New internal testing helpers: waitFor, waitForAll, waitForPaint (#26285)
Over the years, we've gradually aligned on a set of best practices for for testing concurrent React features in this repo. The default in most cases is to use `act`, the same as you would do when testing a real React app. However, because we're testing React itself, as opposed to an app that uses React, our internal tests sometimes need to make assertions on intermediate states that `act` intentionally disallows. For those cases, we built a custom set of Jest assertion matchers that provide greater control over the concurrent work queue. It works by mocking the Scheduler package. (When we eventually migrate to using native postTask, it would probably work by stubbing that instead.) A problem with these helpers that we recently discovered is, because they are synchronous function calls, they aren't sufficient if the work you need to flush is scheduled in a microtask — we don't control the microtask queue, and can't mock it. `act` addresses this problem by encouraging you to await the result of the `act` call. (It's not currently required to await, but in future versions of React it likely will be.) It will then continue flushing work until both the microtask queue and the Scheduler queue is exhausted. We can follow a similar strategy for our custom test helpers, by replacing the current set of synchronous helpers with a corresponding set of async ones: - `expect(Scheduler).toFlushAndYield(log)` -> `await waitForAll(log)` - `expect(Scheduler).toFlushAndYieldThrough(log)` -> `await waitFor(log)` - `expect(Scheduler).toFlushUntilNextPaint(log)` -> `await waitForPaint(log)` These APIs are inspired by the existing best practice for writing e2e React tests. Rather than mock all task queues, in an e2e test you set up a timer loop and wait for the UI to match an expecte condition. Although we are mocking _some_ of the task queues in our tests, the general principle still holds: it makes it less likely that our tests will diverge from real world behavior in an actual browser. In this commit, I've implemented the new testing helpers and converted one of the Suspense tests to use them. In subsequent steps, I'll codemod the rest of our test suite.
Andrew Clark committed
Mar 2, 2023 at 21:58 UTC
e5244673388a58eaf8f02a9e44749bef3ffee615
8 files changed
+215
-9
.eslintrc.js
+1
@@ -325,6 +325,7 @@ module.exports = {
325
'packages/react-native-renderer/**/*.js',
326
'packages/eslint-plugin-react-hooks/**/*.js',
327
'packages/jest-react/**/*.js',
328
+ 'packages/internal-test-utils/**/*.js',
329
'packages/**/__tests__/*.js',
330
'packages/**/npm/*.js',
331
],
packages/internal-test-utils/ReactInternalTestUtils.js
new
+182
@@ -0,0 +1,182 @@
1
+/**
2
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
3
+ *
4
+ * This source code is licensed under the MIT license found in the
5
+ * LICENSE file in the root directory of this source tree.
6
+ */
7
+
8
+// TODO: Move `internalAct` and other test helpers to this package, too
9
+
10
+import * as SchedulerMock from 'scheduler/unstable_mock';
11
+import {diff} from 'jest-diff';
12
+import {equals} from '@jest/expect-utils';
13
+
14
+function assertYieldsWereCleared(Scheduler) {
15
+ const actualYields = Scheduler.unstable_clearYields();
16
+ if (actualYields.length !== 0) {
17
+ const error = Error(
18
+ 'The event log is not empty. Call assertLog(...) first.',
19
+ );
20
+ Error.captureStackTrace(error, assertYieldsWereCleared);
21
+ throw error;
22
+ }
23
+}
24
+
25
+export async function waitFor(expectedLog) {
26
+ assertYieldsWereCleared(SchedulerMock);
27
+
28
+ // Create the error object before doing any async work, to get a better
29
+ // stack trace.
30
+ const error = new Error();
31
+ Error.captureStackTrace(error, waitFor);
32
+
33
+ const actualLog = [];
34
+ do {
35
+ // Wait until end of current task/microtask.
36
+ await null;
37
+ if (SchedulerMock.unstable_hasPendingWork()) {
38
+ SchedulerMock.unstable_flushNumberOfYields(
39
+ expectedLog.length - actualLog.length,
40
+ );
41
+ actualLog.push(...SchedulerMock.unstable_clearYields());
42
+ if (expectedLog.length > actualLog.length) {
43
+ // Continue flushing until we've logged the expected number of items.
44
+ } else {
45
+ // Once we've reached the expected sequence, wait one more microtask to
46
+ // flush any remaining synchronous work.
47
+ await null;
48
+ actualLog.push(...SchedulerMock.unstable_clearYields());
49
+ break;
50
+ }
51
+ } else {
52
+ // There's no pending work, even after a microtask.
53
+ break;
54
+ }
55
+ } while (true);
56
+
57
+ if (equals(actualLog, expectedLog)) {
58
+ return;
59
+ }
60
+
61
+ error.message = `
62
+Expected sequence of events did not occur.
63
+
64
+${diff(expectedLog, actualLog)}
65
+`;
66
+ throw error;
67
+}
68
+
69
+export async function waitForAll(expectedLog) {
70
+ assertYieldsWereCleared(SchedulerMock);
71
+
72
+ // Create the error object before doing any async work, to get a better
73
+ // stack trace.
74
+ const error = new Error();
75
+ Error.captureStackTrace(error, waitFor);
76
+
77
+ do {
78
+ // Wait until end of current task/microtask.
79
+ await null;
80
+ if (!SchedulerMock.unstable_hasPendingWork()) {
81
+ // There's no pending work, even after a microtask. Stop flushing.
82
+ break;
83
+ }
84
+ SchedulerMock.unstable_flushAllWithoutAsserting();
85
+ } while (true);
86
+
87
+ const actualLog = SchedulerMock.unstable_clearYields();
88
+ if (equals(actualLog, expectedLog)) {
89
+ return;
90
+ }
91
+
92
+ error.message = `
93
+Expected sequence of events did not occur.
94
+
95
+${diff(expectedLog, actualLog)}
96
+`;
97
+ throw error;
98
+}
99
+
100
+export async function waitForThrow(expectedError: mixed) {
101
+ assertYieldsWereCleared(SchedulerMock);
102
+
103
+ // Create the error object before doing any async work, to get a better
104
+ // stack trace.
105
+ const error = new Error();
106
+ Error.captureStackTrace(error, waitFor);
107
+
108
+ do {
109
+ // Wait until end of current task/microtask.
110
+ await null;
111
+ if (!SchedulerMock.unstable_hasPendingWork()) {
112
+ // There's no pending work, even after a microtask. Stop flushing.
113
+ error.message = 'Expected something to throw, but nothing did.';
114
+ throw error;
115
+ }
116
+ try {
117
+ SchedulerMock.unstable_flushAllWithoutAsserting();
118
+ } catch (x) {
119
+ if (equals(x, expectedError)) {
120
+ return;
121
+ }
122
+ if (typeof x === 'object' && x !== null && x.message === expectedError) {
123
+ return;
124
+ }
125
+ error.message = `
126
+Expected error was not thrown.
127
+
128
+${diff(expectedError, x)}
129
+`;
130
+ throw error;
131
+ }
132
+ } while (true);
133
+}
134
+
135
+// TODO: This name is a bit misleading currently because it will stop as soon as
136
+// React yields for any reason, not just for a paint. I've left it this way for
137
+// now because that's how untable_flushUntilNextPaint already worked, but maybe
138
+// we should split these use cases into separate APIs.
139
+export async function waitForPaint(expectedLog) {
140
+ assertYieldsWereCleared(SchedulerMock);
141
+
142
+ // Create the error object before doing any async work, to get a better
143
+ // stack trace.
144
+ const error = new Error();
145
+ Error.captureStackTrace(error, waitFor);
146
+
147
+ // Wait until end of current task/microtask.
148
+ await null;
149
+ if (SchedulerMock.unstable_hasPendingWork()) {
150
+ // Flush until React yields.
151
+ SchedulerMock.unstable_flushUntilNextPaint();
152
+ // Wait one more microtask to flush any remaining synchronous work.
153
+ await null;
154
+ }
155
+
156
+ const actualLog = SchedulerMock.unstable_clearYields();
157
+ if (equals(actualLog, expectedLog)) {
158
+ return;
159
+ }
160
+
161
+ error.message = `
162
+Expected sequence of events did not occur.
163
+
164
+${diff(expectedLog, actualLog)}
165
+`;
166
+ throw error;
167
+}
168
+
169
+export function assertLog(expectedLog) {
170
+ const actualLog = SchedulerMock.unstable_clearYields();
171
+ if (equals(actualLog, expectedLog)) {
172
+ return;
173
+ }
174
+
175
+ const error = new Error(`
176
+Expected sequence of events did not occur.
177
+
178
+${diff(expectedLog, actualLog)}
179
+`);
180
+ Error.captureStackTrace(error, assertLog);
181
+ throw error;
182
+}
packages/internal-test-utils/index.js
new
+1
@@ -0,0 +1 @@
1
+export * from './ReactInternalTestUtils';
packages/internal-test-utils/package.json
new
+5
@@ -0,0 +1,5 @@
1
+{
2
+ "private": true,
3
+ "name": "internal-test-utils",
4
+ "version": "0.0.0"
5
+}
packages/jest-react/src/JestReact.js
+3
-1
@@ -31,10 +31,12 @@ function assertYieldsWereCleared(root) {
31
const Scheduler = root._Scheduler;
32
const actualYields = Scheduler.unstable_clearYields();
33
if (actualYields.length !== 0) {
34
- throw new Error(
34
+ const error = Error(
35
'Log of yielded values is not empty. ' +
36
'Call expect(ReactTestRenderer).unstable_toHaveYielded(...) first.',
37
);
38
+ Error.captureStackTrace(error, assertYieldsWereCleared);
39
+ throw error;
40
}
41
}
42
packages/react-reconciler/src/__tests__/ReactSuspenseWithNoopRenderer-test.js
+13
-7
@@ -3,6 +3,10 @@ let Fragment;
3
let ReactNoop;
4
let Scheduler;
5
let act;
6
+let waitFor;
7
+let waitForAll;
8
+let assertLog;
9
+let waitForPaint;
10
let Suspense;
11
let getCacheForType;
12
@@ -19,6 +23,11 @@ describe('ReactSuspenseWithNoopRenderer', () => {
23
Scheduler = require('scheduler');
24
act = require('jest-react').act;
25
Suspense = React.Suspense;
26
+ const InternalTestUtils = require('internal-test-utils');
27
+ waitFor = InternalTestUtils.waitFor;
28
+ waitForAll = InternalTestUtils.waitForAll;
29
+ waitForPaint = InternalTestUtils.waitForPaint;
30
+ assertLog = InternalTestUtils.assertLog;
31
32
getCacheForType = React.unstable_getCacheForType;
33
@@ -208,7 +217,7 @@ describe('ReactSuspenseWithNoopRenderer', () => {
217
React.startTransition(() => {
218
ReactNoop.render(<Foo />);
219
});
211
- expect(Scheduler).toFlushAndYieldThrough([
220
+ await waitFor([
221
'Foo',
222
'Bar',
223
// A suspends
@@ -226,7 +235,7 @@ describe('ReactSuspenseWithNoopRenderer', () => {
235
236
// Even though the promise has resolved, we should now flush
237
// and commit the in progress render instead of restarting.
229
- expect(Scheduler).toFlushAndYield(['D']);
238
+ await waitForPaint(['D']);
239
expect(ReactNoop).toMatchRenderedOutput(
240
<>
241
<span prop="Loading..." />
@@ -235,11 +244,8 @@ describe('ReactSuspenseWithNoopRenderer', () => {
244
</>,
245
);
246
238
- // Await one micro task to attach the retry listeners.
239
- await null;
240
-
247
// Next, we'll flush the complete content.
242
- expect(Scheduler).toFlushAndYield(['Bar', 'A', 'B']);
248
+ await waitForAll(['Bar', 'A', 'B']);
249
250
expect(ReactNoop).toMatchRenderedOutput(
251
<>
@@ -544,7 +550,7 @@ describe('ReactSuspenseWithNoopRenderer', () => {
550
ReactNoop.flushSync(() => {
551
ReactNoop.render(<App highPri="B" lowPri="1" />);
552
});
547
- expect(Scheduler).toHaveYielded(['B', '1']);
553
+ assertLog(['B', '1']);
554
expect(ReactNoop).toMatchRenderedOutput(
555
<>
556
<span prop="B" />
scripts/jest/config.build.js
+6
@@ -12,6 +12,12 @@ const NODE_MODULES_DIR =
12
// Find all folders in packages/* with package.json
13
const packagesRoot = join(__dirname, '..', '..', 'packages');
14
const packages = readdirSync(packagesRoot).filter(dir => {
15
+ if (dir === 'internal-test-utils') {
16
+ // This is an internal package used only for testing. It's OK to read
17
+ // from source.
18
+ // TODO: Maybe let's have some convention for this?
19
+ return false;
20
+ }
21
if (dir.charAt(0) === '.') {
22
return false;
23
}
scripts/jest/matchers/schedulerTestMatchers.js
+4
-1
@@ -18,11 +18,14 @@ function captureAssertion(fn) {
18
19
function assertYieldsWereCleared(Scheduler) {
20
const actualYields = Scheduler.unstable_clearYields();
21
+
22
if (actualYields.length !== 0) {
22
- throw new Error(
23
+ const error = Error(
24
'Log of yielded values is not empty. ' +
25
'Call expect(Scheduler).toHaveYielded(...) first.'
26
);
27
+ Error.captureStackTrace(error, assertYieldsWereCleared);
28
+ throw error;
29
}
30
}
31