All jobs

Migrate a JavaScript Library from Jest to Vitest

Yes. The agent swaps the runner and config, converts the CommonJS helpers that Vitest cannot load, and proves the same test count passes before and after.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

How hard a Jest suite is to move depends on how much of Jest it uses, so the agent measures that before it installs anything. In a library like moment/luxon the answer is: very little. jest.config.js sets testEnvironment to node, roots to test, a babel-jest transform, coverage from src/**/*.js into build/coverage, and one setup file, test/setupTests.js, which adds a custom matcher through expect.extend. The 58 test files call test, it, describe and test.each as globals and import nothing from @jest/globals. No file calls jest.fn, jest.mock or fake timers, and there is one inline snapshot. On paper that is a config swap.

The agent takes the baseline exactly as CI does, and here that detail decides everything. .github/workflows/test.yml runs the suite with TZ: America/New_York and LANG: en_US.utf8, and scripts/test sets the same two variables. With them, Jest passes 1,222 tests. In a sandbox left on UTC, 38 of those tests fail under Jest before any migration begins, and they fail identically under Vitest afterwards. An agent that skipped the workflow file would either chase 38 failures the migration did not cause or blame them on Vitest. The baseline records the command, the environment and the totals.

Then the swap. The agent adds a vitest.config with globals: true, environment: "node", include for test/**/*.test.js and the same setup file, and runs it. The first run does not pass: eleven files fail to load with a module-not-found error for ../src/luxon, raised from test/helpers.js. That file opens with ES import statements and then assigns its nine helpers to exports.name, a mix Babel tolerated because it rewrote everything to CommonJS. A test that reaches the file through require hands it to Node's own loader, outside Vitest's transform, and Node will not add the missing .js extension to its imports. The fix is to make the helpers real ES exports and to change how tests import them: eleven test files use require("../helpers") and seven use a default import that no longer exists, so all eighteen become import * as Helpers. After that, the same 58 files and 1,222 tests pass, inline snapshot included.

The remainder is cleanup with a reason for each line. babel-jest and jest leave package.json; @babel/core and the preset stay, because npm run build still runs Babel through babel-node and Rollup. The jest and test scripts become Vitest commands, with coverage through a provider package configured to read src/**/*.js except src/zone.js and to write where the workflow's upload expects. The agent also reads the engines.node range of the Vitest version it installs against the workflow's matrix. When this page was written, the newest Vitest left out two of that matrix's four Node versions, so the choice is between an older Vitest major that covers them and a trimmed matrix, and the agent puts that choice to the maintainers instead of making it.

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 Jest to Vitest. Read package.json, the lockfile entries for jest and babel-jest, the Jest config, every setup file, the Babel config, the test helpers, .github/workflows and any scripts that run tests first. Count the tests' use of Jest: jest.fn, jest.mock, jest.spyOn, fake timers, snapshot matchers, @jest/globals imports, custom matchers and environment settings, and list them. Take a baseline with the exact environment the workflow sets, including TZ and LANG, and record suites, tests and snapshots; then run it once without those variables and record the difference so later failures are attributed correctly. Add a Vitest config that mirrors the Jest config: globals, node environment, the same test roots, the same setup file and the same coverage include, exclude and output directory. Run it and fix what fails to load. Where a helper or test mixes import statements with exports or require, convert it to ES module syntax and update every importer; do not change what any test asserts. Replace the test scripts in package.json, remove jest and babel-jest, and keep every Babel package the build still uses; prove that by running the build. Read engines.node of the Vitest version you install and compare it with every Node version in the workflow matrix; if any is not covered, do not edit the matrix, and report the options. Update the workflow only where it names a Jest command. The final run must show the same number of test files and tests as the baseline, in the workflow's environment. Open a pull request with both sets of totals and the list of changed files by reason.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. 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.
  2. 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.
  3. 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 new Vitest config, the Jest config deleted, the scripts and devDependencies in package.json changed, the lockfile updated, and the test files that needed module syntax fixed. The description sets the two totals side by side: test files, tests and snapshots under Jest and under Vitest, both taken with the workflow's TZ and LANG, and a line for the run without them so nobody rediscovers those failures later.

Changed files are grouped by cause. In a suite like the one above that is one helper file converted to ES exports, eighteen test files whose import of it changed, and nothing else under test/. The description states that no assertion was edited, and the diff of each test file is a single import line, which a reviewer can confirm by scrolling.

Two things are left as questions with the facts attached. One is Node coverage: which versions in the matrix the installed Vitest supports, and what the alternatives are. The other is coverage figures. A coverage provider that reads V8's data counts differently from Babel's instrumentation, so the percentage the upload service compares against will move even though the tests are the same; the agent reports both numbers and does not tune thresholds.

Run it on every repository still on Jest

This is a one-time job for each repository, so the event is someone deciding to do it. A developer sends this body to POST /o/{org}/sessions from a terminal or an MCP client, with a request_id that is a UUID made once for the job, and keeps working; the pull request is on the session when the run completes. If the agent stops on a question such as the Node matrix, a follow-up to POST /o/{org}/sessions/{id}/messages with the decision wakes the same sandbox, where the dependencies are already installed.

An organisation with many packages 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. A key runs a limited number at once and queues the rest, so the script needs no pacing of its own, and a webhook_url on the key receives run.completed for each run it started.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

The proof of a runner migration is two full test runs with matching totals, taken in an environment that matches CI. In its own sandbox the agent can set the time zone and locale the workflow sets, run both runners, and keep the complete output of each in the transcript at GET /o/{org}/sessions/{id}/messages. A reviewer does not have to take the description's numbers on trust.

The job is also the kind that stalls on a laptop. It is an afternoon of installs, a first run that fails for a reason nobody predicted, and a search through test files for the pattern behind it. Handed to a run, it proceeds while the developer works on something else, and it comes back as a pull request with the surprises written down.

Frequently asked questions

Do I have to rewrite my tests to import from vitest?

No. With globals: true in the Vitest config, test, describe and expect stay global and the test files keep working as written. The agent uses that setting so the diff stays small. Switching to explicit imports later is a separate, mechanical change.

What if my suite uses jest.mock and fake timers heavily?

Then the migration is larger and the inventory at the start says by how much. jest.fn, jest.spyOn and timers map to vi equivalents; module mocks are hoisted differently and factory functions sometimes need rewriting. The agent converts them file by file and runs each file after its change. moment/luxon uses none of these, which is why its diff is small.

Why do tests fail in the sandbox that pass in CI?

Usually environment, and the first thing to check is the workflow's env block. Date and locale libraries are sensitive to TZ and LANG: in moment/luxon, 38 tests fail on UTC and pass under America/New_York. The prompt has the agent take the baseline both ways so those failures are known before the runner changes.

Can we keep Babel?

For the build, yes, and the agent leaves it. Vitest transforms test files itself and does not read the Babel config unless told to, so babel-jest becomes unused and is removed. The agent runs the build afterwards to confirm that nothing else depended on a package it deleted.

More Jest jobs

The same job on other stacks

Keep reading