From 4a4ec4dd774a0c7cc38a2973511062b1bd147b5e Mon Sep 17 00:00:00 2001 From: tukib Date: Sat, 16 Dec 2023 13:12:31 +1300 Subject: [PATCH 1/5] add test contributing docs --- CONTRIBUTING.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 143f753f..0f141ec6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,7 +12,23 @@ Article PRs should be reviewed using the [PR review process here](https://github ### Creating tests -Test files must be within `/src`, with a file name ending in `.test.`, where `` is one of `js` `mjs` `jsx` `ts` `tsx`. +1. For some module `foo.ts`, create a file `foo.test.ts` in the same directory. (Must be within /src) +2. Import required jest utils from `@jest/globals`, and the module to be tested. +3. Use `describe` to log what code is being tested and use `it` to describe a specification of the module. + +```ts +/** @file {criticalMathModule.ts} */ +import { describe, expect, it } from "@jest/globals"; +import { isEven } from "./criticalMathModule"; + +describe("criticalMathModule", () => { + // read as: it checks if numbers are even + it("checks if numbers are even", () => { + expect(isEven(1)).toBe(false); + expect(isEven(4)).toBe(true); + }); +}); +``` ## How to review a code change From 878a7dc84d39df14bb1f3fe601b709159c4b5811 Mon Sep 17 00:00:00 2001 From: tukib Date: Sat, 16 Dec 2023 13:23:54 +1300 Subject: [PATCH 2/5] correct example filename --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0f141ec6..8cca2917 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,7 +17,7 @@ Article PRs should be reviewed using the [PR review process here](https://github 3. Use `describe` to log what code is being tested and use `it` to describe a specification of the module. ```ts -/** @file {criticalMathModule.ts} */ +/** @file criticalMathModule.test.ts */ import { describe, expect, it } from "@jest/globals"; import { isEven } from "./criticalMathModule"; From 2091844fa0e4a3ccf438351e3a761ccf66bc049b Mon Sep 17 00:00:00 2001 From: tukib Date: Sun, 17 Dec 2023 21:34:42 +1300 Subject: [PATCH 3/5] clarifies test file naming instructions --- CONTRIBUTING.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8cca2917..0f125fa9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,7 +12,9 @@ Article PRs should be reviewed using the [PR review process here](https://github ### Creating tests -1. For some module `foo.ts`, create a file `foo.test.ts` in the same directory. (Must be within /src) +1. For some module `foo.ts`, create a file `foo.test.ts` in the same directory. + - Tests must be within `/src`. + - `.tsx` `.mjs` `.jsx` and `.js` are also valid extensions. 2. Import required jest utils from `@jest/globals`, and the module to be tested. 3. Use `describe` to log what code is being tested and use `it` to describe a specification of the module. From 2abbd46f603f77d79ba99837f60cfdff80ac4b7b Mon Sep 17 00:00:00 2001 From: tukib Date: Mon, 18 Dec 2023 17:27:07 +1300 Subject: [PATCH 4/5] revert contributing.md to simpler instructions --- CONTRIBUTING.md | 20 +------------------- 1 file changed, 1 insertion(+), 19 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0f125fa9..143f753f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,25 +12,7 @@ Article PRs should be reviewed using the [PR review process here](https://github ### Creating tests -1. For some module `foo.ts`, create a file `foo.test.ts` in the same directory. - - Tests must be within `/src`. - - `.tsx` `.mjs` `.jsx` and `.js` are also valid extensions. -2. Import required jest utils from `@jest/globals`, and the module to be tested. -3. Use `describe` to log what code is being tested and use `it` to describe a specification of the module. - -```ts -/** @file criticalMathModule.test.ts */ -import { describe, expect, it } from "@jest/globals"; -import { isEven } from "./criticalMathModule"; - -describe("criticalMathModule", () => { - // read as: it checks if numbers are even - it("checks if numbers are even", () => { - expect(isEven(1)).toBe(false); - expect(isEven(4)).toBe(true); - }); -}); -``` +Test files must be within `/src`, with a file name ending in `.test.`, where `` is one of `js` `mjs` `jsx` `ts` `tsx`. ## How to review a code change From 1220a8526df55a501b4c558b1c87499eab07987b Mon Sep 17 00:00:00 2001 From: tukib Date: Mon, 18 Dec 2023 17:36:46 +1300 Subject: [PATCH 5/5] adds instructions for how to create tests --- CONTRIBUTING.md | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 143f753f..e55e5599 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,7 +12,41 @@ Article PRs should be reviewed using the [PR review process here](https://github ### Creating tests -Test files must be within `/src`, with a file name ending in `.test.`, where `` is one of `js` `mjs` `jsx` `ts` `tsx`. +1. For some module `foo.js`, create a file `foo.test.js` in the same directory. + + - `.ts` / `.mjs` / `.js` are all valid extensions. + - `.tsx` / `.jsx` are permitted, though unless the XML syntax is necessary, use `.ts` / `.mjs` instead. + - Tests must be within `/src`. + +2. Import the module to be tested. + + - For TypeScript, Jest utilities are not in global scope, so you will need to import these from `@jest/globals`. + +3. Use Jest's [`expect`](https://jestjs.io/docs/expect), [`it`](https://jestjs.io/docs/api#testname-fn-timeout) and [`describe`](https://jestjs.io/docs/api#describename-fn) to organise and assert the behaviour of the module. A test name should start with a verb, and descriptions should be used to indicate what component is being tested. + +```ts +/** @file criticalMathModule.test.ts */ +import { describe, expect, it } from "@jest/globals"; // only needed for TypeScript +import { isEven, log2 } from "./criticalMathModule"; + +describe("isEven", () => { + it("checks if numbers are even", () => { + expect(isEven(1)).toBe(false); + expect(isEven(4)).toBe(true); + }); +}); + +describe("log2", () => { + it("returns the base-2 logarithm of a number", () => { + expect(log2(1024)).toBeCloseTo(10); + }); + + it("throws an error for non-positive numbers", () => { + expect(log2(0)).toThrow(); + expect(log2(-1)).toThrow(); + }); +}); +``` ## How to review a code change