Added a Testing Guide and updated the specification in some JS files (#907)

Author: cjyuan

Sprint-3/1-implement-and-rewrite-tests/README.md

@@ -1,5 +1,8 @@
 # Implement solutions and rewrite tests with Jest
 
+Before writing any code, please read the [Testing Function Guide](testing-guide.md) to learn how
+to choose test values that thoroughly test a function.
+
 ## 1 Implement solutions
 
 In the `implement` directory you've got a number of functions you'll need to implement.

Sprint-3/1-implement-and-rewrite-tests/implement/1-get-angle-type.js

@@ -1,63 +1,37 @@
 // Implement a function getAngleType
-// Build up your function case by case, writing tests as you go
-// The first test and case is written for you. The next case has a test, but no code.
-// Execute this script in your terminal
-// node 1-get-angle-type.js
-// The assertion error will tell you what the expected output is
-// Write the code to pass the test
-// Then, write the next test! :) Go through this process until all the cases are implemented
+//
+// When given an angle in degrees, it should return a string indicating the type of angle:
+// - "Acute angle" for angles greater than 0° and less than 90°
+// - "Right angle" for exactly 90°
+// - "Obtuse angle" for angles greater than 90° and less than 180°
+// - "Straight angle" for exactly 180°
+// - "Reflex angle" for angles greater than 180° and less than 360°
+// - "Invalid angle" for angles outside the valid range.
+
+// Assumption: The parameter is a valid number. (You do not need to handle non-numeric inputs.)
+
+// Acceptance criteria:
+// After you have implemented the function, write tests to cover all the cases, and
+// execute the code to ensure all tests pass.
 
 function getAngleType(angle) {
-  if (angle === 90) {
-    return "Right angle";
-  }
-   // Run the tests, work out what Case 2 is testing, and implement the required code here.
-   // Then keep going for the other cases, one at a time.
+  // TODO: Implement this function
 }
 
 // The line below allows us to load the getAngleType function into tests in other files.
 // This will be useful in the "rewrite tests with jest" step.
 module.exports = getAngleType;
 
-// we're going to use this helper function to make our assertions easier to read
-// if the actual output matches the target output, the test will pass
+// This helper function is written to make our assertions easier to read.
+// If the actual output matches the target output, the test will pass
 function assertEquals(actualOutput, targetOutput) {
   console.assert(
     actualOutput === targetOutput,
     `Expected ${actualOutput} to equal ${targetOutput}`
   );
 }
 
-// Acceptance criteria:
-
-// Given an angle in degrees,
-// When the function getAngleType is called with this angle,
-// Then it should:
-
-// Case 1: Identify Right Angles:
-// When the angle is exactly 90 degrees,
-// Then the function should return "Right angle"
+// TODO: Write tests to cover all cases, including boundary and invalid cases.
+// Example: Identify Right Angles
 const right = getAngleType(90);
 assertEquals(right, "Right angle");
-
-// Case 2: Identify Acute Angles:
-// When the angle is less than 90 degrees,
-// Then the function should return "Acute angle"
-const acute = getAngleType(45);
-assertEquals(acute, "Acute angle");
-
-// Case 3: Identify Obtuse Angles:
-// When the angle is greater than 90 degrees and less than 180 degrees,
-// Then the function should return "Obtuse angle"
-const obtuse = getAngleType(120);
-// ====> write your test here, and then add a line to pass the test in the function above
-
-// Case 4: Identify Straight Angles:
-// When the angle is exactly 180 degrees,
-// Then the function should return "Straight angle"
-// ====> write your test here, and then add a line to pass the test in the function above
-
-// Case 5: Identify Reflex Angles:
-// When the angle is greater than 180 degrees and less than 360 degrees,
-// Then the function should return "Reflex angle"
-// ====> write your test here, and then add a line to pass the test in the function above

Sprint-3/1-implement-and-rewrite-tests/implement/2-is-proper-fraction.js

@@ -1,59 +1,33 @@
-// Implement a function isProperFraction
-// Write assertions for your function to check it works in different cases
-// Terms:
-// Fractions: https://www.bbc.co.uk/bitesize/topics/zt9n6g8/articles/zjxpp4j
-// Written here like this: 1/2 == Numerator/Denominator
-// the first test and first case is written for you
-// complete the rest of the tests and cases
-// write one test at a time, and make it pass, build your solution up methodically
+// Implement a function isProperFraction,
+// when given two numbers, a numerator and a denominator, it should return true if
+// the given numbers form a proper fraction, and false otherwise.
+
+// Assumption: The parameters are valid numbers (not NaN or Infinity).
+
+// Note: If you are unfamiliar with proper fractions, please look up its mathematical definition.
+
+// Acceptance criteria:
+// After you have implemented the function, write tests to cover all the cases, and
+// execute the code to ensure all tests pass.
 
 function isProperFraction(numerator, denominator) {
-  if (numerator < denominator) {
-    return true;
-  }
+  // TODO: Implement this function
 }
 
 // The line below allows us to load the isProperFraction function into tests in other files.
 // This will be useful in the "rewrite tests with jest" step.
 module.exports = isProperFraction;
 
-// here's our helper again
+// Here's our helper again
 function assertEquals(actualOutput, targetOutput) {
   console.assert(
     actualOutput === targetOutput,
     `Expected ${actualOutput} to equal ${targetOutput}`
   );
 }
 
-// Acceptance criteria:
+// TODO: Write tests to cover all cases.
+// What combinations of numerators and denominators should you test?
 
-// Proper Fraction check:
-// Input: numerator = 2, denominator = 3
-// target output: true
-// Explanation: The fraction 2/3 is a proper fraction, where the numerator is less than the denominator. The function should return true.
-const properFraction = isProperFraction(2, 3);
-assertEquals(properFraction, true);
-
-// Improper Fraction check:
-// Input: numerator = 5, denominator = 2
-// target output: false
-// Explanation: The fraction 5/2 is an improper fraction, where the numerator is greater than or equal to the denominator. The function should return false.
-const improperFraction = isProperFraction(5, 2);
-assertEquals(improperFraction, false);
-
-// Negative Fraction check:
-// Input: numerator = -4, denominator = 7
-// target output: true
-// Explanation: The fraction -4/7 is a proper fraction because the absolute value of the numerator (4) is less than the denominator (7). The function should return true.
-const negativeFraction = isProperFraction(-4, 7);
-// ====> complete with your assertion
-
-// Equal Numerator and Denominator check:
-// Input: numerator = 3, denominator = 3
-// target output: false
-// Explanation: The fraction 3/3 is not a proper fraction because the numerator is equal to the denominator. The function should return false.
-const equalFraction = isProperFraction(3, 3);
-// ====> complete with your assertion
-
-// Stretch:
-// What other scenarios could you test for?
+// Example: 1/2 is a proper fraction
+assertEquals(isProperFraction(1, 2), true);

Sprint-3/1-implement-and-rewrite-tests/implement/3-get-card-value.js

@@ -1,57 +1,52 @@
 // This problem involves playing cards: https://en.wikipedia.org/wiki/Standard_52-card_deck
 
-// You will need to implement a function getCardValue
-// the function takes a single parameter, a string representing a playing card
-// the function should return the numerical value of the card
-// the first test and first case is written for you
-// complete the rest of the tests and cases
-// write one test at a time, and make it pass, build your solution up methodically
-// just make one change at a time -- don't rush -- programmers are deep and careful thinkers
+// Implement a function getCardValue, when given a string representing a playing card,
+// should return the numerical value of the card.
+
+// A valid card string will contain a rank followed by the suit.
+// The rank can be one of the following strings:
+//   "A", "2", "3", "4", "5", "6", "7", "8", "9", "10", "J", "Q", "K"
+// The suit can be one of the following emojis:
+//   "♠", "♥", "♦", "♣"
+// For example: "A♠", "2♥", "10♥", "J♣", "Q♦", "K♦".
+
+// When the card is an ace ("A"), the function should return 11.
+// When the card is a face card ("J", "Q", "K"), the function should return 10.
+// When the card is a number card ("2" to "10"), the function should return its numeric value.
+
+// When the card string is invalid (not following the above format), the function should
+// throw an error.
+
+// Acceptance criteria:
+// After you have implemented the function, write tests to cover all the cases, and
+// execute the code to ensure all tests pass.
+
 function getCardValue(card) {
-  if (rank === "A") {
-    return 11;
-  }
+  // TODO: Implement this function
 }
 
 // The line below allows us to load the getCardValue function into tests in other files.
 // This will be useful in the "rewrite tests with jest" step.
 module.exports = getCardValue;
 
-// You need to write assertions for your function to check it works in different cases
-// we're going to use this helper function to make our assertions easier to read
-// if the actual output matches the target output, the test will pass
+// Helper functions to make our assertions easier to read.
 function assertEquals(actualOutput, targetOutput) {
   console.assert(
     actualOutput === targetOutput,
     `Expected ${actualOutput} to equal ${targetOutput}`
   );
 }
-// Acceptance criteria:
 
-// Given a card string in the format "A♠" (representing a card in blackjack - the last character will always be an emoji for a suit, and all characters before will be a number 2-10, or one letter of J, Q, K, A),
-// When the function getCardValue is called with this card string as input,
-// Then it should return the numerical card value
-const aceofSpades = getCardValue("A♠");
-assertEquals(aceofSpades, 11);
-
-// Handle Number Cards (2-10):
-// Given a card with a rank between "2" and "9",
-// When the function is called with such a card,
-// Then it should return the numeric value corresponding to the rank (e.g., "5" should return 5).
-const fiveofHearts = getCardValue("5♥");
-// ====> write your test here, and then add a line to pass the test in the function above
-
-// Handle Face Cards (J, Q, K):
-// Given a card with a rank of "10," "J," "Q," or "K",
-// When the function is called with such a card,
-// Then it should return the value 10, as these cards are worth 10 points each in blackjack.
-
-// Handle Ace (A):
-// Given a card with a rank of "A",
-// When the function is called with an Ace,
-// Then it should, by default, assume the Ace is worth 11 points, which is a common rule in blackjack.
-
-// Handle Invalid Cards:
-// Given a card with an invalid rank (neither a number nor a recognized face card),
-// When the function is called with such a card,
-// Then it should throw an error indicating "Invalid card rank."
+// TODO: Write tests to cover all outcomes, including throwing errors for invalid cards.
+// Examples:
+assertEquals(getCardValue("9♠"), 9);
+
+// Handling invalid cards
+try {
+  getCardValue("invalid");
+
+  // This line will not be reached if an error is thrown as expected
+  console.error("Error was not thrown for invalid card");
+} catch (e) {}
+
+// What other invalid card cases can you think of?

Sprint-3/1-implement-and-rewrite-tests/rewrite-tests-with-jest/1-get-angle-type.test.js

@@ -2,25 +2,19 @@
 // We will use the same function, but write tests for it using Jest in this file.
 const getAngleType = require("../implement/1-get-angle-type");
 
-test("should identify right angle (90°)", () => {
-  expect(getAngleType(90)).toEqual("Right angle");
-});
-
-// REPLACE the comments with the tests
-// make your test descriptions as clear and readable as possible
-
-// Case 2: Identify Acute Angles:
-// When the angle is less than 90 degrees,
-// Then the function should return "Acute angle"
+// TODO: Write tests in Jest syntax to cover all cases/outcomes,
+// including boundary and invalid cases.
 
-// Case 3: Identify Obtuse Angles:
-// When the angle is greater than 90 degrees and less than 180 degrees,
-// Then the function should return "Obtuse angle"
-
-// Case 4: Identify Straight Angles:
-// When the angle is exactly 180 degrees,
-// Then the function should return "Straight angle"
+// Case 1: Acute angles
+test(`should return "Acute angle" when (0 < angle < 90)`, () => {
+  // Test various acute angles, including boundary cases
+  expect(getAngleType(1)).toEqual("Acute angle");
+  expect(getAngleType(45)).toEqual("Acute angle");
+  expect(getAngleType(89)).toEqual("Acute angle");
+});
 
-// Case 5: Identify Reflex Angles:
-// When the angle is greater than 180 degrees and less than 360 degrees,
-// Then the function should return "Reflex angle"
+// Case 2: Right angle
+// Case 3: Obtuse angles
+// Case 4: Straight angle
+// Case 5: Reflex angles
+// Case 6: Invalid angles

Sprint-3/1-implement-and-rewrite-tests/rewrite-tests-with-jest/2-is-proper-fraction.test.js

@@ -2,12 +2,9 @@
 // We will use the same function, but write tests for it using Jest in this file.
 const isProperFraction = require("../implement/2-is-proper-fraction");
 
-test("should return true for a proper fraction", () => {
-  expect(isProperFraction(2, 3)).toEqual(true);
-});
-
-// Case 2: Identify Improper Fractions:
+// TODO: Write tests in Jest syntax to cover all combinations of positives, negatives, zeros, and other categories.
 
-// Case 3: Identify Negative Fractions:
-
-// Case 4: Identify Equal Numerator and Denominator:
+// Special case: numerator is zero
+test(`should return false when denominator is zero`, () => {
+  expect(isProperFraction(1, 0)).toEqual(false);
+});

Sprint-3/1-implement-and-rewrite-tests/rewrite-tests-with-jest/3-get-card-value.test.js

@@ -2,12 +2,19 @@
 // We will use the same function, but write tests for it using Jest in this file.
 const getCardValue = require("../implement/3-get-card-value");
 
-test("should return 11 for Ace of Spades", () => {
-  const aceofSpades = getCardValue("A♠");
-  expect(aceofSpades).toEqual(11);
+// TODO: Write tests in Jest syntax to cover all possible outcomes.
+
+// Case 1: Ace (A)
+test(`Should return 11 when given an ace card`, () => {
+  expect(getCardValue("A♠")).toEqual(11);
 });
 
-// Case 2: Handle Number Cards (2-10):
-// Case 3: Handle Face Cards (J, Q, K):
-// Case 4: Handle Ace (A):
-// Case 5: Handle Invalid Cards:
+// Suggestion: Group the remaining test data into these categories:
+//   Number Cards (2-10)
+//   Face Cards (J, Q, K)
+//   Invalid Cards
+
+// To learn how to test whether a function throws an error as expected in Jest,
+// please refer to the Jest documentation:
+// https://jestjs.io/docs/expect#tothrowerror
+