# Upgrade Jest 29 to Jest 30

Yes. The agent raises jest and babel-jest together, replaces the matcher aliases Jest 30 removed, and opens a pull request with the suite's totals before and after.

[Run this on Rush](https://cloud.getrush.ai/run/upgrade-jest/jest/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

A Jest major upgrade touches three things: the packages, the matchers the tests call, and the Node versions CI runs on. The agent reads all three before installing. In a library like moment/luxon, `package.json` asks for `jest` at `^29.4.3` and, separately, `babel-jest` at `^28.1.2`. The lockfile shows what that produces: `jest` 29.4.3 with its own `babel-jest` 29.4.3 nested under `jest-config`, and a second `babel-jest` 28.1.3 at the top level, which is what the name `babel-jest` in `jest.config.js` finds from the project root. The project has been transforming its tests with a `babel-jest` one major behind its runner. It works, and it is the first thing a careless upgrade makes worse, because raising `jest` alone leaves the direct dependency two majors behind.

The baseline is taken the way the workflow takes it. `.github/workflows/test.yml` sets `TZ: America/New_York` and `LANG: en_US.utf8` and runs `npm run test`, which is `jest --coverage`. In that environment the suite passes with 58 files, 1,222 tests and one snapshot. Without the time zone, 38 tests fail on the current version, so the agent records both runs and uses the workflow's environment for every comparison that follows.

It then raises `jest` and `babel-jest` to the same major in one step and runs the suite. Two tests fail, both in `test/datetime/tokenParse.test.js`, with `expect(...).toThrowError is not a function`. Jest 30 removed the alias matchers that earlier versions kept beside the canonical names, and `toThrowError` was one of them. The fix is the canonical name, `toThrow`, at those two call sites. The agent searches the whole test tree for the other removed aliases, such as `toBeCalled` and `toBeCalledWith`, instead of fixing only what failed, since a matcher inside a test that is skipped on this platform fails on someone else's. Here the search finds only the two.

The remaining checks are about the edges. `test/setupTests.js` registers a custom matcher with `expect.extend`, so the agent confirms a test that uses it still passes. The single inline snapshot must pass without being rewritten; a snapshot that changes during an upgrade is reported as a difference, not accepted with `-u`. Coverage must still be written to `build/coverage`, where the workflow's upload step reads it. And the agent compares the Node range the new Jest declares with the four versions in the workflow's matrix and with `engines` in `package.json`, which describes what the published library supports and not what its tests need. Nothing here reads the `LIMIT_JEST` variable the workflow also sets, and the pull request mentions it without removing it.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Upgrade Jest in this repository from 29 to the latest 30 release. Read package.json, the lockfile entries for jest, babel-jest and every other jest-prefixed package, the Jest config, the setup files, the Babel config and .github/workflows first. Report every package that is on a different major from jest itself. Take a baseline in the exact environment the workflow sets, including TZ and LANG: test files, tests, snapshots and whether coverage output is written; run once without those variables as well and record the difference. Raise jest and every jest-prefixed direct dependency to the same major in one change. Run the suite. For each failure, find the cause in the Jest 30 release notes before changing code. Replace removed matcher aliases with their canonical names across the whole test tree, not only where a test failed, and list each replacement. Do not update snapshots with -u; if a snapshot differs, show the difference and stop on that file. Do not change what any test asserts, and do not touch source files. Confirm custom matchers from the setup file still work and that coverage is written to the same directory. Compare the Node range the new jest declares with every version in the workflow matrix and report any version it does not cover, without editing the matrix. Leave unrelated dependencies alone. Open a pull request with the totals before and after, the list of replaced matchers by file and line, and the versions of each jest package before and after.",
  "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 that changes `package.json`, the lockfile and the test lines that called removed matchers. The description gives a version table for every Jest package before and after, so the reviewer can see that `babel-jest` now matches the runner. Under it are the suite totals from both runs in the workflow's environment, and the separate run without `TZ` for reference.

Each code change is listed with its file, line and reason. In the case above that is two lines in one test file, `toThrowError` to `toThrow`, and the list also says which other aliases were searched for and not found. Snapshots are reported as unchanged; if one differs, the run stops there and shows the difference.

A reviewer checks the Node note last. The description names each version in the CI matrix and whether the new Jest's declared range includes it. Versions outside the range are for the maintainers to drop or keep; the agent leaves the workflow file as it found it, so the pull request's own checks show what happens on each.

## Run it on every new Jest major

A major release is rare enough to start by hand. A maintainer opens an issue that names the target version and adds the label the team uses for upgrades. An automation in the Project that holds the repository, with this prompt and a `github` trigger on `issues.labeled` with that label in `labels`, starts one run. The trigger puts the issue after the prompt and fills in nothing, so the prompt tells the agent to read the target major from the issue text that follows it.

Between majors, a `schedule` trigger with a weekly `cron` and a shorter prompt keeps the minor versions current: read the registry, and if a newer release exists within the current major, upgrade, run the suite in the workflow's environment and open a pull request, otherwise end with one line. The automation's max runs per hour applies to both triggers together.

## Why run it on Rush?

An upgrade is only as believable as its before and after, and those need the same environment. The agent sets the workflow's time zone and locale in its own sandbox, runs the full suite on the old and new versions, and keeps the output of every run in the transcript at `GET /o/{org}/sessions/{id}/messages`. When the description says the totals match, the two summaries are there to compare.

It also does the part that is easy to skip when a suite goes green. Searching for every removed alias and checking each Node version against the declared range are quick to describe and dull to do. A run does them every time, and the pull request lists what was searched for, not only what was changed.

## Frequently asked questions

### Why upgrade babel-jest in the same change?

Because the transform and the runner are released together and meant to match. In moment/luxon the direct `babel-jest` dependency is already a major behind `jest`, and npm installs a second copy for Jest's own use. Raising both to the same major leaves one copy in the tree.

### Which matchers did Jest 30 remove?

The alias names that duplicated canonical matchers, for example `toThrowError` for `toThrow` and `toBeCalled` for `toHaveBeenCalled`. A call to a removed alias fails with a message that the matcher is not a function. The agent reads the release notes for the full list and searches the test tree for each name.

### Will it update my snapshots?

No. A snapshot that changes during a runner upgrade means the serializer's output changed, and whether that is acceptable is your decision. The agent shows the difference for each affected file and waits. You can answer with a follow-up message to the same session.

### Should we move to Vitest instead?

That is a different job with a different risk. Upgrading keeps the runner and changes a few lines; migrating changes the runner and can change how modules load. If the suite uses few Jest-specific features the migration is small too, and there is a separate page for it. Upgrading first gives a later migration a current baseline to compare against.

## More Jest jobs

- [Write Jest Unit Tests for the Untested Modules of an Express API](https://getrush.ai/run/write-unit-tests/jest/)
- [Add Coverage Thresholds to a Jest Suite](https://getrush.ai/run/add-coverage-thresholds/jest/)
- [Add Mutation Testing With Stryker to a Jest Suite](https://getrush.ai/run/add-mutation-testing/jest/)

## More jobs like this: Upgrade dependencies weekly

- [Upgrade Knex 0.20 to Knex 3 in an Express API](https://getrush.ai/run/upgrade-knex/knex/)
- [Upgrade Retired Lambda Runtimes in an AWS CDK App](https://getrush.ai/run/upgrade-lambda-runtime/aws-cdk/)
- [Upgrade the Lambda Runtime in a Serverless Service](https://getrush.ai/run/upgrade-lambda-runtime/serverless/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
