# Shard a Jest Suite Across Parallel CI Jobs for an Express API

Yes. An agent splits your Jest suite with --shard across a GitHub Actions matrix, keeps the serial MongoDB tests isolated per job, merges coverage, and opens a PR.

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

## What the agent does

The agent reads how the suite runs before it splits anything. In an Express API laid out like hagopj13/node-express-boilerplate, `package.json` defines `test` as `jest -i --colors --verbose --detectOpenHandles` and `coverage` as `jest -i --coverage`; the `-i` runs every file in one process in sequence, because the integration tests under `tests/integration` share one MongoDB database named by `config.mongoose.url` with `-test` appended in `src/config/config.js`, and `tests/utils/setupTestDB.js` wipes every collection in `beforeEach`. Two files running at once against that database would delete each other's fixtures. `jest.config.js` sets `testEnvironment` to `node` and the coverage reporters to `text`, `lcov`, `clover` and `html`. `package.json` pins `jest` at `^26.0.1`, and the only CI is `.travis.yml`, a single job on Node 12 with the `mongodb` service that runs `yarn lint` then `yarn test`.

`--shard=<n>/<m>` arrived in a later major release than the 26 pinned here, so the first step is the upgrade: the agent moves `jest` to a release with sharding, checks `restoreMocks`, `testEnvironmentOptions` and the Node version in `engines` against that release's requirements, and runs the suite once to see what the upgrade alone changes. It does not change the `-i` flag, since each shard still has to run its files in sequence against its own database.

Then it writes the workflow. A new `.github/workflows/test.yml` runs `yarn lint` in one job and the tests in a matrix job with a `shard` input of `[1, 2, 3]` and a `total` of 3, each with its own `mongo` service container and its own `MONGODB_URL` taken from the environment block `.travis.yml` already defines, so the shards never share a database. Each matrix job runs `yarn jest -i --shard=${{ matrix.shard }}/3 --coverage --coverageReporters=json`, uploads `coverage/coverage-final.json` as an artifact named by its shard, and a final job downloads the three, merges them with `nyc merge` into one report and prints it with `nyc report`. `yarn test` in `package.json` keeps working unchanged for a laptop.

The agent checks the split is even. With seven test files, the three integration suites in `tests/integration` and four small unit files under `tests/unit`, Jest assigns files to shards by sorted order, so it runs each shard locally against a MongoDB it installs in the sandbox, records the per-shard duration from Jest's summary line, and adjusts the shard count in the pull request if one shard holds all three integration files. It runs `yarn lint` and the three shards, then `nyc merge` on their output, and opens the pull request with the output and the three durations.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Shard this Express API's Jest suite across parallel GitHub Actions jobs. Read package.json, jest.config.js, .travis.yml, .env.example, src/config/config.js, tests/utils/setupTestDB.js and the files under tests/integration and tests/unit first. Upgrade jest to a release with --shard, keeping restoreMocks and the node test environment, and run the suite once to show the upgrade alone passes. Write .github/workflows/test.yml with a lint job and a matrix test job over three shards, each with its own mongo service container and MONGODB_URL so shards never share a database, each running jest -i --shard=N/3 with JSON coverage and uploading it as an artifact; add a final job that downloads the three and merges them with nyc merge and prints nyc report. Keep yarn test unchanged for local use. Install MongoDB in the sandbox, run each shard and record its duration from Jest's summary, rebalance if one shard holds every integration file, run yarn lint, and open a pull request with the output and the per-shard durations.",
  "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

What comes back is a pull request that adds `.github/workflows/test.yml`, bumps `jest` in `package.json` and `yarn.lock`, and touches nothing under `src`. The description shows the matrix, the per-shard command, the merged coverage step, and the Jest summary for each shard with its duration from the sandbox run.

The run's record keeps each shard's run against its own MongoDB and the merge, so a reviewer sees three green shards and one coverage table rather than reads that they would be.

Before merging, a reviewer decides whether to keep `.travis.yml` beside the new workflow or delete it, which the pull request leaves as a question since the file names the branch and the Coveralls upload the team may still use, and whether three shards is the right number for their runner budget.

## Run it on every Linear issue labelled ci

Add an automation to the Project with this prompt and a `linear` trigger on `linear.issue.labeled` with the label your CI work uses in its `labels`. Each labelled issue starts one run with the issue as its context, on its own branch; the trigger adds the issue after the prompt and fills in no placeholder, and a change made by an app integration never fires it, so the agent's own comment on the issue starts nothing.

A team with several Express services on the same boilerplate sends this body once per repository from its own server, each with its repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started and opens no second pull request. Runs past the key's `max_concurrent` wait in `queued` and start as slots free.

## Why run it on Rush?

Sharding a suite that shares a database is where the mistake hides: the split looks right in the workflow file and fails in CI when two shards wipe the same collections. The agent runs each shard against its own MongoDB in its own sandbox before the workflow ever runs on a runner, and the record keeps the three runs and their durations, which is the evidence a reviewer needs to merge a CI change without trying it first.

Every service on the same layout gets the same workflow from the same body, each in its own sandbox with its own pull request, and the per-shard timings in each description show whether the split is even for that repository rather than for the template.

## Frequently asked questions

### Why does each shard need its own MongoDB?

Because `setupTestDB.js` deletes every collection before each test, and `config.js` points every test process at the same `-test` database. Two shards on one database would wipe each other's fixtures mid-test. A service container per matrix job is the cheapest way to give each shard its own.

### Does this change how tests run locally?

No. `yarn test` keeps `jest -i` with no shard flag and runs the whole suite in sequence as before. The `--shard` flag is used only in the workflow, and a developer who wants one shard locally can pass it by hand.

### What about coverage thresholds and Coveralls?

Each shard's coverage is partial, so the workflow merges the three JSON files with `nyc merge` before reporting, and that merged report is what any threshold or upload should read. The pull request shows the merged table and names where a Coveralls step would go if the team keeps it.

### Why upgrade Jest instead of splitting by path?

A path-based split is a hand-maintained list that goes stale when a file is added. `--shard` divides whatever files exist, so a new test file lands in a shard with no workflow change, and the upgrade is the one-time cost of having that.

## More Jest jobs

- [Fix "Test environment jest-environment-jsdom cannot be found" After Upgrading to Jest 28 or 29](https://getrush.ai/run/fix-jest-environment-jsdom-not-found/jest/)
- [Fix "Option 'testPathPattern' was replaced by '--testPathPatterns'" in Jest 30](https://getrush.ai/run/fix-option-testpathpattern-was-replaced/jest/)
- [Migrate a JavaScript Library from Jest to Vitest](https://getrush.ai/run/migrate-jest-to-vitest/jest/)

## The same job on other stacks

- [Shard Playwright Tests Across GitHub Actions Runners](https://getrush.ai/run/add-test-sharding/playwright/)
- [Shard Cypress Specs Across CI Containers Without Cypress Cloud](https://getrush.ai/run/add-test-sharding/cypress/)

## More jobs like this: Turn a Linear label into a PR

- [Add a Theme App Extension to a Shopify App](https://getrush.ai/run/add-theme-app-extension/shopify-app/)

## 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/)
