Mobile E2E Testing skill for Codex

A mobile E2E suite is healthy when it covers a handful of critical journeys (sign in, purchase, core create/edit flow), starts every test from a known app state, finds elements by stable ids rather than text or coordinates, and runs green in CI on pinned simulator and emulator images. Device E2E is the most expensive layer; keep it small.

Inspect first

1. Read AGENTS.md, package.json, app.json/app.config.*, ios/ and android/ folders, pubspec.yaml. Identify: native, React Native (bare or Expo), Flutter.
2. Look for existing suites: .maestro/, e2e/, .detoxrc.js, *UITests targets, androidTest/.
3. Check what can run here: iOS simulators need macOS with Xcode (xcrun simctl list devices); Android needs an SDK and emulator (emulator -list-avds). In a Codex sandbox, booting simulators, installing CLIs (curl -Ls "https://get.maestro.mobile.dev" | bash) and Gradle/CocoaPods downloads need network and usually approval. If no device can run, write the tests and the CI job, and say they are unverified locally.
4. Find how test users and backend data are provisioned (seed endpoint, staging accounts).

Choose the tool

Situation	Default	Why
Any stack, black-box journeys, quick to write	Maestro	YAML flows, built-in tolerance for delays, works for native, RN, Flutter, web views
React Native, need synchronisation with JS, network and animations	Detox	Gray-box: waits for the app to be idle, fewer explicit waits
Pure native team already in Xcode / Android Studio	XCUITest / Espresso (Compose UI tests)	Best tooling and speed per platform
Real-device farm, WebDriver ecosystem, many languages	Appium	Broad device-cloud support; slower and more setup

Default to Maestro unless the app is React Native and the team wants Detox’s idle synchronisation, or the team is native-only.

Make the app testable first

• Add stable ids to every element a test touches: React Native testID, Flutter Key/Semantics(identifier:), iOS accessibilityIdentifier, Android testTag (Compose, with testTagsAsResourceId = true) or view ids.
• Provide a test entry: launch arguments or a deep link that sets the API base URL, disables animations and onboarding, and signs in a test user.
• Seed backend data per run through an API, not by tapping through setup screens.
• Disable or stub third-party SDK prompts (tracking consent, push permission) in test builds, or grant permissions at launch.

Maestro

# .maestro/checkout.yaml
appId: com.example.shop
tags:
  - smoke
---
- launchApp:
    clearState: true
    arguments:
      e2e: "true"
- runFlow: subflows/sign-in.yaml
- tapOn:
    id: "product-card-0"
- tapOn:
    id: "add-to-cart"
- tapOn:
    id: "cart-tab"
- assertVisible: "1 item"
- tapOn: "Checkout"
- extendedWaitUntil:
    visible: "Order confirmed"
    timeout: 15000
- takeScreenshot: order-confirmed

# .maestro/subflows/sign-in.yaml
appId: com.example.shop
---
- tapOn:
    id: "email-input"
- inputText: ${TEST_EMAIL}
- tapOn:
    id: "password-input"
- inputText: ${TEST_PASSWORD}
- hideKeyboard
- tapOn:
    id: "sign-in-button"
- assertVisible:
    id: "home-screen"

maestro test .maestro/checkout.yaml -e [email protected] -e TEST_PASSWORD="$E2E_PASSWORD"
maestro test .maestro/ --include-tags=smoke --format junit --output build/maestro-junit.xml
maestro studio        # interactive element inspector

Keep test credentials for dedicated test accounts in CI secrets and env vars, never in flow files.

Detox (React Native)

// e2e/checkout.test.js
describe("checkout", () => {
  beforeAll(async () => {
    await device.launchApp({ newInstance: true, launchArgs: { e2e: "true" }, permissions: { notifications: "YES" } });
  });

  beforeEach(async () => {
    await device.reloadReactNative();
  });

  it("buys one item", async () => {
    await element(by.id("product-card-0")).tap();
    await element(by.id("add-to-cart")).tap();
    await element(by.id("cart-tab")).tap();
    await expect(element(by.text("1 item"))).toBeVisible();
    await element(by.text("Checkout")).tap();
    await waitFor(element(by.text("Order confirmed"))).toBeVisible().withTimeout(15000);
  });
});

npx detox build -c ios.sim.release
npx detox test -c ios.sim.release --record-logs failing --take-screenshots failing
npx detox test -c android.emu.release --headless

• .detoxrc.js defines apps (binary path and build command), devices (simulator type, AVD name) and configurations joining them. Pin the simulator model and OS.
• Use release builds in CI so tests do not depend on Metro; debug builds for local iteration.
• Android needs the Detox instrumentation test class and Gradle changes from the Detox setup guide; Expo apps need a prebuild or dev client plus the Detox config plugin.
• If idle sync hangs on a looping animation or long-polling request, scope the fix (device.setURLBlacklist([...]), disable the animation in e2e mode) before reaching for device.disableSynchronization().

Flake control

Cause	Fix
Fixed sleeps	extendedWaitUntil (Maestro) / waitFor().withTimeout() (Detox) on the target element
Text selectors break with copy or locale changes	Use ids; set device locale explicitly
Leftover state from previous test	clearState: true / newInstance: true plus device.clearKeychain() where needed (iOS)
System dialogs (permissions, keyboard, rate-app)	Grant permissions at launch, hideKeyboard, disable prompts in e2e builds
Shared backend test account mutated by parallel runs	One account per shard or per run
Slow cold emulator	Boot and warm up before tests; snapshot AVDs; disable animations (adb shell settings put global animator_duration_scale 0 and the window/transition scales)

CI

• iOS: macOS runners with a pinned Xcode version and simulator; cache the built app between build and test jobs.
• Android: Linux runners with KVM can run the emulator (for example reactivecircus/android-emulator-runner on GitHub Actions); pin API level and system image.
• Hosted options (Maestro Cloud, EAS Workflows, device farms) avoid simulator upkeep; uploading builds to them needs network and account tokens.
• Publish JUnit XML, screenshots and videos as artifacts on failure.
• Run the smoke tag on every PR; the full suite on merge or nightly.

Verification

• Run each new flow three times in a row locally or in CI; all green.
• Break the journey on purpose (rename the button id) and confirm a clear failure with a screenshot.
• Confirm the test leaves no state that changes the next run’s outcome (run the suite twice without reinstalling).

Gotchas

• Coordinates and index-based taps break on a different screen size; never commit them.
• React Native testID on a custom component does nothing unless it is passed down to a native view.
• Expo Go is not a test target; build the actual app (dev client or release build).
• iOS simulator keychain survives app reinstalls; signed-in state can leak between runs.
• Running E2E against production backends creates real orders and emails; use a staging or mocked backend and dedicated test accounts.