Repository navigation
test(cv): ban fake timers in component-view tests and document the Predict flake rules - #38995
Conversation
…edict flake rules
|
CLA Signature Action: All authors have signed the CLA. You may need to manually re-run the blocking PR check if it doesn't pass in a few minutes. |
racitores
left a comment
There was a problem hiding this comment.
tests/component-view/AGENTS.md L114 still recommends 'real delays' — should be aligned with the new rule 4.
| selector: | ||
| "CallExpression[callee.object.name='jest'][callee.property.name=/^(useFakeTimers|useRealTimers|advanceTimersByTime|runAllTimers|runOnlyPendingTimers)$/]", | ||
| message: | ||
| 'Component-view tests must not use fake timers. Keep time behaviour in a unit test, or serve fixtures already in the target state. See docs/testing/component-view-tests.md.', |
There was a problem hiding this comment.
Should we add the Async variants, plus advanceTimersToNextTimer, setSystemTime, runAllTicks and clearAllTimers? Right now jest.advanceTimersByTimeAsync() passes the lint.
There was a problem hiding this comment.
Done in ebdd5fe. The ban now covers the whole fake-timer API. That is useFakeTimers, useRealTimers, advanceTimersByTime, advanceTimersToNextTimer, runAllTimers and runOnlyPendingTimers, each with its Async variant, plus runAllTicks, setSystemTime and clearAllTimers. jest.advanceTimersByTimeAsync() now fails lint in *.view.test.* files and in tests/component-view/**. No existing component-view file calls any of them.
| "CallExpression[callee.object.name='jest'][callee.property.name=/^(useFakeTimers|useRealTimers|advanceTimersByTime|runAllTimers|runOnlyPendingTimers)$/]", | ||
| message: | ||
| 'Component-view tests must not use fake timers. Keep time behaviour in a unit test, or serve fixtures already in the target state. See docs/testing/component-view-tests.md.', | ||
| }, | ||
| ], | ||
| }, | ||
| }, | ||
| { | ||
| // Shared component-view helpers keep the base no-restricted-syntax bans | ||
| // and add the fake-timer ban. The jest.mock ban above does not apply | ||
| // here (mocks.ts mocks Engine). | ||
| files: ['tests/component-view/**/*.{ts,tsx}'], | ||
| rules: { | ||
| 'no-restricted-syntax': [ | ||
| 'error', | ||
| { | ||
| selector: 'WithStatement', | ||
| message: 'With statements are not allowed', | ||
| }, | ||
| { | ||
| selector: 'SequenceExpression', | ||
| message: 'Sequence expressions are not allowed', | ||
| }, | ||
| { | ||
| selector: | ||
| "CallExpression[callee.object.name='jest'][callee.property.name=/^(useFakeTimers|useRealTimers|advanceTimersByTime|runAllTimers|runOnlyPendingTimers)$/]", | ||
| message: | ||
| 'Component-view tests must not use fake timers. Keep time behaviour in a unit test, or serve fixtures already in the target state. See docs/testing/component-view-tests.md.', | ||
| }, | ||
| ], | ||
| }, |
There was a problem hiding this comment.
I'd extract the rule object into a constant (const cvFakeTimerBan = {…}) and reuse it in both overrides so they don't drift.
There was a problem hiding this comment.
Done in ebdd5fe. Both overrides now use one cvFakeTimerBan constant, defined near the top of .eslintrc.js.
| 3. **Reuse presets and renderers** — never rebuild the full state manually from scratch. | ||
|
|
||
| 4. **No fake timers** — never use `jest.useFakeTimers()`, `jest.advanceTimersByTime()`, or `jest.useRealTimers()`. | ||
| 4. **No fake timers** — never use `jest.useFakeTimers()`, `jest.advanceTimersByTime()`, or `jest.useRealTimers()`. ESLint enforces this in `*.view.test.*` files and in `tests/component-view/**` (also `jest.runAllTimers()` and `jest.runOnlyPendingTimers()`). Test countdowns, debounces, and expiry in a unit test, where fake timers are allowed, or serve fixtures already in the target state (an expired quote, an ended game). Never widen a budget to cover a timer. |
There was a problem hiding this comment.
Some CV tests freeze Date.now (PredictHome L220, PredictPortfolioScreen L182, BridgeView L134). Can we state when that's allowed? With real timers it breaks lodash debounce.
There was a problem hiding this comment.
Added to rule 4 in ebdd5fe. A jest.spyOn(Date, 'now') stub is allowed when the test moves the clock across a window the code compares against and leaves timers real. PredictHome and PredictPortfolioScreen do this for the 60-second Balance focus window. Restore the spy in the same test. Never freeze the clock on a screen that uses lodash debounce, because timeSinceLastCall stays 0 and the trailing call never runs.
BridgeView is a different case. Its Date.now = () => new Date().getTime() is left over from the unit setup and does nothing here. jest.config.view.js replaces setupFilesAfterEnv, so testSetup.js never loads and Date.now is already real. The doc says not to copy it.
| | 9 | **Import order** — `mocks.ts` is first; remaining order follows project ESLint rules | Ensure `mocks.ts` is the very first import; reorder the rest as needed | | ||
| | 10 | **Call counts start clean** — every `toHaveBeenCalledTimes` on a shared Engine / messenger mock has `mockClear()` (or `mockReset()`) on that mock in `beforeEach` | Add the clear; check with `--randomize` | | ||
| | 11 | **No `findBy*` result held across a remount** — when the tree can remount after the `await`, the test awaits a loaded-only marker and re-queries with `getBy*` before asserting | Await the loaded marker, then re-query | | ||
| | 12 | **No real timers raced** — countdown, debounce, and expiry behaviour lives in a unit test or in target-state fixtures, not in a widened `waitFor` | Move it to a unit test or change the fixture | |
There was a problem hiding this comment.
Real waits (await new Promise(r => setTimeout(r, 50)), e.g. PredictEventScreen L2289) are the same race against the clock. Should we ban them explicitly?
There was a problem hiding this comment.
Yes. Rule 4 bans them in ebdd5fe, and there is a matching "What NOT to Do" example and checklist row 12. A test should wait on the outcome with waitFor or findBy* instead. A zero-delay flush (setTimeout(r, 0)) before asserting that something did not happen is still allowed. Existing sleeps, like the one in PredictEventScreen, get fixed when their test is next modified, not in this PR.
|
|
||
| 12. **A `findBy*` result is valid only until the next state change** — if the component can remount between the `await` and the assertion (a query resolving, a loading branch swapping for the loaded one), the held node detaches. Await a marker that only the loaded tree renders, then re-query with `getBy*`. Signatures: `Unable to find node on an unmounted component` or `element could not be found in the element tree` right after an `await`. | ||
|
|
||
| 13. **An explicit `{ timeout }` names its async boundary** — pass `{ timeout }` to `waitFor` or `findBy*` only with a comment that names the async boundary needing it (a debounce, a chained query). A raised budget alone is not a fix. |
There was a problem hiding this comment.
There are 426 timeout: across 48 CV files and almost none have a comment. Does this apply only to new/modified code? Is a single comment where TIMEOUT_MS is defined enough?
There was a problem hiding this comment.
It applies to new and modified waits, and rule 13 says so now (ebdd5fe). One comment where a shared constant such as TIMEOUT_MS is defined is enough, as long as it names the boundary that needs the extra time. The existing 426 stay as they are until someone touches those tests.
|
|
||
| 10. **Filter / segmentation tests must assert both sides** — after selecting a filter, assert both what appears (positive `findByTestId`) and what disappears (negative `queryByTestId(...).not.toBeOnTheScreen()`). | ||
|
|
||
| 11. **Clear call history before asserting call counts** — `toHaveBeenCalledTimes` on a shared Engine or `controllerMessenger.call` mock also counts calls made by earlier tests. Call `mockClear()` on that mock in `beforeEach` (`mockReset()` when a test changes implementations). Signature: `Expected number of calls: N, Received: M`; passes alone, fails after another test. |
There was a problem hiding this comment.
Instead of per-file mockClear(), why not clearMocks: true in jest.config.view.js? It only clears call history, not the implementations from mocks.ts. There are already 4 files counting calls without clearing.
There was a problem hiding this comment.
I agree it is the better fix, but I would rather do it in a separate PR. clearMocks: true changes how all ~100 component-view files run. A test that renders in beforeAll and counts calls later would start failing, so it needs a full suite run before it lands. This PR only changes lint and docs. Rule 11 stays until that change merges, and then it can shrink to a pointer at the config.
|
|
||
| 11. **Clear call history before asserting call counts** — `toHaveBeenCalledTimes` on a shared Engine or `controllerMessenger.call` mock also counts calls made by earlier tests. Call `mockClear()` on that mock in `beforeEach` (`mockReset()` when a test changes implementations). Signature: `Expected number of calls: N, Received: M`; passes alone, fails after another test. | ||
|
|
||
| 12. **A `findBy*` result is valid only until the next state change** — if the component can remount between the `await` and the assertion (a query resolving, a loading branch swapping for the loaded one), the held node detaches. Await a marker that only the loaded tree renders, then re-query with `getBy*`. Signatures: `Unable to find node on an unmounted component` or `element could not be found in the element tree` right after an `await`. |
There was a problem hiding this comment.
I'd add concrete remount signals: a skeleton/loading view with the same testID (as in #38949), a loading→loaded branch switch, or a key change. Also worth noting that expect(await findBy*) (L213) carries the same risk.
There was a problem hiding this comment.
Added in ebdd5fe. Rule 12 now lists the remount signals. These are a skeleton or loading view that reuses the loaded testID (as in #38949), a switch from the loading branch to the loaded one, and a key change on the component or a parent. It also flags expect(await findBy*(...)). I rewrote the doc examples that used that pattern, L213 and the Trending one, to await waitFor(() => expect(getBy*(...)).toBeOnTheScreen()).
| | `Warning: An update was not wrapped in act(...)` | Async state update not awaited | Use `await waitFor(...)` | | ||
| | `No QueryClient set` | Missing provider — not in Engine mock | Add to mocks.ts or wrap with QueryClientProvider in renderer | | ||
| | Flakey number assertions | Non-deterministic exchange rates | Add `deterministicFiat: true` | | ||
| | Test passes locally, fails in CI | Time-sensitive assertions | Use `waitFor` not inline assertions after interactions | |
There was a problem hiding this comment.
This row contradicts 'CI is slow is not a cause'. Should we update it to point to 'Fixing a flake'?
There was a problem hiding this comment.
Updated in ebdd5fe. The row now says "CI is slow" is not a cause, lists what a slower runner tends to expose (an order leak, a real timer, a remount), and points to Fixing a flake.
- Share one cvFakeTimerBan object across the *.view.test.* and tests/component-view/** overrides, and add the Async variants, advanceTimersToNextTimer, setSystemTime, runAllTicks and clearAllTimers. - Rule 4: ban real sleeps, state when a Date.now spy is allowed, and note that BridgeView's Date.now reassignment is a no-op. - Rule 12: name the remount signals and the expect(await findBy*) gap; fix the doc examples that used that pattern. - Rule 13: scope the timeout-comment rule to new and modified waits. - Point the CI-only failure row at Fixing a flake, and align tests/component-view/AGENTS.md.
1da9da3 to
ebdd5fe
Compare
|
Fixed the |
|



Description
What changed
ESLint (
.eslintrc.js)**/*.view.test.{js,ts,tsx,jsx}override already bansjest.mockthroughno-restricted-syntax. This adds a second entry to that same list. It errors onjest.useFakeTimers,jest.useRealTimers,jest.advanceTimersByTime,jest.runAllTimers, andjest.runOnlyPendingTimers:CallExpression[callee.object.name='jest'][callee.property.name=/^(useFakeTimers|useRealTimers|advanceTimersByTime|runAllTimers|runOnlyPendingTimers)$/]no-restricted-syntaxlists across overrides, so the entry sits in the existing list rather than in a second override for the same files.tests/component-view/**/*.{ts,tsx}carries only the fake-timer entry. Thejest.mockban does not reach the shared helpers (mocks.tsmocks Engine).*.test.*outside view tests) are not affected.Docs (
docs/testing/component-view-tests.md)The wording follows MetaMask/skills#217, the matching skill change. Existing rule numbers stay as they are, and the new rules are added after them.
Date.nowis real in component-view tests, becausetestSetupView.jsdoes not loadtestSetup.js, which freezesDate.nowfor unit tests.mockClear()on a shared Engine or messenger mock inbeforeEach. The signature isExpected number of calls: N, Received: M: the test passes alone and fails after another test.findBy*result is valid only until the next state change. Await a loaded-only marker, then re-query withgetBy*.{ timeout }needs a comment that names the async boundary. A raised budget alone is not a fix.Expected number of calls: N, Received: M, forUnable to find node on an unmounted component, and forelement could not be found in the element treeafter anawait.{ timeout: 1000 }, which was the default anyway. ThefindByTestIdtimeout example now names its boundary. "What NOT to Do" gains a held-findBy*-across-remount example.Why
The expiry test in PredictOrderFlow waited on a real timer. It failed on three CI runs:
Other Predict component-view failures from the same investigation:
For the call-history leak, seed
1454155912on the PredictFeed balance test reproduces it: the test fails with three calls.Related flake-fix PRs (Cursor-authored): #38947, #38949, #38959.
Validation
1. ESLint over all component-view tests and helpers (149
app/**/*.view.test.{ts,tsx}files, 84tests/component-view/**/*.{ts,tsx}files):Zero errors, and none from the new rule. The 3 warnings were already there.
tests/component-view/mocks.ts(which callsjest.mock) passes, which shows thejest.mockban does not apply to the helpers.2. The rule fires where it should, and only there. Each temporary file contained
jest.useFakeTimers();. All three files were deleted before commit.3. Changed files
package.jsondefines no markdown lint script. Markdown is covered by Prettier throughlint-staged.Follow-up, not in this PR
13 existing violations of "no nested
find*insidewaitFor". No lint rule is added for them here. They need an owner's decision: fix them, or add the rule with a ratchet.app/components/UI/Ramp/Views/BuildQuote/BuildQuote.view.test.tsx:354app/components/Views/ActivityList/ActivityList.view.test.tsx:134,:164app/components/Views/ActivityScreen/ActivityScreen.view.test.tsx:1042,:1280,:1393,:1933,:2017,:2096,:2144app/components/Views/ChoosePassword/ChoosePassword.view.test.tsx:444app/components/Views/ImportNewSecretRecoveryPhrase/ImportNewSecretRecoveryPhrase.view.test.tsx:75app/components/Views/TrendingView/TrendingView.view.test.tsx:161Matching skill change
MetaMask/skills#217 (MetaMask/skills#217) adds the same rules to
testing/mobile-testing.Changelog
CHANGELOG entry: null
Related issues
Refs: #38947, #38949, #38959, MetaMask/skills#217
Manual testing steps
N/A. This changes only lint config and docs, and there is no app behaviour to test. The lint behaviour is covered under Validation above.
Screenshots/Recordings
N/A. No UI change.
Before
N/A
After
N/A
Pre-merge author checklist
Performance checks (if applicable)
trace()for usage andaddTokenfor an exampleFor performance guidelines and tooling, see the Performance Guide.
Pre-merge reviewer checklist
Note
Low Risk
Changes are ESLint overrides and testing documentation only; no production or runtime behavior is modified.
Overview
Adds a shared ESLint
cvFakeTimerBanrule that errors on the full Jest fake-timer API (including*Asyncvariants) in*.view.test.*andtests/component-view/**, while leaving unit tests unchanged. A separate override for shared CV helpers applies the timer ban without the existingjest.mockrestriction somocks.tscan still mock Engine.docs/testing/component-view-tests.mdexpands Golden Rule 4 (no fake timers, no real sleeps, realDate.now, allowedDate.nowspies) and adds rules 11–14 for mock call-count leaks,findBy*held across remounts, documented{ timeout }, and fixing flakes at the root cause. The self-review checklist, failure diagnosis table, Fixing a flake section, and doc examples are updated to match (e.g.waitFor+getBy*instead of nestedfindBy*).tests/component-view/AGENTS.mdbriefly aligns agent guidance with the new timer/sleep rules.Reviewed by Cursor Bugbot for commit 07a2f2a. Bugbot is set up for automated code reviews on this repo. Configure here.