What the agent does
The agent starts by counting what the suite asks of Mocha, because that decides the size of the job. In a library like forwardemail/supertest there is no .mocharc; every option is in the test script of package.json: nyc --reporter=html --reporter=text mocha --exit --require should --reporter spec --check-leaks. Three files under test/ hold 137 tests, and a fourth, test/throwError.js, is a helper that must stay out of the new runner's include. The count that matters is this one: 125 of the 137 tests take a done argument and finish by calling it, 82 in test/supertest.js, 39 in test/cookies.js and 4 in test/issue-fixes.js. There is one before hook and one this.timeout(5000).
The first Vitest run shows why that count matters. With globals: true and nothing else changed, Vitest collects two of the three files and reports 47 tests passed and 2 failed. The 47 are not real. Vitest passes its own test context as the first argument, the test function returns at once, and the test is marked passed before any request has been answered. The calls to done arrive later and surface as unhandled errors reading done() callback is deprecated, use promise instead. The third file never loads, on before is not defined, and the timeout line fails with Cannot read properties of undefined (reading 'timeout'). An agent that looked only at the green count would ship a suite that asserts nothing.
So the conversion is deliberate. The agent adds one small helper that runs a callback-style function as a promise, resolving on done() and rejecting on done(err), and wraps the 125 test functions in it with a syntax-tree edit, so no assertion line is touched. Rewriting each test to return its request would be cleaner, and the agent offers it as a follow-up, but it changes the body of every test and is far harder to review. before becomes beforeAll, the timeout moves to { timeout: 5000 } on that test, and --require should becomes a setup file. proxyquire and nock need nothing, because the tests load the library through require and Node, not Vite, loads it.
After that the same 137 tests pass in 3 files. The agent then checks what Mocha's flags were doing. --exit is unnecessary: the run ends by itself. --check-leaks has no Vitest equivalent, and the pull request says so. For coverage the agent tries both providers and reports a trap: the Istanbul provider instruments files in Vite's transform, which code loaded through require never goes through, so it reports 0 percent for every file; the V8 provider reports figures within two points of nyc's. Finally it reads engines.node of the Vitest it installed. When this page was written that was ^22.12.0 || ^24.0.0 || >=26.0.0 for Vitest 5.1.0, while .github/workflows/ci.yml tests Node 18, 20, 22 and 24.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Migrate this repository's tests from Mocha to Vitest. First read package.json, any .mocharc file, every file under test/, and .github/workflows. List every Mocha feature in use with counts: tests and hooks that take a done callback, before and after hooks, this.timeout, this.skip, this.retries, --require modules, --check-leaks, --exit, reporters, and helper files in the test directory that are not tests. Run the existing suite and record files, tests and coverage. Add a Vitest config with globals enabled, the node environment, an include that matches only real test files, and a setup file for anything Mocha loaded with --require. Run it once before converting anything and report the result honestly: if tests that take done are reported as passed, say that they did not run their assertions. Convert callback-style tests so that done() resolves and done(err) rejects, without changing any assertion; use a syntax-aware edit, not a regular expression. Rename before and after to beforeAll and afterAll, and move this.timeout values to the test's timeout option. Break one assertion inside a request callback on purpose, confirm the run fails, and restore it. Replace the coverage command with a Vitest coverage provider, confirm it reports the library's files with non-zero figures, and keep the lcov output where the workflow's upload step finds it. Read engines.node of the installed Vitest and compare it with every Node version in the workflow matrix; if any version is not covered, do not edit the matrix, and state the options. Remove mocha and packages nothing else uses. The final run must show the same number of tests as the Mocha baseline. Open a pull request with both totals, the feature counts, and what has no Vitest equivalent.",
"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
A pull request with a vitest.config, a setup file, one helper, the scripts and devDependencies in package.json changed, and the lockfile updated. The test files change in a narrow way: an import of the helper at the top and a wrapper around each callback-style test. In a suite like the one above that is 125 wrapped functions, one renamed hook and one moved timeout, and the description states that no line containing an assertion was edited.
The description puts three runs next to each other: Mocha before, Vitest before conversion with its false passes called out, and Vitest after. It includes the deliberate failure, because the way a failure reads has changed. Under Mocha, an assertion that throws inside a request callback fails the test at once as an uncaught assertion error. Under Vitest with the helper, the same throw is listed under unhandled errors and the test itself fails on its timeout five seconds later. The run still exits non-zero, but whoever reads CI output needs to know where to look.
Three decisions come back as questions. The Node matrix, since the installed Vitest may not run on every version the workflow tests. The leak check, which is dropped unless the maintainers want a replacement. And coverage, where a V8-based figure is not the same measurement as nyc's and whatever compares it against history will see a step.
Run it on every repository still on Mocha
A runner migration happens once per repository, when someone decides to do it. A developer sends this body to POST /o/{org}/sessions from a terminal or through the MCP server, with a request_id that is a UUID made once for the job, and goes back to other work. The pull request is on the session when the run completes. A question the agent ends on, such as which Node versions to keep, is answered with a follow-up to POST /o/{org}/sessions/{id}/messages, which wakes the same sandbox with the dependencies still installed.
A team with many packages on the same setup sends the body once per repository from a script, each with a request_id that is a UUID v5 of the repository's full name. The key runs a few at once and queues the others, and its webhook_url receives run.completed for each run it started. The feature counts in each description show which repositories are a config swap and which have a hundred callbacks to wrap.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The dangerous moment in this migration is a green run that means nothing, and catching it takes patience more than skill: run the old suite, run the new one, compare counts, break a test on purpose, run again. In its own sandbox the agent does all of it, and each command with its full output stays in the transcript at GET /o/{org}/sessions/{id}/messages. A reviewer can read the false-pass run and the deliberate failure for themselves.
It is also long, mechanical work with one or two surprises in it, which is what gets abandoned halfway on a laptop branch. Handed off, it runs while the developer does something else, and what comes back is a pull request with the surprises written down and the decisions that belong to people left open.
Frequently asked questions
Does Vitest support Mocha's done callback?
No. Vitest expects a test to return a promise or be an async function, and it passes a context object where Mocha passed done. A test written for Mocha therefore returns immediately and can be counted as passed. The agent wraps each such test so the promise settles when done is called, which keeps the test body as it was.
Will proxyquire, sinon and nock still work?
In a CommonJS project, usually yes. They patch Node's module loader and HTTP layer, and tests that require the code under test still go through Node. In forwardemail/supertest all three keep working unchanged. A project that moves its tests to ES import at the same time would need vi.mock in place of proxyquire, which is a separate change.
Why does coverage show 0 percent after the switch?
Because of how the files are loaded. The Istanbul provider adds its counters while Vite transforms a file, and a file pulled in with require skips that step. The V8 provider reads coverage from the engine and sees every file that ran. The agent checks for non-zero figures before it keeps a provider.