What the agent does
The agent reads how the suite is run before it adds a flag that changes where each file runs. In a package laid out like expressjs/express (5.3.0), package.json declares mocha at ^11.7.5 with no lockfile, because .npmrc sets package-lock=false, and the test script is mocha --require test/support/env --reporter spec --check-leaks test/ test/acceptance/. test-ci wraps that in nyc for coverage and test-tap swaps the reporter. The suite is 71 spec files under test/ plus 18 under test/acceptance/ for the examples, 1,159 it() calls in all, and test/support/env.js is two lines: NODE_ENV = 'test' and NO_DEPRECATION = 'body-parser,express'. CI in .github/workflows/ci.yml runs npm run test-ci on 18 matrix rows, Node 18 through 26 on Ubuntu and Windows, and merges the lcov.info from each.
Then it looks for what parallel mode breaks, because Mocha's --parallel runs each file in a worker process and changes three things. Root-level hooks must become a root hook plugin, and the agent finds none: every before and after sits inside a describe. State set through process.env leaks only within a process, and the three describe blocks in test/app.js that set NODE_ENV to development, production and empty restore it in after, so they are safe as long as they stay in one file. The four this.timeout(5000) calls in test/Route.js and test/Router.js are per-test and carry over. --require test/support/env is applied in every worker, so the two environment variables still hold. Every server in the suite listens on port 0, including test/app.listen.js, so workers cannot collide on a port. What does change is the reporter: spec output in parallel mode arrives file by file as each worker finishes, and .only is not supported, which is a reason to prefer it in CI since forbidOnly is not configured here.
The change is one flag in two scripts. test and test-tap gain --parallel, and test-ci is left alone since it only wraps npm test; nyc instruments worker processes through the same spawn hook it uses for any child, so coverage still arrives per matrix row. The agent does not set --jobs: Mocha defaults to one fewer than the machine's cores, which fits both the 4-core Ubuntu runners and the agent's own sandbox, and a fixed number would be wrong on one of them. A .mocharc.yml is not added, because the repository keeps its options in package.json and a second place for them is a drift waiting to happen.
The proof is a timing from the suite's own command. The agent runs npm test serially and with --parallel in its sandbox, each twice, and reads the wall-clock time and the pass count from Mocha's summary, which must be the same 1,159 passing either way. It then runs npm run test-ci once with the flag to confirm nyc still prints a coverage table with the same line counts as a serial run, since a worker whose coverage is lost shows up there as a drop. Any test that passes serially and fails in parallel is reported in the pull request with its file and the likely shared state, not patched, because a hidden order dependency is a finding for the maintainer.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Run the Mocha suite in parallel. Read package.json, .npmrc, test/support/env.js, .github/workflows/ci.yml, and every file under test/ and test/acceptance/ first, and list anything that assumes one process: root-level hooks, process.env writes, fixed ports, .only calls, or shared module state. Add --parallel to the test and test-tap scripts, leave test-ci wrapping npm test, and do not fix --jobs. Run the suite serially and with --parallel twice each in your sandbox and record the wall-clock time and pass count from Mocha's summary, then run test-ci once to confirm nyc still reports the same coverage. Report any test that fails only in parallel with its file instead of changing it. Run npm run lint and open a pull request that quotes the timings, the pass counts and the coverage table.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request that changes two lines of package.json and nothing else. Its description lists what the agent checked for one-process assumptions and what it found, the serial and parallel timings from four runs with their pass counts, the nyc coverage table from a parallel test-ci run beside a serial one, and the lint output.
The run's record keeps every Mocha summary and the coverage tables, so a reviewer can compare the 1,159 passing line by line rather than trust a percentage.
Before merging, a reviewer decides whether the Windows rows of the CI matrix should keep the flag, since worker processes start more slowly there and the gain may not cover the cost, and whether to add --jobs for the Windows runners only. The pull request shows the Ubuntu timings from the sandbox and says the Windows ones were not measured.
Run it on every CI job that takes longer than it should
A handler on your server that receives a workflow run's completion can compare its duration with the previous week and start one run with this body when the test job crossed a threshold, with the repository in resources and a request_id that is a UUID v5 of the workflow run id, so a redelivered event returns the run already started. The key's webhook_url carries the pull request's session when the run finishes.
For a monorepo of Node packages, a script starts one run per package directory in parallel, each with its own input naming the directory, and reads each session's result. A package whose suite already runs in parallel, or whose tests share a database, gets a pull request that explains why the flag was not added instead of a broken one.
The use case this job follows, with its automation and trigger: Write the missing tests.
Why run it on Rush?
Adding --parallel is one word; knowing whether it is safe means reading 89 test files for shared state and then timing the suite twice on a machine nobody else is using. The agent does the reading, runs the suite four times in its own sandbox and once more under nyc, and keeps every summary, so the pull request carries evidence instead of a hunch.
The same job on ten packages is ten sandboxes at once, each with its own timings, and a reviewer sees ten small pull requests whose numbers were measured rather than copied.
Frequently asked questions
Does --check-leaks still work in parallel mode?
Yes. Leak checking compares the global object before and after each test inside the process the test runs in, and in parallel mode that is the worker, so a test that leaves a global behind is still reported, with its file.
Why not set --jobs to match the CI runner?
Because the runner's core count differs between Ubuntu and Windows rows and from a laptop, and Mocha's default of cores minus one adapts to each. A fixed --jobs would be tuned for one row and wrong for the rest.
What happens to the spec reporter's output?
Each file's block prints when that file's worker finishes, so the order of files changes between runs while the content of each block does not. The final summary, with its pass and fail counts and timing, is unchanged, and test-tap behaves the same way with TAP lines.
Will nyc lose coverage from worker processes?
No. nyc wraps node so that every child process it spawns is instrumented, and Mocha's workers are ordinary child processes. The agent confirms it by comparing the coverage table from a parallel test-ci run with a serial one in the pull request.