Merge branch 'main' into fix-tmcu-311-manual-dapp-network-selection-switch-non-permitted-network

Author: vinnyhoward

.agents/skills/component-view-test/SKILL.md

@@ -56,6 +56,8 @@ tests/component-view/
 ├── mocks.ts              ← Engine + native mocks (import this first, always)
 ├── render.tsx            ← renderComponentViewScreen, renderScreenWithRoutes
 ├── stateFixture.ts       ← StateFixtureBuilder (createStateFixture)
+├── platform.ts           ← describeForPlatforms, itForPlatforms (run per iOS/Android)
+├── api-mocking/          ← HTTP API mocks (nock) — extensible, one file per feature
 ├── presets/              ← initialState<Feature>() builders — one file per feature area
 └── renderers/            ← render<Feature>View() functions — one file per feature area
 ```

.agents/skills/component-view-test/references/navigation-mocking.md

@@ -134,102 +134,62 @@ Route names live in `app/constants/navigation/Routes.ts`.
 
 ## External Service / API Mocking
 
-Some views call external services **directly** (not through Engine controllers) — e.g. a `getTrendingTokens()` function imported from a package, or a `fetch()` call to an external API. These cannot be driven through Redux state overrides.
+Some views call **external HTTP APIs** (e.g. `fetch()` to a REST endpoint). Those requests cannot be driven through Redux state. The framework provides an **api-mocking** layer using [nock](https://github.com/nock/nock) so tests intercept HTTP at the network level **without** using `jest.mock` on service modules (which would violate the “only Engine and allowed native mocks” rule).
 
-### Current pattern — jest.mock on the service module
+### Preferred pattern — nock (api-mocking folder)
 
-When a view calls an external service function directly, mock the module in a dedicated file under `tests/component-view/mocks/` and expose setup/clear helpers:
+All HTTP API mocks for component view tests live under `tests/component-view/api-mocking/`. Each feature has one file (e.g. `trending.ts`) that exports:
 
-```typescript
-// tests/component-view/mocks/myFeatureApiMocks.ts
-import { getMyFeatureData } from '@metamask/some-package';
-
-export const getMyFeatureDataMock = getMyFeatureData as jest.Mock;
+- Mock response data (e.g. `mockTrendingTokensData`)
+- A **setup** function (e.g. `setupTrendingApiFetchMock(responseData?, customReply?)`) that uses nock to intercept the endpoint
+- A **clear** function (e.g. `clearTrendingApiMocks()`) to call in `afterEach`
 
-export const mockFeatureData = [
-  { id: 'item-1', name: 'Token A', price: '100.00', change24h: 5.2 },
-  { id: 'item-2', name: 'Token B', price: '200.00', change24h: -1.8 },
-];
+Shared nock lifecycle helpers (`clearAllNockMocks`, `disableNetConnect`, `teardownNock`) are in `api-mocking/nockHelpers.ts`. To **add a new API mock** for another view, add a file `api-mocking/<feature>.ts` following the pattern in `api-mocking/trending.ts` (mock data, `setupXxxApiMock`, `clearXxxApiMocks` using `nockHelpers`), and call setup/clear in the view test’s `beforeEach`/`afterEach`.
 
-export const setupMyFeatureApiMock = (data = mockFeatureData) => {
-  getMyFeatureDataMock.mockImplementation(async () => data);
-};
-
-export const clearMyFeatureApiMocks = () => {
-  jest.clearAllMocks();
-};
-```
-
-In the test file, declare the `jest.mock` at module scope and use `beforeEach`/`afterEach` for lifecycle:
+**Example (trending):**
 
 ```typescript
-// NOTE: antipattern — only Engine and native modules should be mocked in view tests.
-// This is a temporary workaround for service functions called directly from components,
-// not through Engine. Track removal in the linked issue.
-// eslint-disable-next-line no-restricted-syntax
-jest.mock('@metamask/some-package', () => {
-  const actual = jest.requireActual('@metamask/some-package');
-  return { ...actual, getMyFeatureData: jest.fn().mockResolvedValue([]) };
-});
-
 import {
-  setupMyFeatureApiMock,
-  clearMyFeatureApiMocks,
-  mockFeatureData,
-  getMyFeatureDataMock,
-} from '../../../../tests/component-view/mocks/myFeatureApiMocks';
-
-describe('MyFeatureView', () => {
-  beforeEach(() => {
-    setupMyFeatureApiMock(mockFeatureData);
-  });
-
-  afterEach(() => {
-    clearMyFeatureApiMocks();
-  });
-
-  it('shows token list after data loads from the external service', async () => {
-    const { findByText } = renderMyFeatureWithRoutes();
+  setupTrendingApiFetchMock,
+  clearTrendingApiMocks,
+  mockTrendingTokensData,
+  mockBnbChainToken,
+} from '../../../../tests/component-view/api-mocking/trending';
+
+beforeEach(() => {
+  setupTrendingApiFetchMock(mockTrendingTokensData);
+});
+afterEach(() => {
+  clearTrendingApiMocks();
+});
 
-    expect(await findByText('Token A')).toBeOnTheScreen();
+it('user sees trending tokens section with mocked data', async () => {
+  const { findByText, queryByTestId } = renderTrendingViewWithRoutes();
+  await waitFor(async () => {
+    expect(await findByText('Ethereum')).toBeOnTheScreen();
   });
+  // assert rows with assertTrendingTokenRowsVisibility(...)
+});
 
-  it('shows only filtered results when a specific param is passed', async () => {
-    getMyFeatureDataMock.mockImplementation(async (params) => {
-      if (params?.chainId === 'eip155:56') return [mockBnbData];
-      return mockFeatureData;
-    });
-
-    const { findByText } = renderMyFeatureWithRoutes();
-    // ... interact to trigger the filter, then assert
+it('displays only BNB tokens when BNB Chain network filter is selected', async () => {
+  setupTrendingApiFetchMock(mockTrendingTokensData, (uri) => {
+    const url = new URL(uri, 'https://token.api.cx.metamask.io');
+    const chainIdsParam = url.searchParams.get('chainIds') ?? '';
+    const chainIds = chainIdsParam.split(',').map((s) => s.trim());
+    if (chainIds.length === 1 && chainIds[0] === 'eip155:56') {
+      return mockBnbChainToken;
+    }
+    return mockTrendingTokensData;
   });
+  const { getByTestId, findByText, queryByTestId } =
+    renderTrendingViewWithRoutes();
+  // ... navigate to full view, open network filter, select BNB Chain
+  // assert visible: [BNB], missing: [ETH, BTC, UNI]
 });
 ```
 
-> ⚠️ **This is a known antipattern.** The golden rule is that only Engine and allowed native modules should be mocked in `*.view.test.*` files. Mocking a service module directly bypasses the ESLint guard (note the `eslint-disable` comment). Always link to a tracking issue and plan to migrate to a proper solution.
-
-### Future pattern — Mock Service Worker (MSW)
-
-> 📌 **Placeholder — no example exists yet in this codebase.**
+### Fallback — jest.mock on the service module (antipattern)
 
-For views that call HTTP endpoints directly (via `fetch`), the intended approach is [Mock Service Worker (msw)](https://mswjs.io/), which intercepts requests at the network level without needing `jest.mock`. This keeps tests closer to real behavior and avoids the module-mock antipattern.
+When a view calls an external **function** (not `fetch`) from a package and that function cannot be replaced by nock (e.g. no HTTP), you may mock the module in a file under `tests/component-view/mocks/` and use setup/clear helpers. This requires an `eslint-disable` and is a **known antipattern**; prefer moving the integration to an HTTP API and using api-mocking, or drive data through Engine/Redux when possible.
 
-When the first MSW-based view test is written, document the setup here:
-
-```typescript
-// TODO: Add MSW setup example once the first test using it is merged.
-// Expected shape:
-//
-// import { setupServer } from 'msw/node';
-// import { http, HttpResponse } from 'msw';
-//
-// const server = setupServer(
-//   http.get('https://api.example.com/tokens', () =>
-//     HttpResponse.json(mockTokensData),
-//   ),
-// );
-//
-// beforeAll(() => server.listen());
-// afterEach(() => server.resetHandlers());
-// afterAll(() => server.close());
-```
+> ⚠️ Only Engine and allowed native modules should be mocked in `*.view.test.*` files. Mocking a service module directly bypasses the ESLint guard. Always link to a tracking issue and plan to migrate to nock (api-mocking) or Engine/Redux.

.agents/skills/component-view-test/references/reference.md

@@ -203,6 +203,7 @@ yarn eslint <path/to/test.tsx>
 | Engine + native mocks          | `tests/component-view/mocks.ts`                                |
 | render, renderScreenWithRoutes | `tests/component-view/render.tsx`                              |
 | StateFixtureBuilder            | `tests/component-view/stateFixture.ts`                         |
+| HTTP API mocks (nock)          | `tests/component-view/api-mocking/` (per-feature)              |
 | Feature renderers (per view)   | `tests/component-view/renderers/` (e.g. bridge, wallet)        |
 | Feature presets (per view)     | `tests/component-view/presets/` (e.g. bridge, wallet)          |
 | DeepPartial type               | `app/util/test/renderWithProvider`                             |

.agents/skills/component-view-test/references/writing-tests.md

@@ -12,6 +12,7 @@ Before writing any test, read:
 - Any existing `*.view.test.tsx` for the same component
 - The relevant preset(s) in `tests/component-view/presets/`
 - The relevant renderer(s) in `tests/component-view/renderers/`
+- If the view calls an external HTTP API: `tests/component-view/api-mocking/` and any existing `api-mocking/<feature>.ts` for that API (see navigation-mocking.md, External Service / API Mocking)
 
 ---
 
@@ -194,6 +195,38 @@ const defaultBridgeWithTokens = (overrides?: Record<string, unknown>) => {
 
 Then each test only specifies its delta from this baseline.
 
+### describe / it and platform (iOS + Android)
+
+Import from `tests/component-view/platform`. All helpers accept an optional **filter** (3rd arg): `'ios'` | `'android'` | `['ios','android']` | `{ only: 'ios' }` | `{ skip: ['android'] }`. Env: `TEST_OS=ios` or `TEST_OS=android` to run only one OS.
+
+| Helper                                                                  | Use                                                                                                           |
+| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `describeForPlatforms(name, define, filter?)`                           | One describe per OS. Inside, `define({ os })`; use `it()` or `itForPlatforms()` — each runs once per that OS. |
+| `itForPlatforms(name, (ctx) => {}, filter?)`                            | One `it` per OS. Callback receives `{ os }`.                                                                  |
+| `itOnlyForPlatforms(name, fn, filter?)`                                 | Same as `itForPlatforms` but registers `it.only`.                                                             |
+| `itEach(table)(name, (row) => {}, filter?)`                             | One `it` per table row × per OS. Use `$key` in name to interpolate row fields.                                |
+| `describeEach(table)(name, (row) => { it('...', () => {}); }, filter?)` | One describe per row × per OS. Use `$key` in name.                                                            |
+| `getTargetPlatforms(filter?)`                                           | Returns `['ios','android']` (or filtered list) for custom loops.                                              |
+
+Example — `itEach` (each case runs on iOS and Android):
+
+```typescript
+import { itEach } from '../../../../../../tests/component-view/platform';
+
+const cases = [
+  { name: 'renders empty', amount: '0' },
+  { name: 'displays fiat', amount: '1' },
+];
+itEach(cases)('$name', ({ amount }) => {
+  const { findByDisplayValue } = renderDefault({
+    bridge: { sourceAmount: amount },
+  });
+  expect(findByDisplayValue(amount)).toBeOnTheScreen();
+});
+```
+
+Jest modifiers (`it.only`, `it.skip`, `describe.only`, `describe.skip`) work as usual inside these blocks.
+
 ### Minimal template
 
 ```typescript

.agents/skills/e2e-test/SKILL.md

@@ -3,7 +3,8 @@ name: e2e-test
 description:
   Add and fix Detox E2E tests (smoke and regression) for MetaMask Mobile using
   withFixtures, Page Objects, and tests/framework. Use when creating a new spec,
-  fixing a failing E2E test, or adding page objects and selectors.
+  fixing a failing E2E test, adding page objects and selectors, or adding
+  MetaMetrics analytics expectations (analyticsExpectations).
 ---
 
 # E2E Test Builder — Skill
@@ -44,6 +45,10 @@ Task → What do you need?
 │  → Open references/mocking.md (testSpecificMock, setupRemoteFeatureFlagsMock, setupMockRequest)
 │  → When writing the spec: open references/writing-tests.md
 │
+├─ MetaMetrics / Segment analytics assertions (`analyticsExpectations` on `withFixtures`)
+│  → Open [tests/docs/analytics-e2e.md](../../../tests/docs/analytics-e2e.md) (config shape, teardown order, presets under `tests/helpers/analytics/expectations/`, `runAnalyticsExpectations`)
+│  → When wiring a spec: still follow references/writing-tests.md for `withFixtures` usage
+│
 └─ Run tests, debug failures, or self-review
    → Open references/running-tests.md (build check, detox commands, common failures, retry patterns)
 ```
@@ -84,9 +89,10 @@ Step 5 → Iterate (fix → lint → run) until green
 
 Documentation is split by **action**. Open only the reference that matches what you are doing.
 
-| Action                                        | File                                                       | When to open it                                                                                   |
-| --------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| **Writing or updating a spec**                | [references/writing-tests.md](references/writing-tests.md) | New spec file, spec structure, FixtureBuilder patterns, smoke/regression templates.               |
-| **Page Objects and selectors**                | [references/page-objects.md](references/page-objects.md)   | Create or update POM classes, selector/testId conventions, Matchers/Gestures/Assertions API.      |
-| **API and feature flag mocking**              | [references/mocking.md](references/mocking.md)             | testSpecificMock, setupRemoteFeatureFlagsMock, setupMockRequest, shared mock files.               |
-| **Running tests, debugging, fixing failures** | [references/running-tests.md](references/running-tests.md) | Build check, detox run commands, lint/tsc, common failures table, retry patterns, iteration loop. |
+| Action                                        | File                                                                | When to open it                                                                                                    |
+| --------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| **Writing or updating a spec**                | [references/writing-tests.md](references/writing-tests.md)          | New spec file, spec structure, FixtureBuilder patterns, smoke/regression templates.                                |
+| **Page Objects and selectors**                | [references/page-objects.md](references/page-objects.md)            | Create or update POM classes, selector/testId conventions, Matchers/Gestures/Assertions API.                       |
+| **API and feature flag mocking**              | [references/mocking.md](references/mocking.md)                      | testSpecificMock, setupRemoteFeatureFlagsMock, setupMockRequest, shared mock files.                                |
+| **MetaMetrics / analytics expectations**      | [tests/docs/analytics-e2e.md](../../../tests/docs/analytics-e2e.md) | `analyticsExpectations` on `withFixtures`, declarative checks, presets in `tests/helpers/analytics/expectations/`. |
+| **Running tests, debugging, fixing failures** | [references/running-tests.md](references/running-tests.md)          | Build check, detox run commands, lint/tsc, common failures table, retry patterns, iteration loop.                  |