Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/maintainers_guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,13 +15,13 @@ All you need to work with this project is a supported version of [Node.js](https

#### Unit Tests

This package has unit tests for most files in the same directory the code is in with the suffix `.spec` (i.e. `exampleFile.spec.ts`). You can run the entire test suite using the npm script `npm test`. This command is also executed by GitHub Actions, the continuous integration service, for every Pull Request and branch. The coverage is computed with the `codecov` package. The tests themselves are run using the `mocha` test runner.
This package has unit tests for most files in the same directory the code is in with the suffix `.spec` (i.e. `exampleFile.spec.ts`). You can run the entire test suite using the npm script `npm test`. This command is also executed by GitHub Actions, the continuous integration service, for every Pull Request and branch. Coverage is collected with Node.js's built-in test coverage support and uploaded by CI. The tests themselves are run using Node.js's built-in test runner.

Test code should be written in syntax that runs on the oldest supported Node.js version. This ensures that backwards compatibility is tested and the APIs look reasonable in versions of Node.js that do not support the most modern syntax.

#### Debugging

A useful trick for debugging inside tests is to use the Chrome Debugging Protocol feature of Node.js to set breakpoints and interactively debug. In order to do this you must run mocha directly. This means that you should have already linted the source (`npm run lint`), manually. You then run the tests using the following command: `./node_modules/.bin/mocha test/{test-name}.js --debug-brk --inspect` (replace {test-name} with an actual test file).
A useful trick for debugging inside tests is to use the Chrome Debugging Protocol feature of Node.js to set breakpoints and interactively debug. In order to do this you should have already linted the source (`npm run lint`), manually. You can then run a specific test file with Node.js's test runner, for example: `node --inspect-brk --import tsx --test test/unit/{test-name}.spec.ts` (replace `{test-name}` with an actual test file path).

#### Local Development

Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/ci-build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ jobs:
uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2 # v6.0.0
with:
token: ${{ secrets.CODECOV_TOKEN }}
directory: coverage
files: coverage/lcov.info
fail_ci_if_error: true
verbose: true
notifications:
Expand Down
13 changes: 9 additions & 4 deletions .vscode/launch.json
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,19 @@
"type": "node",
"request": "launch",
"name": "Spec tests",
"program": "${workspaceFolder}/node_modules/mocha/bin/_mocha",
"runtimeExecutable": "node",
"stopOnEntry": false,
"args": ["--config", ".mocharc.json", "--no-timeouts", "src/*.spec.ts", "src/**/*.spec.ts"],
"args": [
"--inspect-brk",
"--import",
"tsx",
"--test",
"test/unit/**/*.spec.ts"
],
"cwd": "${workspaceFolder}",
"runtimeExecutable": null,
"env": {
"NODE_ENV": "testing",
"TS_NODE_PROJECT": "tsconfig.test.json"
"TSX_TSCONFIG_PATH": "tsconfig.test.json"
},
"skipFiles": ["<node_internals>/**"]
}
Expand Down
8 changes: 4 additions & 4 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,8 @@ npm test # Full pipeline: build -> lint -> type tests -> unit test
npm run build # Clean build (rm dist/ + tsc compilation)
npm run lint # Biome check (formatting + linting)
npm run lint:fix # Biome auto-fix
npm run test:unit # Unit tests only (mocha)
npm run test:coverage # Unit tests with coverage (c8)
npm run test:unit # Unit tests only (Node.js test runner)
npm run test:coverage # Unit tests with built-in Node.js coverage
npm run test:types # Type definition tests (tsd)
npm run watch # Watch mode for development (rebuilds on src/ changes)
```
Expand Down Expand Up @@ -171,9 +171,9 @@ test/types/ # tsd type tests
### Test Conventions

- **Test files** use `*.spec.ts` suffix
- **Assertions** use chai (`expect`, `assert`)
- **Assertions** in tests use direct `node:assert/strict` and `sinon.assert` imports
- **Mocking** uses sinon (`stub`, `spy`, `fake`) and proxyquire for module-level dependency replacement
- **Test config** in `test/unit/.mocharc.json`
- **Test config** lives in `package.json` scripts plus direct `node:test` imports in the spec files
- **Where to put new tests:** Mirror the source structure. For `src/Foo.ts`, add `test/unit/Foo.spec.ts`. For `src/receivers/Bar.ts`, add `test/unit/receivers/Bar.spec.ts`.

### CI
Expand Down
Loading