test: adapt FixureHelper to run with appium and local runs

[christopherferreira9]

Description

This PR adapts the FixtureHelper (withFixtures) to work properly with appium and playwright.

Main changes:

• launchApp utility inside withFixtures now sends launchArgs so that FixtureServer and other resources can properly be used
• MockServer is completely tool agnostic
• App interaction is now segregated in specific handlers for adb and xcrun with an abstract CommandHandler
  • These are also exposed via test callback so that individual tests can interact with the device to clear app data, uninstall, install and so on
• Android amulator name is now automatically derived from its friendly name. Eg: PIXEL_XL_API_34 is not translated in the proper serial as emulator-5554
• FixtureServer now waits for an initial request to avoid early test start
• Tests now only start once Metro has finished loading. This prevents early fast fails where metro would take longer to load than the test would start.
  1. FixtureServer now counts completed GET /state.json requests.
  2. Before launching the app in Appium mode, withFixtures creates a waiter with fixtureServer.waitForNextStateRequest().
  3. Then PlaywrightUtilities.launchApp(...) launches the app with the fixture/mock/command server launch args.
  4. The app loads JS from Metro, runs the E2E bootstrap, and requests /state.json.
  5. When that request finishes, FixtureServer resolves the waiter.
  6. Only then does withFixtures continue to dismiss dev screens and run the actual test body.
• Appium server log level has been bumped to INFO to avoid clutter
• A boilerplate test using withFixtures has been added to be used as a guide for debugging
• Implemented different conditions to run tests locally on emulator:
  • buildPath is not provided - Framework checks for installed app, deletes app data and launches the app. Throws if the app is not installed.
  • buildPath is provided - App is uninstalled and installed back. Throws if the artifact does not exist.

Introduction of test shims:

This PR also adds a Playwright-only Node shim so FixtureBuilder can load in Playwright without changing app runtime behavior.
We need this shim mechanism because some app dependencies patch CommonJS packages to call native modules such as @metamask/native-utils. Those calls are valid in the mobile app, but Playwright loads the same dependency graph in Node where React Native/Nitro native modules are unavailable.

Changelog

CHANGELOG entry:

Related issues

Fixes:

• https://consensyssoftware.atlassian.net/browse/MMQA-1784
• https://consensyssoftware.atlassian.net/browse/MMQA-1742

Manual testing steps

N/A

Screenshots/Recordings

Before

N/A

After

N/A

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.

Performance checks (if applicable)

• I've tested on Android
  • Ideally on a mid-range device; emulator is acceptable
• I've tested with a power user scenario
  • 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
  • See trace() for usage and addToken for an example

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.

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

[github-actions]

🔍 Smart E2E Test Selection

• Selected E2E tags: None (no tests recommended)
• Selected Performance tags: None (no tests recommended)
• Risk Level: low
• AI Confidence: 88%

click to see 🤖 AI reasoning details

E2E Test Selection:
All 25 changed files are exclusively within the tests/ directory — specifically the Playwright/Appium test framework infrastructure. No app source code (app/) was modified.

Key findings:

1. New DeviceCommandHandler system (AndroidDeviceCommandHandler, IOSDeviceCommandHandler, DeviceCommandHandler) — new classes for adb/simctl device management in the Playwright/Appium framework only.
2. FixtureHelper.ts — Extended withFixtures to support both Detox and Appium/Playwright frameworks. All Appium-specific paths are guarded by FrameworkDetector.isDetox() / FrameworkDetector.isAppium() checks, so existing Detox behavior is preserved.
3. FixtureServer.ts — Added waitForNextStateRequest() as an app boot signal for Appium. This is additive and doesn't change existing Detox behavior.
4. PlaywrightUtilities.ts — Refactored launchApp to support platform-specific launch with intent extras/process arguments. This is Playwright/Appium only.
5. MockServerE2E.ts — Minor safe refactor replacing device.getPlatform() === 'android' with await PlatformDetector.isAndroid(), which is the standard pattern used throughout the codebase.
6. nodeNativeUtilsShim.cjs — New Node.js shim for @metamask/native-utils in Playwright's Node process only.
7. playwright.config.ts — Updated test matching for Playwright performance tests (not Detox).
8. performance/fixtures/test.spec.ts — New demo test using withFixtures in Playwright framework.
9. Unit tests — New Jest unit tests for the new framework classes.
10. TestConstants.js — Added e2e scenario type password, additive change.

Since all changes are in the Playwright/Appium test infrastructure (separate from Detox), and no app source code was modified, no Detox E2E test tags are required. The changes do not affect any user-facing functionality.

Performance Test Selection:
The performance test changes are in the Playwright/Appium framework infrastructure (tests/performance/fixtures/test.spec.ts, tests/playwright.config.ts). These are framework-level changes to how performance tests are set up and run, not changes to app code that would affect actual performance metrics. The playwright.config.ts now points to a demo fixture test rather than the full performance suite. No app source code was modified, so no performance regression is expected. Performance test tags (@PerformanceLaunch, @PerformanceLogin, etc.) are for measuring app performance, not for validating test infrastructure changes.

View GitHub Actions results

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud