Skip to content

Commit 051594d

Browse files
authored
[jest-circus] Add describe-level retries (#16322)
1 parent 47a097e commit 051594d

48 files changed

Lines changed: 2551 additions & 92 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
- `[@jest/expect-utils, jest-mock]` Add `mockFn.whenCalledWith(...args)` for configuring return values per argument list, with first-class asymmetric-matcher support ([#16053](https://github.com/jestjs/jest/pull/16053))
66
- `[@jest/expect-utils]` Export `AsymmetricMatcher` and `FunctionParameters` types (previously private to `expect`) ([#16053](https://github.com/jestjs/jest/pull/16053))
77
- `[jest-circus, jest-core, jest-jasmine2, jest-test-result, jest-types]` `--collectTests` now expands `test.each`/`describe.each` cases and reports per-status counts (skipped/todo via the new `wouldRun` flag for selected tests) plus a summary line that match a real run, including under `--testNamePattern` and `.only`/`fdescribe` focus on both the circus and jasmine2 runners ([#16259](https://github.com/jestjs/jest/pull/16259))
8+
- `[jest-circus, jest-environment, jest-runtime, jest-types]` Add describe-level retries via `jest.retryTimes(..., {entireDescribe: true})` ([#16322](https://github.com/jestjs/jest/pull/16322))
89
- `[jest-circus, jest-message-util, jest-reporters, jest-types]` Add `retryMessages` to `AssertionResult` and export `formatErrorStack`, so the retry log renders nested `cause` and `AggregateError` sections with code frames instead of serialized `[cause]:`/`[errors]:` markers ([#16316](https://github.com/jestjs/jest/pull/16316))
910
- `[jest-circus, jest-types]` Add `unhandledErrorsDetailed` to `Circus.RunResult`, so an unhandled rejection reports its `cause` chain and `AggregateError` entries with code frames instead of a pre-serialized stack ([#16316](https://github.com/jestjs/jest/pull/16316))
1011
- `[jest-haste-map]` Replace `NodeWatcher` and `FSEventsWatcher` with `@parcel/watcher` for the non-watchman watch path ([#16188](https://github.com/jestjs/jest/pull/16188))

‎docs/JestObjectAPI.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1224,6 +1224,42 @@ test('will fail', () => {
12241224
});
12251225
```
12261226

1227+
`entireDescribe` retries all tests and hooks in the `describe` block where `jest.retryTimes()` is called. When called at the top level, it retries the root `describe` block for the test file. While a describe retry is active, per-test retries are not applied within its subtree.
1228+
1229+
```js
1230+
describe('workflow', () => {
1231+
jest.retryTimes(3, {entireDescribe: true});
1232+
1233+
beforeAll(() => {
1234+
// Runs again before each retry.
1235+
});
1236+
1237+
test('first step', () => {
1238+
// Passing tests run again with the rest of the block.
1239+
});
1240+
1241+
test('second step', () => {
1242+
// A failure retries the entire block.
1243+
});
1244+
1245+
afterAll(() => {
1246+
// Runs after every attempt.
1247+
});
1248+
});
1249+
```
1250+
1251+
Each attempt runs the block's `beforeAll` hooks, child tests and nested describes, and `afterAll` hooks. When a retryable test or hook failure is recorded, passing tests run again with the rest of the block. If `entireDescribe` is omitted or `false`, `jest.retryTimes()` keeps its existing per-test behavior.
1252+
1253+
Nested describe retry settings compose from the innermost block outwards. Each time an ancestor starts a new attempt, its descendant retry budgets start again. The maximum number of times a test can run from nested describe retries is therefore the product of `(numRetries + 1)` for each configured block. A block configured with zero describe retries still defines a retry boundary and disables per-test retries in its subtree.
1254+
1255+
`afterAll` hooks still run after every attempt, but failures from `afterAll` and process-level errors do not trigger a describe retry. If either occurs during an attempt, no further attempts run, even if another failure would otherwise be retried, and all errors remain reported.
1256+
1257+
Unhandled rejections owned by a test, `beforeAll`, `beforeEach`, or `afterEach` participate in describe retries. Ownerless rejections remain reported, while `afterAll` failures remain non-retryable.
1258+
1259+
When test randomization is enabled, each describe block keeps the order selected for its first attempt across all of its retries.
1260+
1261+
`retryImmediately` only applies to ordinary per-test retries. A describe retry always finishes the complete current attempt before starting the next one.
1262+
12271263
Returns the `jest` object for chaining.
12281264

12291265
:::caution

‎e2e/__tests__/failures.test.ts‎

Lines changed: 19 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,27 @@ const dir = path.resolve(__dirname, '../failures');
1313

1414
const normalizeDots = (text: string) => text.replaceAll(/\.+$/gm, '.');
1515

16+
// These snapshots run with both Circus and Jasmine, which format the wrapper
17+
// around non-Error failures differently. Keep the user-facing stack comparable.
18+
function normalizeCircusErrorCauses(text: string) {
19+
return text.replaceAll(
20+
/\n {10}at Array\.map \(<anonymous>\)\n\n {4}Cause:\n([\s\S]*?)(?=\n {2}● |$)/g,
21+
(match, cause: string) => {
22+
const stackStart = cause.search(/\n {10}(?:\d+ \||at )/);
23+
return stackStart === -1
24+
? match
25+
: `\n${cause.slice(stackStart + 1).replaceAll(/^ {4}/gm, '')}`;
26+
},
27+
);
28+
}
29+
1630
function cleanStderr(stderr: string) {
1731
const {rest} = extractSummary(stderr);
18-
return rest
19-
.replaceAll(/.*(jest-jasmine2|jest-circus).*\n/g, '')
20-
.replaceAll(new RegExp('Failed: Object {', 'g'), 'thrown: Object {');
32+
return normalizeCircusErrorCauses(
33+
rest
34+
.replaceAll(/.*(jest-jasmine2|jest-circus).*\n/g, '')
35+
.replaceAll(new RegExp('Failed: Object {', 'g'), 'thrown: Object {'),
36+
);
2137
}
2238

2339
beforeAll(() => {

0 commit comments

Comments
 (0)