All jobs

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 RushOpens 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 with this body:

{
  "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.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

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

The same job on other stacks

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

Keep reading