Merge branch 'main' into MMQA-1367-serve-test-snaps-locally

chrisleewilcox · web-flow · commit d35945844cbc · 2026-04-22T07:24:09.000-07:00
diff --git a/.agents/skills/e2e-test/references/mocking.md b/.agents/skills/e2e-test/references/mocking.md
@@ -127,15 +127,17 @@ Add a mock for every such request to ensure test determinism.
 
 ## Features using WebSockets or complex transport
 
-Some features depend on **WebSockets** or other non-HTTP transport (e.g. Perps/HyperLiquid, real-time data). The HTTP mock server cannot intercept these. The repo uses two patterns:
+Some features depend on **WebSockets** or other non-HTTP transport (e.g. Perps/HyperLiquid, real-time data). The HTTP mock server cannot intercept these. The repo uses three patterns:
 
-1. **Controller-level mocking** — A mixin under `tests/controller-mocking/mock-config/` replaces provider SDK touchpoints so E2E runs with stable, test-controlled data. Example: `perps-controller-mixin.ts` for HyperLiquid. See **`tests/docs/CONTROLLER_MOCKING.md`** for when and how to use it.
-2. **Command queue / test server** — Tests that need to drive the app (e.g. inject state or commands) can use **`CommandQueueServer`** (`tests/framework/fixtures/CommandQueueServer.ts`). Enable it in the fixture with `useCommandQueueServer: true`. Used by Perps specs (e.g. `tests/smoke/perps/perps-add-funds.spec.ts`, `tests/regression/perps/perps-limit-long-fill.spec.ts`). The app consumes the queue in E2E context.
+1. **WebSocket mocking** — A `LocalWebSocketServer` (`tests/websocket/server.ts`) intercepts production WebSocket connections via URL rewriting in the E2E shim. Protocol-specific mocks handle subscribe/unsubscribe and push notifications. See **`tests/docs/WEBSOCKET_MOCKING.md`** for full usage guide and how to add new services. Example: `tests/websocket/account-activity-mocks.ts` for AccountActivity.
+2. **Controller-level mocking** — A mixin under `tests/controller-mocking/mock-config/` replaces provider SDK touchpoints so E2E runs with stable, test-controlled data. Example: `perps-controller-mixin.ts` for HyperLiquid. See **`tests/docs/CONTROLLER_MOCKING.md`** for when and how to use it.
+3. **Command queue / test server** — Tests that need to drive the app (e.g. inject state or commands) can use **`CommandQueueServer`** (`tests/framework/fixtures/CommandQueueServer.ts`). Enable it in the fixture with `useCommandQueueServer: true`. Used by Perps specs (e.g. `tests/smoke/perps/perps-add-funds.spec.ts`, `tests/regression/perps/perps-limit-long-fill.spec.ts`). The app consumes the queue in E2E context.
 
 **When adding support for a new feature that uses WebSockets or similar:**
 
-- Follow the **same pattern** as existing features (controller mixin and/or CommandQueueServer).
-- Implement under `tests/controller-mocking/mock-config/` or extend the command-queue protocol as needed.
+- For WebSocket services: add a service config in `tests/websocket/constants.ts` and a protocol mock. See `tests/docs/WEBSOCKET_MOCKING.md`.
+- For SDK-level mocking: implement under `tests/controller-mocking/mock-config/`.
+- For test-driven commands: extend the command-queue protocol as needed.
 - Add or update **tests/specs** that cover the mock infrastructure and the E2E flow.
 
-Prefer HTTP mocking whenever the feature’s API is plain HTTP; use controller mocking or the command server only when necessary.
+Prefer HTTP mocking whenever the feature’s API is plain HTTP; use WebSocket mocking for WS connections; use controller mocking or the command server only when necessary.
diff --git a/app/component-library/components-temp/ButtonFilter/ButtonFilter.tsx b/app/component-library/components-temp/ButtonFilter/ButtonFilter.tsx
@@ -9,6 +9,7 @@ import { ButtonFilterProps } from './ButtonFilter.types';
  * @deprecated Please update your code to use `ButtonFilter` from `@metamask/design-system-react-native`.
  * The API may have changed — compare props before migrating.
  * @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/src/components/ButtonFilter/README.md}
+ * @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/MIGRATION.md#buttonfilter-component Migration docs}
  * @since @metamask/design-system-react-native@0.11.0
  */
 const ButtonFilter = ({
diff --git a/app/component-library/components-temp/Buttons/ButtonHero/ButtonHero.tsx b/app/component-library/components-temp/Buttons/ButtonHero/ButtonHero.tsx
@@ -60,6 +60,7 @@ const ButtonHeroInner = ({
  * @deprecated Please update your code to use `ButtonHero` from `@metamask/design-system-react-native`.
  * The API may have changed - compare props before migrating.
  * @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/src/components/ButtonHero/README.md}
+ * @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/MIGRATION.md#buttonhero-component Migration docs}
  */
 const ButtonHero = (props: ButtonBaseProps) => (
   <ThemeProvider theme={Theme.Light}>
diff --git a/app/component-library/components/Banners/Banner/foundation/BannerBase/BannerBase.tsx b/app/component-library/components/Banners/Banner/foundation/BannerBase/BannerBase.tsx
@@ -28,6 +28,7 @@ import {
  * @deprecated Please update your code to use `BannerBase` from `@metamask/design-system-react-native`.
  * The API may have changed — compare props before migrating.
  * @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/src/components/BannerBase/README.md}
+ * @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/MIGRATION.md#bannerbase-component Migration docs}
  * @since @metamask/design-system-react-native@0.11.0
  */
 const BannerBase: React.FC<BannerBaseProps> = ({
diff --git a/app/component-library/components/BottomSheets/BottomSheet/BottomSheet.tsx b/app/component-library/components/BottomSheets/BottomSheet/BottomSheet.tsx
@@ -35,6 +35,7 @@ import BottomSheetDialog, {
  * @deprecated Please update your code to use `BottomSheet` from `@metamask/design-system-react-native`.
  * The API may have changed — compare props before migrating.
  * @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/src/components/BottomSheet/README.md}
+ * @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/MIGRATION.md#bottomsheet-component Migration docs}
  * @since @metamask/design-system-react-native@0.11.0
  */
 const BottomSheet = forwardRef<BottomSheetRef, BottomSheetProps>(
diff --git a/app/component-library/components/BottomSheets/BottomSheetFooter/BottomSheetFooter.tsx b/app/component-library/components/BottomSheets/BottomSheetFooter/BottomSheetFooter.tsx
@@ -22,6 +22,7 @@ import {
  * @deprecated Please update your code to use `BottomSheetFooter` from `@metamask/design-system-react-native`.
  * The API may have changed — compare props before migrating.
  * @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/src/components/BottomSheets/BottomSheetFooter/README.md}
+ * @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/MIGRATION.md#bottomsheetfooter-component Migration docs}
  * @since @metamask/design-system-react-native@0.7.0
  */
 const BottomSheetFooter: React.FC<BottomSheetFooterProps> = ({
diff --git a/app/component-library/components/BottomSheets/BottomSheetHeader/BottomSheetHeader.tsx b/app/component-library/components/BottomSheets/BottomSheetHeader/BottomSheetHeader.tsx
@@ -23,6 +23,7 @@ import {
  * @deprecated Please update your code to use `BottomSheetHeader` from `@metamask/design-system-react-native`.
  * The API may have changed - compare props before migrating.
  * @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/src/components/BottomSheetHeader/README.md}
+ * @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/MIGRATION.md#bottomsheetheader-component Migration docs}
  */
 const BottomSheetHeader: React.FC<BottomSheetHeaderProps> = ({
   style,
diff --git a/app/component-library/components/Buttons/Button/foundation/ButtonBase/ButtonBase.tsx b/app/component-library/components/Buttons/Button/foundation/ButtonBase/ButtonBase.tsx
@@ -24,6 +24,7 @@ import {
  * @deprecated Please update your code to use `ButtonBase` from `@metamask/design-system-react-native`.
  * The API may have changed - compare props before migrating.
  * @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/src/components/ButtonBase/README.md}
+ * @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/MIGRATION.md#buttonbase-component Migration docs}
  */
 const ButtonBase = ({
   label,
diff --git a/app/component-library/components/Buttons/Button/variants/ButtonLink/ButtonLink.tsx b/app/component-library/components/Buttons/Button/variants/ButtonLink/ButtonLink.tsx
@@ -34,6 +34,7 @@ import {
  *
  * @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/src/components/TextButton/README.md | TextButton}
  * @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/src/components/Button/README.md | Button}
+ * @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/MIGRATION.md#textbutton-component-buttonlink Migration docs}
  */
 const ButtonLink: React.FC<ButtonLinkProps> = ({
   style,
diff --git a/app/component-library/components/Buttons/ButtonIcon/ButtonIcon.tsx b/app/component-library/components/Buttons/ButtonIcon/ButtonIcon.tsx
@@ -21,6 +21,7 @@ import {
  * @deprecated Please update your code to use `ButtonIcon` from `@metamask/design-system-react-native`.
  * The API may have changed — compare props before migrating.
  * @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/src/components/ButtonIcon/README.md}
+ * @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/MIGRATION.md#buttonicon-component Migration docs}
  */
 const ButtonIcon = ({
   iconName,
diff --git a/app/component-library/components/Checkbox/Checkbox.tsx b/app/component-library/components/Checkbox/Checkbox.tsx
@@ -25,6 +25,7 @@ import {
  * @deprecated Please update your code to use `Checkbox` from `@metamask/design-system-react-native`.
  * The API may have changed — compare props before migrating.
  * @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/src/components/Checkbox/README.md}
+ * @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/MIGRATION.md#checkbox-component Migration docs}
  */
 const Checkbox = ({
   style,
diff --git a/app/component-library/components/Form/TextField/TextField.tsx b/app/component-library/components/Form/TextField/TextField.tsx
@@ -27,6 +27,7 @@ import {
  * @deprecated Please update your code to use `TextField` from `@metamask/design-system-react-native`.
  * The API may have changed — compare props before migrating.
  * @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/src/components/TextField/README.md}
+ * @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/MIGRATION.md#textfield-component Migration docs}
  * @since @metamask/design-system-react-native@0.9.0
  */
 const TextField = React.forwardRef<TextInput | null, TextFieldProps>(
diff --git a/app/component-library/components/Form/TextField/foundation/Input/Input.tsx b/app/component-library/components/Form/TextField/foundation/Input/Input.tsx
@@ -21,6 +21,7 @@ import { INPUT_TEST_ID } from './Input.constants';
  * @deprecated Please update your code to use `Input` from `@metamask/design-system-react-native`.
  * The API may have changed — compare props before migrating.
  * @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/src/components/Input/README.md}
+ * @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/MIGRATION.md#input-controlled-only-requirement Migration docs}
  * @since @metamask/design-system-react-native@0.7.0
  */
 const Input = React.forwardRef<TextInput, InputProps>(
diff --git a/app/component-library/components/List/ListItem/ListItem.tsx b/app/component-library/components/List/ListItem/ListItem.tsx
@@ -20,6 +20,7 @@ import {
  * @deprecated Please update your code to use `ListItem` from `@metamask/design-system-react-native`.
  * The API may have changed — compare props before migrating.
  * @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/src/components/ListItem/README.md}
+ * @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/MIGRATION.md#listitem-component Migration docs}
  * @since @metamask/design-system-react-native@0.11.0
  */
 const ListItem: React.FC<ListItemProps> = ({
diff --git a/package.json b/package.json
@@ -244,8 +244,8 @@
     "@metamask/core-backend": "^6.2.0",
     "@metamask/delegation-controller": "^2.0.2",
     "@metamask/delegation-deployments": "^1.0.0",
-    "@metamask/design-system-react-native": "^0.17.0",
-    "@metamask/design-system-twrnc-preset": "^0.4.1",
+    "@metamask/design-system-react-native": "^0.19.0",
+    "@metamask/design-system-twrnc-preset": "^0.4.2",
     "@metamask/design-tokens": "^8.3.0",
     "@metamask/earn-controller": "^12.0.0",
     "@metamask/eip-5792-middleware": "^2.0.0",
diff --git a/tests/docs/README.md b/tests/docs/README.md
@@ -18,6 +18,7 @@
 - **Selectors (`tests/selectors/`)**: Element selectors organized by feature
 - **Fixtures (`tests/framework/fixtures/`)**: Test data and state management
 - **API Mocking (`tests/api-mocking/`)**: Comprehensive API mocking system
+- **WebSocket Mocking (`tests/websocket/`)**: Local WebSocket server for mocking real-time connections ([docs](WEBSOCKET_MOCKING.md))
 
 **Core E2E Framework Classes:**
 
diff --git a/tests/docs/WEBSOCKET_MOCKING.md b/tests/docs/WEBSOCKET_MOCKING.md
@@ -0,0 +1,166 @@
+# WebSocket Mocking in E2E Tests
+
+The E2E framework includes a local WebSocket server that intercepts production WebSocket connections during tests. This enables deterministic testing of features that use real-time data streams (e.g., account activity notifications).
+
+## Architecture
+
+```
+App (E2E build)
+  │
+  ├─ shim.js rewrites wss://gateway.api.cx.metamask.io → ws://localhost:<port>
+  │
+  └─ LocalWebSocketServer (tests/websocket/server.ts)
+       │
+       └─ Protocol mock (e.g. account-activity-mocks.ts)
+            └─ Handles subscribe/unsubscribe, sends mock notifications
+```
+
+**Key files:**
+
+| File                                        | Purpose                                                                          |
+| ------------------------------------------- | -------------------------------------------------------------------------------- |
+| `tests/websocket/server.ts`                 | `LocalWebSocketServer` — generic WS server implementing the `Resource` interface |
+| `tests/websocket/constants.ts`              | Service definitions (production URL, fallback port, launch arg key)              |
+| `tests/websocket/account-activity-mocks.ts` | Protocol-specific mock for AccountActivity WS                                    |
+| `tests/framework/fixtures/FixtureHelper.ts` | Creates and manages the WS server per test run                                   |
+
+## How It Works
+
+1. `withFixtures` in `FixtureHelper.ts` creates a `LocalWebSocketServer` instance for every test run
+2. The server is started via `startResourceWithRetry` with automatic port allocation
+3. `setupAccountActivityMocks()` attaches protocol-specific message handlers
+4. The allocated port is passed to the app via launch args (`accountActivityWsPort`)
+5. The app's E2E shim rewrites the production WebSocket URL to `ws://localhost:<port>`
+6. After the test, the server is stopped and connections are cleaned up
+
+## Using the Existing AccountActivity Mock
+
+The AccountActivity WebSocket mock is available in every test automatically. For most tests, you don't need to do anything — the mock server handles subscribe/unsubscribe handshakes in the background.
+
+To explicitly test WebSocket behavior, use the helpers from `account-activity-mocks.ts`:
+
+```typescript
+import {
+  waitForAccountActivitySubscription,
+  getAccountActivitySubscriptionCount,
+  waitForAccountActivityDisconnection,
+  createBalanceUpdateNotification,
+} from '../../websocket/account-activity-mocks';
+```
+
+### Waiting for a subscription
+
+```typescript
+// Set up the waiter BEFORE the action that triggers the connection
+const subscriptionPromise = waitForAccountActivitySubscription();
+await loginToApp();
+const subscriptionId = await subscriptionPromise;
+```
+
+### Checking subscription count
+
+```typescript
+assertEqual(getAccountActivitySubscriptionCount(), 1);
+```
+
+### Waiting for disconnection
+
+```typescript
+await device.sendToHome();
+await waitForAccountActivityDisconnection();
+```
+
+### Sending a mock balance update
+
+```typescript
+const notification = createBalanceUpdateNotification({
+  subscriptionId,
+  channel: 'account-activity.v1',
+  address: '0x1234...',
+  chain: 'eip155:1',
+  updates: [
+    {
+      asset: { fungible: true, type: 'native', unit: 'ETH', decimals: 18 },
+      postBalance: { amount: '1000000000000000000' },
+      transfers: [
+        { from: '0x0...', to: '0x1234...', amount: '500000000000000000' },
+      ],
+    },
+  ],
+});
+
+// Broadcast to all connected clients
+accountActivityWsServer.sendMessage(JSON.stringify(notification));
+```
+
+### Example spec
+
+See `tests/smoke/account-activity/web-socket-connection.spec.ts` for a complete example with three tests covering subscribe-on-login, resubscribe-after-background, and resubscribe-after-lock.
+
+## Adding a New WebSocket Service Mock
+
+To mock a new WebSocket service (e.g., a new real-time data feed):
+
+### 1. Define the service in `tests/websocket/constants.ts`
+
+```typescript
+export const MY_NEW_WS: WebSocketServiceConfig = {
+  url: 'wss://my-service.example.com',
+  fallbackPort: 8090, // pick a unique port
+  launchArgKey: 'myNewWsPort',
+};
+
+// Add it to the services array
+export const WS_SERVICES: WebSocketServiceConfig[] = [
+  ACCOUNT_ACTIVITY_WS,
+  MY_NEW_WS,
+];
+```
+
+### 2. Create a protocol mock in `tests/websocket/`
+
+```typescript
+// tests/websocket/my-service-mocks.ts
+import type LocalWebSocketServer from './server.ts';
+import { WebSocket } from 'ws';
+
+export async function setupMyServiceMocks(
+  server: LocalWebSocketServer,
+): Promise<void> {
+  const wsServer = server.getServer();
+
+  wsServer.on('connection', (socket: WebSocket) => {
+    // Handle incoming messages
+    socket.on('message', (data) => {
+      const raw = data.toString();
+      // Parse and respond based on your protocol
+    });
+
+    // Send initial data on connection
+    socket.send(JSON.stringify({ type: 'connected' }));
+  });
+}
+```
+
+### 3. Register in `FixtureHelper.ts`
+
+Add the server creation, startup, and cleanup alongside the existing `accountActivityWsServer` pattern:
+
+```typescript
+const myNewWsServer = new LocalWebSocketServer('myNewService');
+// ...
+await startResourceWithRetry(ResourceType.MY_NEW_WS, myNewWsServer);
+await setupMyServiceMocks(myNewWsServer);
+```
+
+Pass the port via launch args:
+
+```typescript
+[MY_NEW_WS.launchArgKey]: isAndroid
+  ? `${MY_NEW_WS.fallbackPort}`
+  : `${myNewWsServer.getServerPort()}`,
+```
+
+### 4. Register the port in PortManager
+
+Add the new `ResourceType` and fallback port in `tests/framework/PortManager.ts` so the framework can manage port allocation and Android `adb reverse` forwarding.
diff --git a/yarn.lock b/yarn.lock

Original file line number	Diff line number	Diff line change
`@@ -34,6 +34,7 @@ import {`
`34`	`34`	`*`
`35`	`35`	`* @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/src/components/TextButton/README.md \| TextButton}`
`36`	`36`	`* @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/src/components/Button/README.md \| Button}`
	`37`	`+ * @see {@link https://github.com/MetaMask/metamask-design-system/blob/main/packages/design-system-react-native/MIGRATION.md#textbutton-component-buttonlink Migration docs}`
`37`	`38`	`*/`
`38`	`39`	`const ButtonLink: React.FC<ButtonLinkProps> = ({`
`39`	`40`	`style,`