Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

### Changed

- Add a `Rules (enforced by lint)` checklist to `testing/mobile-testing` component-view guidance: the flake anti-patterns ESLint rejects on `*.view.test.tsx` (arbitrary `jest.mock`, fake timers, `find*` nested in `waitFor`, awaiting a skeleton or sibling, pressing a node held across a remount, `clearAllMocks` without `mockReset`, fixed sleeps, and bare timeout bumps). Require `yarn eslint` on new CV tests before finishing.
- Mark `planning`, `planning-spec`, and `jira-brief` `stable` and `base: true`, so a default install includes them. `planning` wins over a generic plan, brainstorm, design, or spec skill only when the engineer did not name another skill for that job. `planning` calls `jira-brief` only when the message has a Jira browse URL or the engineer explicitly refers to a Jira ticket. Otherwise it says nothing about Jira. A planning delegation never asks whether a bare token is a ticket. Opt out with `yarn skills --exclude planning/planning,planning/planning-spec,planning/jira-brief --save`.
- Update the `assets/react-compiler-migration` skill: run `react-compiler-marker` from outside an offline checkout (install to a temp prefix, `bin/cli.js` entry point, pinned 0.2.0), stop on stale scan findings instead of editing a file the marker already reports clean, document effect-scoped shared-value writes compiling on compiler 1.0.0 while callback/worklet writes still need `set()`/`get()`, and add a validated try/catch example (ASSETS-4331) showing value-block diagnostics cover the `try` block only — catch-side ternaries are fine and the fix keeps the protected span by calling a helper from inside the `try`.

Expand Down
128 changes: 124 additions & 4 deletions domains/testing/skills/mobile-testing/references/component-view.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,10 @@ Your job is to figure out whether the user needs to **write a new test**, **fix
Task → What do you need?
├─ Write new test or update after change
│ → Read component + existing tests
│ → Follow Rules (enforced by lint) in this file
│ → Open component-view/writing-tests.md (use cases, coverage, renderer/preset, file structure)
│ → If test needs navigation: also open component-view/navigation-mocking.md
│ → After writing: run tests, then open component-view/reference.md for self-review
│ → After writing: yarn eslint <file>, run tests, then open component-view/reference.md for self-review
│
├─ Fix failing test
│ → Run: yarn jest -c jest.config.view.js <path> --runInBand --silent --coverage=false
Expand All @@ -48,7 +49,7 @@ Do not read the full reference files until the decision tree or workflow sends y

Component view tests are **integration-level** tests that test views through real Redux state — no mocked hooks or selectors. They live alongside the component as `ComponentName.view.test.tsx` and use a dedicated framework in `tests/component-view/`.

Key constraint: **only Engine and allowed native modules may be mocked** (enforced at runtime by `app/util/test/testSetupView.js` and by ESLint override in `.eslintrc.js` for `**/*.view.test.*`).
Key constraint: **only Engine and allowed native modules may be mocked** (enforced at runtime by `app/util/test/testSetupView.js` and by ESLint override in `.eslintrc.js` for `**/*.view.test.*`). The full lint list is *Rules (enforced by lint)*.


## The Framework at a Glance
Expand All @@ -67,7 +68,7 @@ tests/component-view/

## Workflow (summary)

- **Write new test**: Read component and existing tests → list use cases and map to test patterns → check coverage and deduplicate → use or create renderer/preset → write test (use `renderScreenWithRoutes` if asserting navigation). Every test must have at least one of: `fireEvent`, `waitFor`/`findBy`, `store.dispatch`/`act`, or Engine spy (no render-only scenarios). Run tests, then run the self-review checklist in `component-view/reference.md`.
- **Write new test**: Read component and existing tests → list use cases and map to test patterns → check coverage and deduplicate → use or create renderer/preset → write test (use `renderScreenWithRoutes` if asserting navigation). Every test must have at least one of: `fireEvent`, `waitFor`/`findBy`, `store.dispatch`/`act`, or Engine spy (no render-only scenarios). Follow *Rules (enforced by lint)*. Run `yarn eslint <file>`, run tests, then run the self-review checklist in `component-view/reference.md`.
- **Fix failing test**: Run with `jest.config.view.js` → identify error type from the table in `component-view/reference.md` (Diagnosing Failures) → apply the fix (remove disallowed mock, add state override, add preset, wrap in `waitFor`, add `deterministicFiat`, etc.) → re-run.
- **Update after change**: Same as write — review existing tests, extend preset/renderer if needed, update tests, run and self-review.

Expand Down Expand Up @@ -95,8 +96,125 @@ yarn test:view:coverage:folder app/components/UI/MyFeature
For run-by-name, watch mode, or other options, see `component-view/reference.md` (Run the Tests).


## Rules (enforced by lint)

ESLint on `*.view.test.tsx` in metamask-mobile rejects this list (`no-restricted-syntax` in `.eslintrc.js`, override `**/*.view.test.*`). Arbitrary `jest.mock` is already an error. The fake-timer API is already an error ([metamask-mobile#38995](https://github.com/MetaMask/metamask-mobile/pull/38995)). The remaining rules are the ESLint PR in progress. [skills#217](https://github.com/MetaMask/skills/pull/217) is merged: the Golden Rules below and [`component-view/reference.md`](component-view/reference.md) keep the diagnosis and the failure signatures. Write the good form here, and cite those rules by name.

Run lint on every new or edited CV test before finishing. A green Jest run does not cover these.

```bash
yarn eslint <path/to/Component.view.test.tsx>
```

**1. No arbitrary `jest.mock`** — a view test drives behaviour through Redux. Another mock hides that wiring. Engine and `react-native-device-info` are already mocked in `tests/component-view/mocks.ts` (*Only mock Engine and allowed native modules*).

```typescript
// ❌
jest.mock('../../hooks/useQuote', () => ({ useQuote: jest.fn() }));

// ✅ override the preset — no jest.mock in the test file
renderMyView({ overrides: { bridge: { sourceAmount: '1' } } });
```

**2. No fake timers** — `useFakeTimers`, `advanceTimersByTime`, `runAllTimers`, `setSystemTime`, and the `*Async` variants stall real queries and flake in CI. Keep countdowns, debounces, and expiry in a unit test, or serve a fixture already in the target state (*Keep time-dependent behaviour out of view tests*). `Date.now` is real here; do not freeze it. `jest.spyOn(Date, 'now')` is allowed when timers stay real.

```typescript
// ❌
jest.useFakeTimers();
jest.advanceTimersByTime(1000);

// ✅ no timer API — fixture already ended, or cover the countdown in a unit test
expect(await findByTestId(MyViewSelectorsIDs.ENDED_BADGE)).toBeOnTheScreen();
```

**3. No `find*` inside `waitFor`** — `findBy*` already polls (`waitFor` + `getBy`, default 1000 ms). Nesting shares that budget, so CI fails with a bare `Timed out in waitFor.` (*Do not nest `find*` inside `waitFor`*).

```typescript
// ❌
await waitFor(async () => {
expect(await findByText('Token A')).toBeOnTheScreen();
});

// ✅ findBy* already waits
expect(await findByText('Token A')).toBeOnTheScreen();

// ✅ or waitFor + a synchronous getBy* when the assert is a count
await waitFor(() => {
expect(getAllByTestId(MyViewSelectorsIDs.ROW)).toHaveLength(3);
});
```

**4. Await the subject, not a skeleton or sibling** — header, list, and actions load on their own. A sibling skeleton leaving the screen does not mean the control under test is mounted (*Do not wait on a sibling loading proxy*).

```typescript
// ❌
await waitFor(() => {
expect(queryByTestId(MyViewSelectorsIDs.DETAILS_SKELETON)).toBeNull();
});
fireEvent.press(getByTestId(MyViewSelectorsIDs.SHARE_BUTTON));

// ✅ await the subject, then re-query to press
expect(await findByTestId(MyViewSelectorsIDs.SHARE_BUTTON)).toBeOnTheScreen();
fireEvent.press(getByTestId(MyViewSelectorsIDs.SHARE_BUTTON));
```

**5. Re-query after a remount, then press** — a `findBy*` node detaches when the loading tree swaps for the loaded one. Pressing the held node is a no-op (`Unable to find node on an unmounted component`) (*A `findBy*` result is valid only until the next state change*).

```typescript
// ❌
const card = await findByTestId(MyViewSelectorsIDs.CARD);
fireEvent.press(card);

// ✅ await a marker that only the loaded tree renders, then query again
await findByTestId(MyViewSelectorsIDs.LOADED_CONTENT);
fireEvent.press(getByTestId(MyViewSelectorsIDs.CARD));
```

**6. No `clearAllMocks` without `mockReset`** — `jest.clearAllMocks()` drops call history and keeps the last `mockImplementation` / `mockResolvedValue`. The next test flakes with `Expected number of calls: N, Received: M`. Use `mockReset()` (or restore) in `beforeEach` when a case changes an implementation; use `mockClear()` only to zero a call count (*Reset mock implementations between tests*).

```typescript
// ❌
beforeEach(() => {
jest.clearAllMocks();
});

// ✅
beforeEach(() => {
quoteSpy.mockReset();
});
```

**7. No fixed sleeps** — `setTimeout` of N ms races the clock the same way a widened `waitFor` does. Await the observable outcome. A zero-delay flush (`setTimeout(r, 0)`) before asserting that something did not happen is still allowed.

```typescript
// ❌
await new Promise((resolve) => setTimeout(resolve, 50));
expect(getByText('Quote refreshed')).toBeOnTheScreen();

// ✅
await waitFor(() => expect(getByText('Quote refreshed')).toBeOnTheScreen());
```

**8. No bare timeout bumps** — pass `{ timeout }` only with a comment that names the async boundary (a debounce, a chained query). A raised budget alone is not a fix. The default is 1000 ms (*Do not nest `find*` inside `waitFor`*, *Fix a flake at its cause*).

```typescript
// ❌ raised budget, no named boundary
await waitFor(() => expect(getByText('Ready')).toBeOnTheScreen(), {
timeout: 5000,
});

// ✅
// Quote-preview debounce; the default 1000 ms expires first.
await waitFor(() => expect(getByText('Preview')).toBeOnTheScreen(), {
timeout: 5000,
});
```


## Golden Rules (Enforced)

Diagnosis for *Rules (enforced by lint)*. Cite these by name, not by number.

1. **Only mock Engine and allowed native modules** — no arbitrary `jest.mock()` in `*.view.test.*` files. Allowed:
- `../../app/core/Engine`
- `../../app/core/Engine/Engine`
Expand All @@ -107,7 +225,7 @@ For run-by-name, watch mode, or other options, see `component-view/reference.md`

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()`. For time-dependent UI, see *Keep time-dependent behaviour out of view tests*.
4. **No fake timers** — never use `jest.useFakeTimers()`, `jest.advanceTimersByTime()`, `jest.useRealTimers()`, or the rest of the fake-timer API (ESLint rejects it). For time-dependent UI, see *Keep time-dependent behaviour out of view tests*. A real `setTimeout` sleep is the same race — see *No fixed sleeps* under *Rules (enforced by lint)*.

5. **Test behavior, not snapshots** — use `toBeOnTheScreen()`, `not.toBeOnTheScreen()`, interaction assertions.

Expand Down Expand Up @@ -149,6 +267,8 @@ For run-by-name, watch mode, or other options, see `component-view/reference.md`

24. **Run format:check before declaring done** — run `npx prettier --check <file>` (or `yarn format:check`) on the new test file and every new supporting file (renderer, preset, api-mock). Auto-fix with `npx prettier --write <file>` if needed, then re-check.

25. **Run lint before declaring done** — run `yarn eslint <file>` on every new or edited `*.view.test.tsx`. See *Rules (enforced by lint)*. A green Jest run does not cover these.


## Reference files (when to use)

Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Running Tests, Self-Review, and Diagnosing Failures

Use this reference when you need to **run** component view tests, **self-review** after tests pass, or **diagnose and fix** failures. It also covers assertion patterns, deterministic fiat, and What NOT to Do.
Use this reference when you need to **run** component view tests, **self-review** after tests pass, or **diagnose and fix** failures. It also covers assertion patterns, deterministic fiat, and What NOT to Do. Lint-enforced anti-patterns are [Rules (enforced by lint)](../component-view.md#rules-enforced-by-lint).

Reference: [SKILL.md](../SKILL.md) · [Writing Tests](writing-tests.md) · [Navigation & Mocking](navigation-mocking.md)

Expand Down Expand Up @@ -48,6 +48,9 @@ yarn jest -c jest.config.view.js <file> --watch

# Coverage for a feature folder (use this, not --coverage directly — avoids OOM)
yarn test:view:coverage:folder app/components/UI/MyFeature

# Lint — required before finishing. See Rules (enforced by lint).
yarn eslint <file>
```

---
Expand All @@ -60,7 +63,7 @@ Before declaring the task done, go through this checklist for every test written
| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
| 1 | **No render scenarios** — every test has at least one `fireEvent`, `waitFor`/`findBy`, `store.dispatch`, or Engine spy | Rewrite the test to add a user interaction or system reaction |
| 2 | **No selector mocking** — no `(useSelector as jest.Mock).mockImplementation(...)` anywhere in the file | Remove; drive behavior through state overrides instead |
| 3 | **No fake timers** — no `jest.useFakeTimers()`, `jest.advanceTimersByTime()`, or `jest.useRealTimers()` | Remove fake timers; move time behaviour to a unit test or serve fixtures already in the target state (*Keep time-dependent behaviour out of view tests*) |
| 3 | **No fake timers** — no jest fake-timer API (`useFakeTimers`, `advanceTimersByTime`, `setSystemTime`, `*Async` variants) | Remove fake timers; move time behaviour to a unit test or serve fixtures already in the target state (*Keep time-dependent behaviour out of view tests*) |
| 4 | **Data-completeness test exists** — if the view loads data asynchronously (API, Engine polling), there is one test that waits for the load and validates all fields of all items in the full base mock using `within()` per row | Add the data-completeness test |
| 5 | **Filter/segmentation tests have paired assertions** — every test that selects a filter or changes a network asserts both what appears (`findByTestId`) AND what disappears (`queryByTestId(...).not.toBeOnTheScreen()`) for each item from the previous set. Spy-only checks (refetch count / analytics) are **not** enough | Seed distinct before/after rows; add the missing negative assertions |
| 6 | **No raw strings in `getByTestId` / `findByTestId` / `queryByTestId`** — all test IDs reference constants from the component's `ComponentName.testIds.ts` | Create or update the testIds file; replace raw strings with constants |
Expand All @@ -79,10 +82,11 @@ Before declaring the task done, go through this checklist for every test written
| 19 | **Negative asserts wait until the positive path could have rendered** — do not `queryBy*` absence immediately after mount | Await owning skeleton/load, then assert absence |
| 20 | **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` |
| 21 | **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 |
| 22 | **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 |
| 22 | **No real timers raced** — countdown, debounce, and expiry behaviour lives in a unit test or in target-state fixtures, not in a widened `waitFor` or a fixed `setTimeout` sleep | Move it to a unit test, change the fixture, or `waitFor` the outcome |
| 23 | **A flake fix names its cause** — the cause is reproduced locally (seed or load) and the fix passes under that condition; it is not only a longer timeout | Reproduce first; see Fixing a Flake |
| 24 | **Tests pass** — run `yarn jest -c jest.config.view.js <file> --runInBand --silent --coverage=false` and all tests are green. | Fix the failing test before marking the task done |
| 25 | **Format check passes** — run `yarn format:check` (or `npx prettier --check <file>`) on the new test file and every new supporting file (renderer, preset, api-mock). | Run `npx prettier --write <file>` to auto-fix, then re-run the check |
| 26 | **Lint is clean** — `yarn eslint <file>` passes on every new or edited `*.view.test.tsx`. See [Rules (enforced by lint)](../component-view.md#rules-enforced-by-lint). | Fix the violation. Do not disable the rule to keep a sleep, a nested `find*`, or a bare timeout. |

---

Expand Down Expand Up @@ -367,7 +371,7 @@ yarn jest -c jest.config.view.js <path> --runInBand --silent --coverage=false
# Coverage for a feature folder
yarn test:view:coverage:folder app/components/UI/MyFeature

# Lint check
# Lint check — required before finishing. See Rules (enforced by lint) in component-view.md.
yarn eslint <path/to/test.tsx>
```

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ Reference: [SKILL.md](../SKILL.md) · [Navigation & Mocking](navigation-mocking.

Before writing any test, read:

- [Rules (enforced by lint)](../component-view.md#rules-enforced-by-lint) — ESLint rejects that list on `*.view.test.tsx`. Run `yarn eslint <file>` before finishing.
- The component file under test
- Any existing `*.view.test.tsx` for the same component
- The relevant preset(s) in `tests/component-view/presets/`
Expand Down
Loading