test(e2e): serve snap tarballs from local binaries (MMQA-1366)

[chrisleewilcox]

Description

Eliminates live npm registry tarball downloads during flask E2E tests by serving snap binaries from local files via MockServer.

Problem: iOS flask shards were timing out at 35m (25% shard failure rate) because installSnap() fetched tarballs live from registry.npmjs.org. The first test in a shard would hang on the registry fetch, cascade-failing every subsequent test.

Solution: Pre-download all 21 snap tarballs and serve them from MockServer's /proxy handler via testSpecificMock, matching the pattern used by the Extension team in MetaMask/metamask-extension#32555.

Changes:

• scripts/update-snap-binary.ts — CLI tool to download snap tarballs from npm (yarn update-snap-binary --<snap>@<version>). Includes input sanitization and path traversal guards (CodeQL).
• 42 binary files in tests/api-mocking/mock-response-data/snaps/snap-binaries-and-headers/ — pre-downloaded tarballs + response headers for all 21 snaps
• tests/api-mocking/mock-response-data/snaps/snap-binary-mocks.ts — createSnapMock() registers mockttp rules to intercept npm registry tarball URLs and return local binaries. 21 exported convenience functions, one per snap.
• 23 snap spec files — each now has a testSpecificMock calling the appropriate mock function(s)
• tests/api-mocking/MockServerE2E.ts — retains the npm:@metamask/ regex allowlist bypass in isUrlAllowed(), since the ethereum-provider and multichain-provider snaps make a direct GET to a malformed npm: URI that bypasses the /proxy route
• .gitattributes — marks snap binary .txt files as binary to prevent CRLF corruption

How requests are protected:

There are two distinct request paths for snap installation:

1. Tarball downloads (via /proxy) — fully protected. The app fetches tarballs through GET /proxy?url=https://registry.npmjs.org/@metamask/.... Our testSpecificMock intercepts these with a forGet('/proxy').matching(...) rule. If the mock doesn't match (e.g. snap version updated but local binary wasn't refreshed), the request falls through to the proxy catch-all handler, which decodes the URL to registry.npmjs.org/.... Since registry.npmjs.org is not in the allowlist, isUrlAllowed() returns false → the request is tracked in _liveRequests → validateLiveRequests() fails the test. A stale binary will never silently hit the live registry.

2. Malformed npm: URI requests (direct, not via /proxy) — harmless. The ethereum-provider and multichain-provider snaps make a direct GET to a malformed URL like https://https//npm:@metamask/ethereum-provider-example-snap. These hit the unmatched request handler, not /proxy. The npm URI bypass in isUrlAllowed() catches these so they don't fail validateLiveRequests(). They always fail with DNS errors (getaddrinfo ENOTFOUND https) because the URL is unparseable — they can never reach a live server.

Keeping binaries up to date:

Local binaries are updated manually via yarn update-snap-binary --<snap-name>@<version>. This is the same pattern the Extension team uses (MetaMask/metamask-extension#32555) — neither repo has CI automation to detect stale binaries. The safety net is that a version mismatch causes the mock to not match, triggering a clear test failure via validateLiveRequests() rather than silently falling through to the live registry.

Changelog

CHANGELOG entry: null

Related issues

Fixes: MMQA-1366
Parent: MMQA-1364

Manual testing steps

Feature: Local snap binary serving in flask E2E tests

  Scenario: Snap installs use local binaries instead of live npm registry
    Given the iOS simulator has a flask build installed
    And MockServer is running with testSpecificMock configured

    When user runs a flask snap test (e.g. test-snap-rpc.spec.ts)
    Then the snap installs successfully from local binary files
    And no requests are made to registry.npmjs.org for tarballs
    And validateLiveRequests() does not report any unmocked requests

  Scenario: Multi-snap test installs two snaps from local binaries
    Given the iOS simulator has a flask build installed

    When user runs test-snap-rpc.spec.ts (installs bip32 + json-rpc snaps)
    Then both snaps install successfully
    And cross-snap RPC produces the expected public key

Screenshots/Recordings

Before

Specs had no testSpecificMock — snap tarballs were fetched live from registry.npmjs.org through the mock server's /proxy fallback:

// test-snap-bip-32.spec.ts (before)
await withFixtures(
  {
    fixture: new FixtureBuilder().withMultiSRPKeyringController().build(),
    restartDevice: true,
    skipReactNativeReload: true,
    // no testSpecificMock — live npm fetch via /proxy fallback
  },
  async () => { ... }
);

After

Each spec now declares a testSpecificMock that registers mockttp rules to intercept the npm tarball URL and return the pre-downloaded local binary:

// test-snap-bip-32.spec.ts (after)
await withFixtures(
  {
    fixture: new FixtureBuilder().withMultiSRPKeyringController().build(),
    restartDevice: true,
    skipReactNativeReload: true,
    testSpecificMock: async (mockServer: Mockttp) => {
      await mockBip32Snap(mockServer);
    },
  },
  async () => { ... }
);

Multi-snap tests call multiple mock functions:

// test-snap-rpc.spec.ts — installs bip32 + json-rpc
testSpecificMock: async (mockServer: Mockttp) => {
  await mockBip32Snap(mockServer);
  await mockJsonRpcSnap(mockServer);
},

Pre-merge author checklist

• I've followed MetaMask Contributor Docs and MetaMask Mobile Coding Standards.
• I've completed the PR template to the best of my ability
• I've included tests if applicable
• I've documented my code using JSDoc format if applicable
• I've applied the right labels on the PR (see labeling guidelines). Not required for external contributors.

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

Medium Risk
Medium risk because it changes Snap tarball download behavior in NpmLocation (URL rewriting in E2E) and adds a large set of binary fixtures; failures would mainly impact E2E reliability rather than production behavior due to the isE2E gate.

Overview
Stops live npm tarball downloads during E2E Snap installs by rewriting NpmLocation.fetchNpmTarball to route registry tarball fetches through the local MockServer /proxy when isE2E is true (using a new getMockServerPortInApp value populated from launch args).

Adds a local snap-binary fixture system: a new yarn update-snap-binary script to download and persist tarballs + selected response headers, .gitattributes rules to treat the .txt tarballs as binary, and snap-binary-mocks.ts helpers that register mockttp rules to serve those local binaries.

Updates Snap smoke specs to use testSpecificMock to install snaps from local binaries (and tweaks a few assertions/sync behaviors for iOS vs Android), and expands unit coverage in npm.test.ts to verify the E2E URL rewrite behavior.

^{Reviewed by Cursor Bugbot for commit d9a4ae6. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

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.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81.96%. Comparing base (3751d9a) to head (d9a4ae6).
⚠️ Report is 262 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #29282      +/-   ##
==========================================
+ Coverage   81.54%   81.96%   +0.41%     
==========================================
  Files        5343     5446     +103     
  Lines      142128   145459    +3331     
  Branches    32411    33227     +816     
==========================================
+ Hits       115899   119224    +3325     
+ Misses      18299    18105     -194     
- Partials     7930     8130     +200     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit f2ef5e4. Configure here.}

[chrisleewilcox]

@copilot resolve the merge conflicts in this pull request

[Copilot]

@copilot resolve the merge conflicts in this pull request

Resolved and pushed in 38f7282. I merged latest main into this branch, resolved all conflicts by keeping the local snap binary mocks and preserving new disableSynchronization settings from main, and combined the .gitattributes updates.

[github-actions]

🔍 Smart E2E Test Selection

• Selected E2E tags: SmokeSnaps
• Selected Performance tags: None (no tests recommended)
• Risk Level: high
• AI Confidence: 97%

click to see 🤖 AI reasoning details

E2E Test Selection:
This PR is entirely focused on the MetaMask Snaps E2E test infrastructure. The key changes are:

1. app/core/Snaps/location/npm.ts (CRITICAL): Modified NpmLocation to route snap tarball downloads through a mock server proxy (/proxy endpoint) when isE2E is true. This is a production code change that affects how snaps are installed during E2E tests - ReactNativeBlobUtil's native fetch bypasses JS-layer fetch/XHR patches, so the redirect must happen at the source URL level.

2. app/util/test/utils.js + shim.js: Added getMockServerPortInApp() and FALLBACK_MOCK_SERVER_PORT to support mock server port configuration via launch arguments.

3. tests/api-mocking/mock-response-data/snaps/snap-binary-mocks.ts: New mock infrastructure that intercepts npm registry tarball downloads and serves locally-stored snap binaries.

4. All tests/smoke/snaps/*.spec.ts files: Updated to use testSpecificMock with the new snap binary mock functions. Also removed disableSynchronization: true from subsequent test cases (only needed for the first snap install step).

5. Snap binary data files: 22 snap binaries stored locally with their headers for offline mocking.

6. scripts/update-snap-binary.ts: New utility to download and update snap binaries.

7. .gitattributes: Marks snap binary .txt files as binary to prevent line ending normalization.

The entire PR is about making SmokeSnaps tests work with local binary mocking instead of live npm registry access. The production code change in npm.ts (the isE2E URL rewriting) is the critical piece that needs validation - it must correctly route snap downloads through the mock server in E2E mode while leaving production behavior unchanged. All 22+ snap test spec files have been updated to use the new mocking infrastructure.

Only SmokeSnaps is needed - no other test areas are affected by these changes.

Performance Test Selection:
These changes are entirely focused on E2E test infrastructure for Snaps - snap binary mocking, mock server routing, and test spec updates. There are no UI rendering changes, no state management changes, no component changes, and no changes to critical user flows that would impact performance metrics. The production code change in npm.ts only affects behavior when isE2E is true (E2E test mode), not in production builds.

View GitHub Actions results

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud