Node.js Integration Tests That Exercise the Real Process

A route validator can reject a duplicate route and still leave CI convinced the build passed. The function throws, the command catches it and prints a perfectly helpful error, then the process exits with status 0. The caller gets a green tick and goes looking for a report that was never written.
A unit test calling the validator is useful here. It tells you the duplicate really is rejected. The next test needs to run the command that CI runs and watch what comes back. I put a small catalogue validator together to check its arguments, exit status, both output streams, and the JSON file the next step would read.
Decide What the Caller Gets
The validator takes a JSON file containing route paths and writes a report. The rules fit in a pure function. It checks the path format, rejects a duplicate, and keeps the accepted routes in their original order. Four short unit tests cover those rules. The command has a few more duties:
- On success, it writes the report, prints a JSON count on stdout, and exits with status
0. - An invalid catalogue or a failed file operation produces a diagnostic on stderr and status
1. - The wrong number of arguments prints usage on stderr and returns status
2.
The specimen has one optional environment variable, ROUTE_CATALOGUE. Leave it out and the report uses local, with a warning on stderr. The command still succeeds. That makes a useful test because a shell, or a CI console merging both streams, can make a warning look just like part of the result.
The built‑in test runner became stable in Node.js 20.0.0, and I'm using 20.6.1 here. The lab uses the runner, assertions, filesystem, and subprocess APIs that ship with Node.
Run the Same Entry Point as CI
I use spawn() to run the real entry point, passing each argument separately and leaving the shell disabled. process.execPath is the Node executable already running the test, so the child uses the same installation. The command receives a disposable working directory and an explicit environment. If a test needs the default catalogue name, it passes an empty environment to make that choice visible.
My first subprocess test gives the command two filenames with spaces and punctuation. It copies the input into the test directory, then invokes the command with relative paths. That exercises the working directory and argument handling at the same time. It also gives me a reason to inspect the file the command actually wrote. Here's the assertion from that test, with the directory and fixture already set up:
const result = await run(cwd, [input, output], { ROUTE_CATALOGUE: 'main catalogue' });
assert.deepEqual(result, {
code: 0,
signal: null,
stdout: '{"routeCount":3}\n',
stderr: '',
launchError: null,
timedOut: false,
});
assert.deepEqual(await readReport(join(cwd, output)), {
catalogue: 'main catalogue',
routes: expectedRoutes,
});The helper reads stdout and stderr separately and settles on the child's close event. An exit handler can know the status before the output streams close. Waiting for close lets the test make assertions about the finished output. On the command side, setting process.exitCode gives pending writes a chance to finish before Node exits naturally.
Check the Result That the Next Step Needs
For the first test, the count is machine‑readable and the report must contain the three expected routes. A command could print a convincing count whilst missing the write altogether. Conversely, a report could exist from a previous run. The invalid‑input tests start with two different filesystem states. One checks that no report appears in a fresh directory. The other puts an existing report there and checks that rejected input leaves it alone.
I also ran three deliberate changes in disposable copies of the command:
| Change | What the test caught |
|---|---|
The error handler sets the exit status to 0. | The duplicate‑route case expected status 1 and received 0. |
| The catalogue warning moves from stderr to stdout. | Parsing stdout as JSON failed even though the command still succeeded. |
| The report write is removed. | The exit status and summary were correct. Reading the expected report failed with ENOENT. |
Those changes touch the entry point. The validation rules are identical in each copy. The regression script runs the relevant test and checks its failure reason, so a broken test path or a command that never starts can't count as a detection.
Give Failed Commands Somewhere to Stop
A missing executable and a running command that rejects its input are different failures. In the first case the harness records a launch error, ENOENT. In the second, there's an actual status from the validator. The deadline test starts a separate fixture that prints its process ID and keeps running. When the deadline expires, the helper terminates the immediate child. On the macOS test machine, the result had a null exit code and a SIGKILL signal, and the fixture's process ID was gone after close.
Each process test registers its own directory for removal with t.after(). Two concurrent invocations can use the same input and output filenames and still write two different reports. The regression script also checks that the test directory is gone after the deliberately failing assertion. The full suite passed all 15 checks on Node.js 20.6.1. The helper buffers the small amounts of output in this lab and only supervises one immediate child. Managing a whole process tree or collecting verbose build logs would call for a different helper.
My Node.js process integration test lab has the command, fixtures, tests, and all three regression controls. Try running the normal tests and then removing just the report write. It's a small change, and the terminal will still tell you how many routes it checked. The test tells you whether the next step has anything to read.
A command like this often sits between other JavaScript build tools. Look at what the next step expects to receive. That gives you a better starting point for the test than whatever the command happens to print on a good day.
Postscript
November 2026: Node's test runner has since gained Date mocking, and its timer‑mocking API became stable in Node 23.1.0. That's useful for testing expiry and retry logic without waiting. Those mocks stay in the test process, though; they don't advance the clock in a command launched with spawn(). I've kept real deadlines in this lab so a hanging child still gets stopped, however quickly the parent thinks time is passing.