Skip to content

test(cv): ban fake timers in component-view tests and document the Predict flake rules - #38995

Merged
matallui merged 5 commits into
mainfrom
chore/cv-fake-timer-lint
Nov 5, 2026
Merged

matallui merged 5 commits into
mainfrom
chore/cv-fake-timer-lint

Conversation

@matallui

@matallui matallui commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Description

What changed

ESLint (.eslintrc.js)

  • The **/*.view.test.{js,ts,tsx,jsx} override already bans jest.mock through no-restricted-syntax. This adds a second entry to that same list. It errors on jest.useFakeTimers, jest.useRealTimers, jest.advanceTimersByTime, jest.runAllTimers, and jest.runOnlyPendingTimers:
    • 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."
  • ESLint does not merge no-restricted-syntax lists across overrides, so the entry sits in the existing list rather than in a second override for the same files.
  • A new override for tests/component-view/**/*.{ts,tsx} carries only the fake-timer entry. The jest.mock ban does not reach the shared helpers (mocks.ts mocks Engine).
  • Unit tests (*.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.

  • Rule 4 (no fake timers) now names the lint check and says where time-dependent behaviour goes: a unit test, or fixtures already in the target state. It also says never to widen a budget to cover a timer, and that Date.now is real in component-view tests, because testSetupView.js does not load testSetup.js, which freezes Date.now for unit tests.
  • New Golden Rules 11–14:
    • Call-count leaks: mockClear() on a shared Engine or messenger mock in beforeEach. The signature is Expected number of calls: N, Received: M: the test passes alone and fails after another test.
    • Remounts: a findBy* result is valid only until the next state change. Await a loaded-only marker, then re-query with getBy*.
    • Explicit timeouts: a { timeout } needs a comment that names the async boundary. A raised budget alone is not a fix.
    • Fix a flake at its cause (links to the new section).
  • Self-review checklist rows 10–14 cover the same rules. Row 3's fix column now points to unit tests or target-state fixtures.
  • Diagnosis rows for Expected number of calls: N, Received: M, for Unable to find node on an unmounted component, and for element could not be found in the element tree after an await.
  • New "Fixing a flake" section: name the cause, reproduce it locally with a seed or under load, show the fix holds under the same condition, and do not merge a change whose only change is a longer timeout.
  • Code samples: the slippage example drops its { timeout: 1000 }, which was the default anyway. The findByTestId timeout 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 1454155912 on 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, 84 tests/component-view/**/*.{ts,tsx} files):

$ NODE_OPTIONS="--max-old-space-size=12288" yarn eslint 'app/**/*.view.test.{ts,tsx}' 'tests/component-view/**/*.{ts,tsx}' -f unix
.../TrendingView/TrendingView.view.test.tsx:77:37: `ReactTestInstance` is deprecated. ... [Warning/@typescript-eslint/no-deprecated]
.../ExploreSearchScreen/ExploreSearchScreen.view.test.tsx:42:37: `ReactTestInstance` is deprecated. ... [Warning/@typescript-eslint/no-deprecated]
.../ExploreSearchScreen/ExploreSearchScreen.view.test.tsx:51:45: `ReactTestInstance` is deprecated. ... [Warning/@typescript-eslint/no-deprecated]

3 problems
exit=0

Zero errors, and none from the new rule. The 3 warnings were already there. tests/component-view/mocks.ts (which calls jest.mock) passes, which shows the jest.mock ban 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.

== app/components/UI/Predict/tmp-fake-timer.view.test.tsx
app/components/UI/Predict/tmp-fake-timer.view.test.tsx:1:1: 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. [Error/no-restricted-syntax]

1 problem
exit=1
== tests/component-view/tmp-fake-timer.ts
tests/component-view/tmp-fake-timer.ts:1:1: 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. [Error/no-restricted-syntax]

1 problem
exit=1
== app/util/tmp-fake-timer.test.ts
exit=0

3. Changed files

$ yarn eslint .eslintrc.js
exit=0
$ yarn prettier --check docs/testing/component-view-tests.md .eslintrc.js
Checking formatting...
All matched files use Prettier code style!
exit=0

package.json defines no markdown lint script. Markdown is covered by Prettier through lint-staged.

Follow-up, not in this PR

13 existing violations of "no nested find* inside waitFor". 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:354
  • app/components/Views/ActivityList/ActivityList.view.test.tsx:134, :164
  • app/components/Views/ActivityScreen/ActivityScreen.view.test.tsx:1042, :1280, :1393, :1933, :2017, :2096, :2144
  • app/components/Views/ChoosePassword/ChoosePassword.view.test.tsx:444
  • app/components/Views/ImportNewSecretRecoveryPhrase/ImportNewSecretRecoveryPhrase.view.test.tsx:75
  • app/components/Views/TrendingView/TrendingView.view.test.tsx:161

Matching 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)

  • I've tested on Android (N/A: no runtime change)
    • Ideally on a mid-range device; emulator is acceptable
  • I've tested with a power user scenario (N/A: no runtime change)
    • Use these power-user SRPs to import wallets with many accounts and tokens
  • I've instrumented key operations with Sentry traces for production performance metrics (N/A: no runtime change)

For performance guidelines and tooling, see the Performance Guide.

Pre-merge reviewer checklist

  • I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed).
  • I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots.

Note

Low Risk
Changes are ESLint overrides and testing documentation only; no production or runtime behavior is modified.

Overview
Adds a shared ESLint cvFakeTimerBan rule that errors on the full Jest fake-timer API (including *Async variants) in *.view.test.* and tests/component-view/**, while leaving unit tests unchanged. A separate override for shared CV helpers applies the timer ban without the existing jest.mock restriction so mocks.ts can still mock Engine.

docs/testing/component-view-tests.md expands Golden Rule 4 (no fake timers, no real sleeps, real Date.now, allowed Date.now spies) 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 nested findBy*).

tests/component-view/AGENTS.md briefly 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.

@matallui matallui self-assigned this Nov 5, 2026
@github-actions

github-actions Bot commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

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.

@matallui
matallui marked this pull request as draft November 5, 2026 13:33
@matallui
matallui marked this pull request as ready for review November 5, 2026 14:11

@racitores racitores left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tests/component-view/AGENTS.md L114 still recommends 'real delays' — should be aligned with the new rule 4.

Comment thread .eslintrc.js Outdated
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.',

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we add the Async variants, plus advanceTimersToNextTimer, setSystemTime, runAllTicks and clearAllTimers? Right now jest.advanceTimersByTimeAsync() passes the lint.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread .eslintrc.js Outdated
Comment on lines 434 to 464
"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.',
},
],
},

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd extract the rule object into a constant (const cvFakeTimerBan = {…}) and reuse it in both overrides so they don't drift.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in ebdd5fe. Both overrides now use one cvFakeTimerBan constant, defined near the top of .eslintrc.js.

Comment thread docs/testing/component-view-tests.md Outdated
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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread docs/testing/component-view-tests.md Outdated
| 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 |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread docs/testing/component-view-tests.md Outdated

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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`.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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()).

Comment thread docs/testing/component-view-tests.md Outdated
| `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 |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This row contradicts 'CI is slow is not a cause'. Should we update it to point to 'Fixing a flake'?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

cursor[bot]

This comment was marked as resolved.

- 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.
@matallui
matallui force-pushed the chore/cv-fake-timer-lint branch from 1da9da3 to ebdd5fe Compare November 5, 2026 14:26
@matallui
matallui requested a review from a team as a code owner November 5, 2026 14:26
@MetaMask MetaMask deleted a comment from cursor Bot Nov 5, 2026
@MetaMask MetaMask deleted a comment from cursor Bot Nov 5, 2026
@MetaMask MetaMask deleted a comment from cursor Bot Nov 5, 2026
@matallui

matallui commented Nov 5, 2026

Copy link
Copy Markdown
Contributor Author

Fixed the tests/component-view/AGENTS.md line from the review summary in ebdd5fe. It no longer suggests real delays. It now says no fake timers and no real sleeps, wait on the outcome with waitFor or findBy*, and move timer behaviour to a unit test.

@matallui
matallui enabled auto-merge November 5, 2026 14:34
@sonarqubecloud

sonarqubecloud Bot commented Nov 5, 2026

Copy link
Copy Markdown

@matallui
matallui added this pull request to the merge queue Nov 5, 2026
Merged via the queue into main with commit 4758ed3 Nov 5, 2026
89 checks passed
@matallui
matallui deleted the chore/cv-fake-timer-lint branch November 5, 2026 17:24
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 5, 2026
@metamask-ci metamask-ci Bot added the release-8.20.0 Issue or pull request that will be included in release 8.20.0 label Nov 5, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

release-8.20.0 Issue or pull request that will be included in release 8.20.0 size-S team-predict Predict team

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants