Flaky Jest tests on GitHub Actions.
Set up, retried right, quarantined.
On GitHub Actions, Jest needs one package, one wrapper and one secret: install @mergifyio/jest, wrap your config with withMergify, and give the test step a MERGIFY_TOKEN. The reporter uploads every result when the run ends and applies quarantine inside Jest's workers, with no JUnit file to write or upload.
Setup
Run Jest with Test Engine on GitHub Actions
Create a Mergify application key with the ci scope and store it as the MERGIFY_TOKEN secret. Then:
jest.config.js: Wrap the Jest config with withMergify, which adds the reporter and test runner.const { withMergify } = require("@mergifyio/jest");
module.exports = withMergify({
testEnvironment: "node",
// ...your existing configuration
});.github/workflows/ci.yml: Pass the MERGIFY_TOKEN secret to the step that runs Jest.name: CI
on:
push:
branches: [main]
pull_request:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: 24
cache: npm
- run: npm ci
- name: Run tests
env:
MERGIFY_TOKEN: ${{ secrets.MERGIFY_TOKEN }}
run: npm test # jest- Remove
--reportersfrom the test command. On the command line it replaces the reporters of your config, the Mergify one included. - Config in
package.json?withMergifyneeds a function call, so move it tojest.config.jsfirst. - Moving from
jest-junitand the upload action? Drop the upload step andcontinue-on-errorfrom the test step: the reporter sends the results and quarantine is already in Jest's exit code. - Running Jest across a matrix? Every leg reports the same
GITHUB_JOB, so setMERGIFY_TEST_JOB_NAME: test (${{ matrix.node-version }})on each leg. Without it, the legs' results merge into one test, and a test that only fails on one version looks flaky instead of broken.
Full reference: Jest on docs.mergify.com.
Retries
Re-run failed jobs versus retrying the test
Re-run failed jobs repeats npm ci and every test file for one test that may have been unlucky.
jest.retryTimes(2) retries inside the run and reports the test as passed when an attempt succeeds. The flake is still there, and only the log of that run shows the failed attempts.
@mergifyio/jest turns Jest's own retries off during its reruns and decides with history instead. On a pull request it reruns the tests the target branch does not have yet, in Jest's workers, within the Prevention budget, and fails the run if any attempt fails. On the default branch it reruns the tests Test Engine knows as unhealthy without changing the result.
Runners
Why Jest tests flake on GitHub Actions
One worker on a private-repository runner
Jest's
maxWorkersdefaults to the number of CPUs minus one. On a 2-vCPU private runner that is a single worker, so files that ran in parallel on your laptop run one after the other, and a slow file can push tests past the default 5-second timeout. On a public repository's 4 vCPUs it is three workers. Reproduce with the runner's count.npx jest --maxWorkers=1Workers running out of memory
A private runner has 8 GB for the runner, your app's services and every Jest worker. Workers that leak memory across files get killed mid-file, and the failure lands on whichever test was running.
workerIdleMemoryLimitrecycles a worker before it gets there.module.exports = withMergify({ workerIdleMemoryLimit: "512MB", });Snapshots that only exist on one machine
Jest runs with
--ciby default on GitHub Actions, where a missing snapshot fails the test instead of being written. A test whose snapshot was never committed passes locally and fails on CI, and goes "green" the moment someone commits it. It looks flaky; it is a missing file.
The missing layer
GitHub Actions doesn't know what a test is.
GitHub Actions tells you a job failed. Test Engine tells you which Jest test failed, whether it failed on the same commit before, and whether it should block the merge. Read what Test Engine adds to GitHub Actions, or the Jest guide for the patterns behind flaky Jest suites on any CI: fake timers, snapshot drift, and the async traps behind flaky Jest suites.
Frequently asked questions
- Why are my Jest tests flaky only on GitHub Actions?
- Look at the runner first: one worker on a 2-vCPU private runner instead of one per core on your laptop, 8 GB shared by every worker, and a UTC clock. Run with --maxWorkers=1 and TZ=UTC locally to reproduce.
- Do I still need jest-junit?
- Not for Test Engine: @mergifyio/jest uploads the results itself. If another tool reads the JUnit file, list jest-junit in the config's reporters, after which withMergify adds its own.
- Are test.concurrent tests rerun?
- No. jest-circus starts them together with the other tests of their file and cannot run one again on its own. They are still reported and can still be quarantined.