What the agent does
The agent reads how coverage is produced before it sets a floor. In a package laid out like expressjs/express (5.3.0), package.json runs the suite with mocha --require test/support/env --reporter spec --check-leaks test/ test/acceptance/, the spec files under test/ plus the 18 under test/acceptance/ for the examples/, and wraps it twice with nyc ^17.1.0: test-ci with --reporter=lcovonly --reporter=text and test-cov with --reporter=html --reporter=text, both passing --exclude examples --exclude test --exclude benchmarks on the command line. There is no .nycrc, and .npmrc sets package-lock=false, so there is no lockfile to move. .gitignore already ignores .nyc_output and coverage.
It then reads where the number is used. .github/workflows/ci.yml runs npm run test-ci on a matrix of Ubuntu and Windows across Node 18 to 26, uploads each coverage/lcov.info, and a coverage job merges the 18 files with lcov and sends the result to Coveralls. The text reporter prints a table in each row and nothing reads it; a change that drops a file's coverage to zero still passes. The thresholds therefore have to hold on every row, not on the merged file, which is where the Windows rows matter.
The agent moves the three --exclude flags into a new .nycrc so test-ci and test-cov share one configuration, and adds check-coverage: true with statements, branches, functions and lines. The figures come from its own npm run test-cov on Linux, each set a few points under what the table shows, with the widest margin on branches. nyc reports a miss as ERROR: Coverage for lines (…%) does not meet global threshold (…%) and exits non-zero after the tests, so a failing threshold shows up as a red row with the suite itself green above it.
What it cannot do in a Linux sandbox is run the Windows rows, and coverage can differ between operating systems when a test skips on one of them, so it says so: the pull request names the margin it left for them and asks the reviewer to read the Windows rows of the first CI run before raising anything. It proves the check fires by raising one figure above the measurement for a run, quoting the does not meet line and the exit code, then restoring it. npm run lint runs last, since .eslintrc.yml governs the repository and the new file is JSON.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add coverage thresholds to this package's Mocha suite with nyc. Read package.json, .npmrc, .github/workflows/ci.yml, test/support/env.js and .gitignore first. Run npm install and npm run test-cov, read the coverage table, and create a .nycrc that holds the existing exclude list and check-coverage with statements, branches, functions and lines set a few points under the measured figures, with the widest margin on branches. Remove the --exclude flags from the test-ci and test-cov scripts so .nycrc is the one configuration. Do not change any test. Prove the check fires by raising one threshold above the measurement for one run, quote the failure, and restore it. Note in the pull request that the Windows rows were not run. Run npm run lint and open a pull request.",
"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 with two files: .nycrc, new, holding the exclude list and the four thresholds, and package.json, where test-ci and test-cov lose their three --exclude flags and keep their reporters. No test changes, and with package-lock=false in .npmrc there is no lockfile to update.
The description quotes the coverage table from the agent's test-cov run, the four thresholds beside the figures they came from, and the deliberate failure with the does not meet global threshold line and nyc's exit code. It says plainly that the measurement is from one Linux run and that the Windows rows in ci.yml should be read before any figure moves up.
Before merging, a reviewer watches the first CI run across the matrix. If a Windows row lands under a threshold, the fix is the figure in .nycrc, not a test, and the margin the agent left is meant to make that rare.
Run it on every merged pull request
A threshold earns its keep when it rises. An automation with a github trigger on pull_request.closed.merged starts a run that executes npm run test-cov on the merged branch, compares the table with .nycrc, and opens a pull request raising any figure the suite now clears by more than the margin, with the table in the description and the Windows caveat repeated.
The trigger adds the merged pull request after the prompt. When nothing has risen, no pull request opens.
The use case this job follows, with its automation and trigger: Write the missing tests.
Why run it on Rush?
The number has to be measured before it is set, and measured on a run that uses the same nyc flags as CI. In a sandbox the agent installs with the repository's .npmrc, runs the suite once with coverage, and sets the floor from what it read, instead of a round number that fails on the first push.
The run's record holds the table, the deliberate failure and the lint, so a reviewer reads nyc's own output. Across a team's Mocha packages the same request runs at once, one sandbox and one .nycrc each, every floor measured from its own suite.
Frequently asked questions
Why a .nycrc rather than flags in package.json?
Because two scripts carried the same three --exclude flags and a threshold would make it eight. One file holds the excludes and the thresholds, both scripts read it, and nyc on a laptop behaves as it does in CI.
Does the threshold apply to the merged Coveralls number?
No. nyc checks each run, so each of the 18 matrix rows checks its own coverage, and the merged lcov.info the coverage job uploads is reported, not checked. That is why the figures stay under the lowest row.
Will a failing threshold hide a failing test?
No. Mocha runs first and its result is printed in full; nyc checks coverage after and adds its ERROR line. A row with a red test and a missed threshold shows both.
Why not per-file thresholds?
nyc supports per-file: true, but a file with a few lines moves by whole points on one branch. The agent sets global figures and mentions per-file in the description for a team that wants it later.