What the agent does
The agent clones the repository into its own sandbox and starts from what already exists, not from a blank test folder. In hagopj13/node-express-boilerplate, package.json runs jest -i --colors --verbose --detectOpenHandles for test and jest -i --coverage for coverage, with Jest 26.6.3 in yarn.lock. jest.config.js sets testEnvironment: 'node', restoreMocks: true, and leaves src/config, src/app.js and tests out of coverage. The suite has integration tests for auth, users and docs under tests/integration, and unit tests for the toJSON and paginate plugins, the user model and the error middleware under tests/unit, with fixtures in tests/fixtures and a setupTestDB helper that connects Mongoose and empties every collection before each test.
Integration tests need MongoDB, and the sandbox has no Docker, so the agent does not use docker-compose.test.yml. It installs MongoDB from MongoDB's own apt repository, starts mongod, copies .env.example to .env (the config is validated by Joi at load, and MONGODB_URL, NODE_ENV and JWT_SECRET are required), and runs yarn coverage. Because config.js appends -test to the database name when NODE_ENV is test, the tests never touch the development database. The coverage table is the work list: which files and which branches no test executes today.
In this repository that list starts with code that only integration tests reach, or nothing does. src/middlewares/validate.js picks params, query and body from a Joi schema, validates with abortEarly: false, joins every message with a comma into a 400 ApiError, and on success copies the converted values back onto req, so a query string limit becomes a number. src/validations/custom.validation.js has objectId, which accepts exactly 24 hex characters, and password, which needs eight characters with at least one letter and one number. src/utils/pick.js copies only own properties. src/services/token.service.js signs JWTs with sub, iat, exp and type, and verifyToken throws Token not found for a blacklisted or missing token even when the signature is valid.
The new tests go under tests/unit beside the existing ones and follow their style: describe blocks per module, node-mocks-http for requests and responses as in tests/unit/middlewares/error.test.js, and jest.spyOn(emailService.transport, 'sendMail') for email, the way tests/integration/auth.test.js already does, so no SMTP server is needed. Token tests that save tokens use setupTestDB and the real database rather than mocking Mongoose. The agent runs yarn test until every test passes, then yarn coverage again, and yarn lint, since .eslintrc.json extends airbnb-base with the Jest plugin.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Write Jest unit tests for the modules this Express API's tests do not cover. Read package.json, jest.config.js, .env.example, src/config/config.js, tests/utils/setupTestDB.js and every existing test first, and follow their style. Install and start MongoDB in the sandbox, copy .env.example to .env, and run yarn coverage to list the files and branches no test executes. Write tests under tests/unit for the gaps, starting with src/middlewares/validate.js, src/validations/custom.validation.js, src/utils/pick.js and src/services/token.service.js. Use node-mocks-http for middleware, spy on emailService.transport.sendMail instead of sending email, and use setupTestDB with the real database instead of mocking Mongoose. Do not change code under src; list anything that looks wrong as a finding. Run yarn test, yarn coverage and yarn lint until they pass, and put the coverage table before and after in the pull request. 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 that adds files under tests/unit and changes nothing in src. For this repository that means new test files for validate, the custom Joi validators, pick and the token service, each next to the existing unit tests in the same folder layout. The description has the yarn coverage table from before and after, so a reviewer sees which lines and branches the new tests reach, and lists any finding the agent made instead of fixing it.
The session transcript keeps every command: installing MongoDB, the first coverage run, each yarn test run including the failures while tests were written, yarn lint, and the final coverage. The repository's .travis.yml describes the CI it was built for, MongoDB as a service, yarn lint and yarn test; whatever CI your fork actually runs shows its checks on the pull request.
Before merging, a reviewer checks that the validate tests assert the converted values and not only the absence of an error, that token tests clean up through setupTestDB rather than relying on order, and that no test mocks a module from src that it could exercise for real.
Run it on every night, on a schedule
One run closes the biggest gaps; keeping coverage from sliding back is a nightly job. An automation in the Project that holds the repository, with a prompt like this one narrowed to "the least covered file changed in the last week" and a schedule trigger whose cron is 0 2 * * * in your timezone, starts one run each night and opens at most one pull request.
The automation's max_runs_per_hour caps how many runs it can start, and each run uses the member who last changed the automation, so the tests and their cost are attributed to a person on the team.
The use case this job follows, with its automation and trigger: Write the missing tests.
Why run it on Rush?
This suite needs a MongoDB server, a valid .env and Jest run in band with -i, and the integration tests empty every collection before each test. That is fine in CI and unpleasant on a laptop where the same server holds someone's development data. In a Rush sandbox the agent installs and starts its own mongod, runs coverage against an empty -test database, and throws the whole machine away afterwards.
The coverage table is the proof. The transcript holds the first yarn coverage that chose the work, every test run, and the final table, so the pull request does not just claim more tests, it shows which branches of validate.js and token.service.js now run.
Frequently asked questions
Will it mock Mongoose to avoid needing a database?
No. Tests that touch models use the repository's own setupTestDB against a real MongoDB in the sandbox. Mocks are kept to what the existing tests already mock, such as the email transport.
Does it upgrade Jest from version 26?
No. The tests are written for the Jest the lockfile has, 26.6.3, so the pull request is only tests. Moving to a newer Jest is a separate run, because it changes configuration and sometimes snapshot formats.
Will it change application code to make it testable?
Not in this request. The prompt says to leave src alone and to report anything that looks wrong. If a module cannot be tested without a change, the pull request says so and you can ask for the change in a follow-up.
Can it raise a coverage threshold once the tests are in?
Yes, in a follow-up. jest.config.js has no coverageThreshold today; ask the agent to add one at the level the new tests reach. Jest checks thresholds only when it collects coverage, so the same follow-up can make CI run yarn coverage instead of yarn test.
More Jest jobs
The same job on other stacks
- Write the Missing Jest Tests for a Koa API (Koa)
- Write Unit Tests for a LangChain.js App (LangChain.js)
- Write Unit Tests for a Laravel Project (Laravel)