| 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, adding page objects and selectors, or adding MetaMetrics analytics expectations (analyticsExpectations). |
E2E Test Builder ā Skill
One source of truth for adding Detox E2E tests to MetaMask Mobile.
Applies to: Claude Code (.claude/commands/e2e-test.md), Cursor, Copilot, Windsurf, and other AI agents.
Before writing or changing any E2E code: read this skill once, then open the reference(s) indicated by the decision tree for your task.
What This Skill Does
Guides you through adding a new E2E regression or smoke test end-to-end:
- Plans the test (type, location, infrastructure needed)
- Creates or reuses Page Objects and selectors
- Writes the spec using the mandatory framework patterns and the correct tag (see Golden rule 8; check
tests/tags.js and existing specs in the feature folder)
- Runs lint and type checks
- Executes the test locally via Detox
- Iterates until the test passes
Your job is to figure out whether the user needs to write a new spec, fix a failing test, or add page objects/selectors, then follow the corresponding path and open the relevant reference when that path indicates.
Decision tree ā which reference to use:
Task ā What do you need?
āā Write new spec or add test steps
ā ā Open references/writing-tests.md (spec structure, templates, FixtureBuilder patterns)
ā ā If you need POM/selectors: also open references/page-objects.md
ā ā If you need API or feature-flag mocks: also open references/mocking.md
ā ā After writing: run lint/tsc, then open references/running-tests.md to run and debug
ā
āā Create or update Page Objects / selectors
ā ā Open references/page-objects.md (POM structure, Matchers, Gestures, Assertions, selector conventions)
ā ā When writing the spec: open references/writing-tests.md
ā
āā Mock API or feature flags
ā ā 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)
Do not read the full reference files until the decision tree or workflow sends you there.
10 Golden Rules
- Always use
withFixtures ā every spec must be wrapped; no exceptions
- Always use Page Object Model ā no
element(by.id()) in spec files
- Always import from
tests/framework/index.ts ā never from individual files
- Always add
description to every Gestures.* and Assertions.* call
- Never use
TestHelpers.delay() ā use Assertions.* which has auto-retry
- Use
FixtureBuilder for state ā do not set state through UI interactions
- Selectors live in
*.testIds.ts (co-located) or tests/selectors/ (legacy)
- Tag correctly ā Use the tag that matches your feature and test type. Options include
SmokeE2E, SmokeTrade, SmokePredictions, SmokePerps, SmokeConfirmations, RegressionTrade, RegressionWallet, etc. Check tests/tags.js for the full list and descriptions, and existing specs in the same feature folder to see which tag they use.
- Descriptive test names ā no 'should' prefix (e.g.,
'opens market details')
- Fix lint/tsc before running ā never run with known errors
Workflow Overview
Step 0 ā Understand requirement + choose type (smoke/regression)
Step 1 ā Discover / create Page Objects and selectors
Step 2 ā Write the spec (withFixtures + POM + correct tag)
Step 3 ā Lint + TSC (fix all errors)
Step 4 ā Run detox test locally
Step 5 ā Iterate (fix ā lint ā run) until green
Reference files (when to use)
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 | New spec file, spec structure, FixtureBuilder patterns, smoke/regression templates. |
| Page Objects and selectors | references/page-objects.md | Create or update POM classes, selector/testId conventions, Matchers/Gestures/Assertions API. |
| API and feature flag mocking | references/mocking.md | testSpecificMock, setupRemoteFeatureFlagsMock, setupMockRequest, shared mock files. |
| MetaMetrics / analytics expectations | 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 | Build check, detox run commands, lint/tsc, common failures table, retry patterns, iteration loop. |