[jest-circus] Add describe-level retries

[soltonigiri]

Summary

Closes #10520.

This adds an entireDescribe option to jest.retryTimes():

describe('workflow', () => {
  jest.retryTimes(3, {entireDescribe: true});
});

When enabled, a failure recorded on a test reruns the complete current describe lifecycle: its beforeAll hooks, child tests and nested describes, and afterAll hooks. This includes ordinary failures and unhandled rejections owned by a test, beforeAll, beforeEach, or afterEach. Calling it at the test-file top level applies it to the root describe block. Existing per-test retry behavior is unchanged when entireDescribe is omitted or false.

Describe-level retries take precedence over per-test retries in their subtree. Each describe attempt finishes completely, including its afterAll hooks, before another attempt begins; retryImmediately continues to apply only to ordinary per-test retries. A describe_retry circus event is dispatched after rollback and before the next attempt starts.

Nested describe retry settings compose from the innermost block outwards, with descendant retry budgets restarting for each ancestor attempt. A zero-retry describe setting still suppresses per-test retries in its subtree.

Ownerless rejections remain reported. Failures from afterAll and process-level errors observed during an attempt abort further attempts. Randomized test order stays fixed across attempts. Cleanup only removes errors added during the current attempt, clears test-owned snapshot changes for tests in the retried subtree, and restores expect state from the attempt start, so ancestor errors and snapshots outside an inner retried block are preserved.

Describe retry options must be configured synchronously during collection. Calling jest.retryTimes(..., {entireDescribe: true}) after test execution has started throws at the call site.

Test plan

• corepack yarn build
• corepack yarn jest packages/jest-circus/src/__tests__ packages/jest-circus/src/legacy-code-todo-rewrite/__tests__ --runInBand (19 suites, 125 tests, and 34 snapshots passed)
• corepack yarn jest e2e/__tests__/detectOpenHandles.ts e2e/__tests__/failures.test.ts e2e/__tests__/promiseAsyncHandling.test.ts e2e/__tests__/testRetries.test.ts e2e/__tests__/toMatchSnapshotWithRetries.test.ts e2e/__tests__/toMatchInlineSnapshotWithRetries.test.ts --runInBand --color=false (6 suites, 83 tests, and 36 snapshots passed)
• corepack yarn typecheck:tests
• corepack yarn lint
• corepack yarn check-changelog 16322

[netlify]

✅ Deploy Preview for jestjs ready!

Name	Link
🔨 Latest commit	a7d5afc
🔍 Latest deploy log	https://app.netlify.com/projects/jestjs/deploys/6a8413c0762ab50008c15555
😎 Deploy Preview	https://deploy-preview-16322--jestjs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: soltonigiri / name: soltonigiri (2186d1e, 41ab85f, 4abe118, ecd4ebf)

[pkg-pr-new]

Open in StackBlitz

babel-jest

npm i https://pkg.pr.new/babel-jest@16322

babel-plugin-jest-hoist

npm i https://pkg.pr.new/babel-plugin-jest-hoist@16322

babel-preset-jest

npm i https://pkg.pr.new/babel-preset-jest@16322

create-jest

npm i https://pkg.pr.new/create-jest@16322

@jest/diff-sequences

npm i https://pkg.pr.new/@jest/diff-sequences@16322

expect

npm i https://pkg.pr.new/expect@16322

@jest/expect-utils

npm i https://pkg.pr.new/@jest/expect-utils@16322

jest

npm i https://pkg.pr.new/jest@16322

jest-changed-files

npm i https://pkg.pr.new/jest-changed-files@16322

jest-circus

npm i https://pkg.pr.new/jest-circus@16322

jest-cli

npm i https://pkg.pr.new/jest-cli@16322

jest-config

npm i https://pkg.pr.new/jest-config@16322

@jest/console

npm i https://pkg.pr.new/@jest/console@16322

@jest/core

npm i https://pkg.pr.new/@jest/core@16322

@jest/create-cache-key-function

npm i https://pkg.pr.new/@jest/create-cache-key-function@16322

jest-diff

npm i https://pkg.pr.new/jest-diff@16322

jest-docblock

npm i https://pkg.pr.new/jest-docblock@16322

jest-each

npm i https://pkg.pr.new/jest-each@16322

@jest/environment

npm i https://pkg.pr.new/@jest/environment@16322

jest-environment-jsdom

npm i https://pkg.pr.new/jest-environment-jsdom@16322

@jest/environment-jsdom-abstract

npm i https://pkg.pr.new/@jest/environment-jsdom-abstract@16322

jest-environment-node

npm i https://pkg.pr.new/jest-environment-node@16322

@jest/expect

npm i https://pkg.pr.new/@jest/expect@16322

@jest/fake-timers

npm i https://pkg.pr.new/@jest/fake-timers@16322

@jest/get-type

npm i https://pkg.pr.new/@jest/get-type@16322

@jest/globals

npm i https://pkg.pr.new/@jest/globals@16322

jest-haste-map

npm i https://pkg.pr.new/jest-haste-map@16322

jest-jasmine2

npm i https://pkg.pr.new/jest-jasmine2@16322

jest-leak-detector

npm i https://pkg.pr.new/jest-leak-detector@16322

jest-matcher-utils

npm i https://pkg.pr.new/jest-matcher-utils@16322

jest-message-util

npm i https://pkg.pr.new/jest-message-util@16322

jest-mock

npm i https://pkg.pr.new/jest-mock@16322

@jest/pattern

npm i https://pkg.pr.new/@jest/pattern@16322

jest-phabricator

npm i https://pkg.pr.new/jest-phabricator@16322

jest-regex-util

npm i https://pkg.pr.new/jest-regex-util@16322

@jest/reporters

npm i https://pkg.pr.new/@jest/reporters@16322

jest-resolve

npm i https://pkg.pr.new/jest-resolve@16322

jest-resolve-dependencies

npm i https://pkg.pr.new/jest-resolve-dependencies@16322

jest-runner

npm i https://pkg.pr.new/jest-runner@16322

jest-runtime

npm i https://pkg.pr.new/jest-runtime@16322

@jest/schemas

npm i https://pkg.pr.new/@jest/schemas@16322

jest-snapshot

npm i https://pkg.pr.new/jest-snapshot@16322

@jest/snapshot-utils

npm i https://pkg.pr.new/@jest/snapshot-utils@16322

@jest/source-map

npm i https://pkg.pr.new/@jest/source-map@16322

@jest/test-result

npm i https://pkg.pr.new/@jest/test-result@16322

@jest/test-sequencer

npm i https://pkg.pr.new/@jest/test-sequencer@16322

@jest/transform

npm i https://pkg.pr.new/@jest/transform@16322

@jest/types

npm i https://pkg.pr.new/@jest/types@16322

jest-util

npm i https://pkg.pr.new/jest-util@16322

jest-validate

npm i https://pkg.pr.new/jest-validate@16322

jest-watcher

npm i https://pkg.pr.new/jest-watcher@16322

jest-worker

npm i https://pkg.pr.new/jest-worker@16322

pretty-format

npm i https://pkg.pr.new/pretty-format@16322

commit: 4f01ede

[SimenB]

thanks, this generally looks really good! impressive test coverage 👍

as mentioned inline, there seems to be some bug fixes bundled into this change - would you mind extracting those to its own PR?

[soltonigiri]

@SimenB All requested changes are addressed and the new head is green. Ready for re-review when you have a chance.

[SimenB]

Thanks! Will take a look tomorrow or next week.

As mentioned, I'd love to see the bug fixes you made as its own PR as bug fixes are easier to review and land than features/new APIs 🙂

[soltonigiri]

Thanks! I opened separate PRs for the bug fixes as you suggested:

• [jest-circus] Clear the current test after skipped and todo tests #16342
• [jest-circus] Isolate done callback state between invocations #16343
• [jest-circus, jest-snapshot] Preserve unrelated inline snapshots across test retries #16344

CI is green on all three.

[SimenB]

Awesome, thanks! All three landed now, which has created a bunch of conflicts here 😅

---

I've tried to sketch out a design with Claude for the snapshot clearing that works both with what landed in #16344 on its own, but also as a mechanism used by the describe retries on this PR. Here's the result:

What main gives you now

clear is clear(testIdentity). Every test has a stable identity — MatcherState.currentTestIdentity, set by circus from the async-local scope, the same object across one test's retries and distinct across tests even when full names collide. SnapshotState records what each test contributed since its current attempt began, and clear(identity) inverts exactly that: counts, key counters, inline snapshots, file snapshot data, unchecked keys, and the dirty flag. Other tests' work is untouched.

Two properties matter for this PR: the records are disjoint per test, and clear(identity) is order-independent — it does not require that nothing else happened since the attempt started.

What that means here

_inlineSnapshotsForTestRetry and commit() are redundant. They solve per-test retry rollback against a committed baseline; main solves the same problem per test. Dropping them resolves most of the State.ts conflict.

getRetryCheckpoint/restore can go too. A describe attempt's snapshot work is the union of the work of the tests inside it. Because the records are disjoint, rolling back the attempt decomposes into clear(identity) for each test in the subtree — no whole-state snapshot required. This PR already disables per-test retries inside a describe attempt, so nothing interleaves.

The missing piece is hook identity. beforeAll/afterAll run outside the async-local scope, so their snapshots carry no identity and nothing can undo them — and a describe retry re-runs beforeAll. Setting the scope around the *All hooks, with the describe block as the identity, closes that. Rollback then becomes clear() per test in the subtree plus clear() for the block, and needs no new SnapshotState API.

Why not keep both mechanisms

They do not compose, and the failure is silent. The checkpoint does not save _attemptRecordsByTest, so a restore() leaves records holding prior values captured before the restore. A later clear(identity) then undoes work the restore already undid: double-subtracted counts, resurrected file snapshot values.

Cost also differs by an order. The checkpoint copies _snapshotData, _uncheckedKeys, _counters and _inlineSnapshots wholesale on every attempt, including attempts that succeed and discard the copy. The records cost only what the attempt actually touched.

Knock-on

SnapshotStateWithRetry and the optional getRetryCheckpoint? go away with the checkpoint. The version-skew concern that motivated the optional method does not apply to clear: it exists in every published version, so against a mismatched jest-snapshot a clear(identity) call degrades to the old full wipe rather than throwing, with no optional-method probe needed.

[soltonigiri]

Thanks for the detailed design — I updated the branch to follow it.

I removed _inlineSnapshotsForTestRetry, commit(), and the getRetryCheckpoint() / restore() path, and now use main’s identity-scoped SnapshotState.clear() implementation. beforeAll and afterAll run with their owning describe block as the snapshot identity, while tests and per-test hooks use the test entry.

A describe retry clears every test identity and every describe-block identity in that subtree. Nested describe blocks are included because their beforeAll and afterAll hooks are rerun by the outer describe retry. Ordinary test retries continue to clear only event.test. The resulting implementation does not add a new retry API to SnapshotState.

I also added focused identity-scoping coverage and an E2E case combining file and inline snapshots from beforeAll, tests, and afterAll with a later ordinary test retry.

All checks on the updated head have completed with no failures. Ready for another look when you have a chance.

[SimenB]

I like how this is turning out. I of course saw something that didn't smell right (which I lead you to add), but quite close!

Two things inline. The hook identity one reverses part of the earlier sketch, so sorry for the churn there.

It has a knock-on for the fixtures. entireDescribeBeforeAllSnapshot pins beforeAll snapshot behaviour, which is heading for a hard error rather than support. The coverage worth keeping is that a describe retry rolls back snapshots and gets the counts right, so move those assertions into the test body and drop the beforeAll ones — entireDescribeAncestorFailures already covers the hook side without snapshots.

One more while jest.retryTimes is open. The setter pushes to state.unhandledErrors when called after the run has started, so the mistake surfaces as a file-level failure with a stack pointing into Jest. Throwing from the setter instead propagates back out through jest.retryTimes to the line the user actually wrote.

[soltonigiri]

Addressed all requested changes:

• memoized getTestID with a WeakMap;
• limited snapshot identity and retry cleanup to tests, with the snapshot assertions moved out of *All hooks;
• made late entireDescribe retry configuration throw at the user's call site.

The Jest Circus unit suites and the focused retry/snapshot E2E suites pass, along with build, test typechecking, lint, and the changelog check.

[SimenB]

Noticed one more thing and just pushed a fix rather than have you iterate again.

A test-owned unhandled rejection no longer vetoes a describe retry, but an uncaught exception attributed to the same test still did — so a stray timer that throws made the block un-retryable while a floating promise did not. Both end up on the owning test and both are rolled back by clearTestErrors, so neither needs to stop the attempt. Ownerless errors keep vetoing, which the unhandledErrors check in the retry loop already covers.

One of the unit assertions was pinning the old behaviour (processErrorGeneration being 1 after a test-owned process error), so that moved to 0, and there is a fixture covering both the immediate and the late-arriving case.

[SimenB]

thank you! quite a few iterations, but I think it landed in a good place 🙂 Thanks for the PR (and your patience)!

[soltonigiri]

Thanks so much! I really appreciate all the detailed reviews and guidance through the iterations. I’m glad we got it into a good place!