Detox
End-to-end tests driving the real app on a simulator or device.
The rule
This is the whole text, exactly as your agent receives it. Nothing is held back for the paid tier.
What belongs here
Only flows where a regression would be unacceptable — sign-in, purchase, the core task the app exists for. Everything a component test can catch belongs in a component test: each E2E test costs minutes of CI on every push.
Selectors
- Use
by.id()with accessibility ids. Unlike component tests, this is the right default — text changes with locale and copy edits. - Add the id to the component deliberately, as part of the change.
Waiting
await waitFor(element(by.id('pro-badge'))).toBeVisible().withTimeout(10000);Never sleep(). A fixed delay is slow when the app is fast and flaky when it is not, and it hides the real timing bug.
Isolation
device.launchApp({ newInstance: true })inbeforeEach. State leaking between tests produces failures that depend on execution order.- Stub the network and third-party SDKs in the E2E build. A test that charges a real card, sends a real email, or pollutes analytics is not a test.
Do not
- Do not add an E2E test for something a unit test proves.
- Do not assert on exact copy that product will change next week.
- Do not delete a flaky test — quarantine it and fix the non-determinism.
6 formats, one per tool
Each tab is the file that tool actually reads, at the path it actually looks in. Knowing where each one looks is most of the work of supporting it.
---
description: Detox end-to-end testing conventions
globs: ["e2e/**", ".detoxrc.js"]
alwaysApply: false
---
# Detox
## What belongs here
Only flows where a regression would be unacceptable — sign-in, purchase, the
core task the app exists for. Everything a component test can catch belongs in
a component test: each E2E test costs minutes of CI on every push.
## Selectors
- Use `by.id()` with accessibility ids. Unlike component tests, this is the
right default — text changes with locale and copy edits.
- Add the id to the component deliberately, as part of the change.
## Waiting
```js
await waitFor(element(by.id('pro-badge'))).toBeVisible().withTimeout(10000);
```
Never `sleep()`. A fixed delay is slow when the app is fast and flaky when it
is not, and it hides the real timing bug.
## Isolation
- `device.launchApp({ newInstance: true })` in `beforeEach`. State leaking
between tests produces failures that depend on execution order.
- Stub the network and third-party SDKs in the E2E build. A test that charges a
real card, sends a real email, or pollutes analytics is not a test.
## Do not
- Do not add an E2E test for something a unit test proves.
- Do not assert on exact copy that product will change next week.
- Do not delete a flaky test — quarantine it and fix the non-determinism.
Hand-written by the module author, frontmatter and all. It is the source the four derived formats are rendered from, so a correction lands here first.
What else this module writes
The rule is one file of several. Selecting Detox contributes all of this too — merged with every other module you pick, with conflicts resolved rather than duplicated.
Advisory history
Every time this rule turned out to be wrong, and what we did about it.
This rule has been accurate since it was published. That is a fact about the rule, not a promise about the future — which is the whole reason this section exists.
Pro tells you the day a correction lands that affects a repo you actually have.
See what Pro adds →Rules people add alongside this one
The wizard picks the rest of the stack with you, writes all 6 formats, and leaves a manifest so check can tell you when any of it drifts.