rules/run-api.md
GitHubrun() options and coverage additions
New run([options]) options since v24. The versions come from the run()
YAML changes: list unless the table says otherwise:
| Option | Versions | Notes |
|---|---|---|
rerunFailuresFilePath |
v24.7.0 | Same as --test-rerun-failures |
env |
v25.6.0, v24.14.0 | Environment for the test processes. Replaces process.env (verified: PATH is undefined in the child). Throws ERR_INVALID_ARG_VALUE with isolation: 'none' |
randomize, randomSeed |
not in the YAML. Verified on v24.19.0, v26.13.0 and main | Same as --test-randomize/--test-random-seed. randomSeed must be an integer 0..4294967295 and enables randomization by itself |
testTagFilters |
v26.2.0, v24.19.0 | string | string[], ANDed. On v24.19.0 it ran no files at all (see the selection-and-ci rules) |
coverageIncludeAll |
not in the YAML. The CLI flag is v26.7.0 | Verified on v26.13.0 and main. Ignored on v24.19.0 |
forbidOnly |
v27.0.0 | Default: the value of --test-forbid-only. Ignored silently on v24/v26 |
import { run } from 'node:test';
import { spec } from 'node:test/reporters';
run({
files: ['test/a.test.mjs'],
env: { ...process.env, DATABASE_URL: 'postgres://localhost/test_1' }, // merge explicitly
randomSeed: 1234,
forbidOnly: process.env.CI === 'true', // 27+
})
.on('test:fail', () => { process.exitCode = 1; })
.compose(spec)
.pipe(process.stdout);
The stream also has these new events:
'test:log'(v26.6.0, v24.20.0), described in the context-and-observability rules.'test:interrupted'(v25.7.0, v24.15.0), on SIGINT.parentIdon events that carry atestId(v26.3.0, v24.19.0).entryFileon events forwarded from child processes (v26.6.0, v24.20.0).
--test-coverage-include-all (v26.7.0; Stability 1; not on v24)
node --test --experimental-test-coverage --test-coverage-include-all
- Source files under the cwd that no test loaded are added to the report
with 0% coverage. Verified:
unused.mjs | 0.00 | ...appears in the spec coverage table. - The candidates are still filtered by
--test-coverage-includeand--test-coverage-exclude. Test files are excluded by default. - Combine it with
--test-coverage-lines=<n>so that untested files fail the threshold. This replaces the jest/c8collectCoverageFrom/--allidiom. - Coverage itself still needs
--experimental-test-coverage(Stability 1).