use jest for testing (#108)

use jest instead of nodejs test runner since jest just has way better
coverage reporting and is the common tool to test nodejs apps. Perhaps
nodejs test runner will be added back again when things change and it
becomes majorly adopted.

Author: xddq

.github/workflows/test.yaml

@@ -20,4 +20,4 @@ jobs:
       - name: Install Dependencies
         run: yarn --immutable
       - name: Test
-        run: npm test
+        run: yarn test

.gitignore

@@ -137,3 +137,4 @@ bundle
 dist
 node_modules
 TODO
+.envrc

README.md

@@ -20,14 +20,12 @@ running with a new project in no time. It provides:
   - compile the codebase from ts to js
   - check for formatting issues
   - check for linting issues
-- Testing via the new Node.js [test
-  runner](https://nodejs.org/api/test.html#test-runner) instead of something
-  like mocha or jest.
+- Testing via [jest](https://www.npmjs.com/package/jest)
 - Formatting via [prettier](https://prettier.io/).
 - Linting via [eslint](https://eslint.org/) and
   [typescript-eslint](https://typescript-eslint.io/)
 - Bundling via [esbuild](https://esbuild.github.io/), a fast bundler that "just
-  works" and is nowadays even used in the typescript codebase.
+  works".
 - Debugging set up with examples for vscode and vim.
 - Automated dependency updates via
   [renovate](https://github.com/renovatebot/renovate).
@@ -105,8 +103,10 @@ attribute.
   only invoked by the CI/CD pipeline.
 - `yarn start` -> Runs the code. This only works if the code was bundled before ;).
 - `yarn test` -> Tests your codebase. Basic tests are created for both major
-  approaches of putting tests beside the source code as well as putting tests in
-  a seperate folder.
+  common approaches of putting tests beside the source code as well as putting
+  tests in a separate folder.
+  - You can inspect the code coverage in depth by running `npx http-server
+./coverage/lcov-report` and then browsing http://localhost:8080.
 
 ## Debugging
 

babel.config.cjs

@@ -0,0 +1,12 @@
+module.exports = {
+  presets: [
+    ["@babel/preset-env", { targets: { node: "current" } }],
+    "@babel/preset-typescript",
+  ],
+  // required for easily mocking module exports.
+  // see: https://stackoverflow.com/questions/67872622/jest-spyon-not-working-on-index-file-cannot-redefine-property
+  assumptions: {
+    constantReexports: true,
+  },
+  plugins: [],
+};

jest.config.cjs

@@ -0,0 +1,36 @@
+//@ts-check
+/**
+ * For a detailed explanation regarding each configuration property, visit:
+ * https://jestjs.io/docs/configuration
+ */
+
+/** @type {import('jest').Config} */
+const config = {
+  // Automatically clear mock calls, instances, contexts and results before every test
+  clearMocks: true,
+  // Indicates whether the coverage information should be collected while executing the test
+  collectCoverage: true,
+  coverageReporters: ["lcov", "text"],
+  collectCoverageFrom: [
+    "**/*.ts",
+    "!**/node_modules/**",
+    "!**/dist/**",
+    "!**/*.d.ts",
+  ],
+  // The directory where Jest should output its coverage files
+  coverageDirectory: "coverage",
+  // Indicates which provider should be used to instrument code for coverage
+  coverageProvider: "v8",
+  // An array of regexp pattern strings that are matched against all test paths, matched tests are skipped
+  testPathIgnorePatterns: ["/node_modules/", "/dist/"],
+  // Indicates whether each individual test should be reported during the run
+  verbose: true,
+  testMatch: [
+    "**/test/**/*.[jt]s?(x)",
+    "!**/test/util/**/*.[jt]s?(x)",
+    "!**/test/fixture/**/*.[jt]s?(x)",
+    "**/?(*.)+(spec|test).[tj]s?(x)",
+  ],
+};
+
+module.exports = config;

package.json

@@ -38,22 +38,26 @@
     "lint": "eslint . --fix",
     "lint-check": "eslint .",
     "start": "node --enable-source-maps ./bundle/index.js",
-    "test": "glob \"src/**/*.test.ts\" \"test/**\" -c \"tsx --test\""
+    "test": "jest --runInBand ."
   },
   "devDependencies": {
+    "@babel/core": "7.24.5",
+    "@babel/preset-env": "7.24.5",
+    "@babel/preset-typescript": "7.24.1",
+    "@jest/globals": "29.7.0",
     "@tsconfig/node20": "20.1.4",
+    "@types/jest": "29.5.12",
     "@types/node": "20.12.11",
-    "@types/nodemon": "1.19.6",
     "@typescript-eslint/eslint-plugin": "6.21.0",
     "@typescript-eslint/parser": "6.21.0",
     "esbuild": "0.19.12",
     "eslint": "8.57.0",
     "eslint-config-prettier": "9.1.0",
     "glob": "10.3.15",
+    "jest": "29.7.0",
     "nodemon": "3.1.0",
     "prettier": "3.2.5",
     "rimraf": "5.0.7",
-    "tsx": "4.10.2",
     "typescript": "5.4.5"
   },
   "packageManager": "yarn@4.0.2"

src/hello.test.ts

@@ -1,11 +1,12 @@
-import { describe, test } from "node:test";
-import assert from "node:assert/strict";
+import { describe, expect, it } from "@jest/globals";
 import { returnHelloWorld } from "./hello";
 
 describe("unit tests and code side by side", () => {
-  test("returnHelloWorld() - returns 'hello world'", () => {
-    console.log("testing returnHelloWorld()");
-    assert.equal(returnHelloWorld(), "hello world");
-    console.log("Done");
+  describe("when using the returnHelloWorld function", () => {
+    it("returns 'hello world'", () => {
+      console.log("testing returnHelloWorld()");
+      expect(returnHelloWorld()).toBe("hello world");
+      console.log("Done");
+    });
   });
 });

test/index.ts

@@ -1,8 +1,7 @@
-import { describe, it } from "node:test";
-import assert from "node:assert/strict";
+import { describe, it } from "@jest/globals";
 
-describe("tests in seperate folder", () => {
+describe("when having tests in seperate folder", () => {
   it("works", () => {
-    assert.equal(true, true);
+    expect(true).toBe(true);
   });
 });

tsconfig.json

@@ -12,8 +12,8 @@
     "forceConsistentCasingInFileNames": true,
     "declaration": true,
     "sourceMap": true,
-    "resolveJsonModule": true,
+    "resolveJsonModule": true
   },
   "include": ["src", "test"],
-  "exclude": ["dist", "bundle", "node_modules"],
+  "exclude": ["dist", "bundle", "node_modules"]
 }