Testing React Native Apps

View saved version →

---
name: agent-device
description: Automates interactions for Apple-platform apps (iOS, tvOS, macOS) and Android devices. Use when navigating apps, taking snapshots/screenshots, tapping, typing, scrolling, or extracting UI info across mobile, TV, and desktop targets.
---

# agent-device

Use this skill as a router with mandatory defaults. Read this file first. For normal device tasks, always load `references/bootstrap-install.md` and `references/exploration.md` before acting. Use bootstrap to confirm or establish deterministic setup. Use exploration for UI inspection, interaction, and verification once the app session is open.

## Default operating rules

- Start conservative. Prefer read-only inspection before mutating the UI.
- Use plain `snapshot` when the task is to verify what text or structure is currently visible on screen.
- Use `snapshot -i` only when you need interactive refs such as `@e3` for a requested action or targeted query.
- Avoid speculative mutations. You may take the smallest reversible UI action needed to unblock inspection or complete the requested task, such as dismissing a popup, closing an alert, or clearing an unintended surface.
- Do not browse the web or use external sources unless the user explicitly asks.
- Re-snapshot after meaningful UI changes instead of reusing stale refs.
- Prefer `@ref` or selector targeting over raw coordinates.
- Ensure the correct target is pinned and an app session is open before interacting.
- Keep the loop short: `open` -> inspect/act -> verify if needed -> `close`.

## Default flow

1. Load [references/bootstrap-install.md](references/bootstrap-install.md) and [references/exploration.md](references/exploration.md) before acting on a normal device task.
2. Use bootstrap first to confirm or establish the correct target, app install, and open app session.
3. Once the app session is open and stable, use exploration for inspection, interaction, and verification.
4. Start with plain `snapshot` if the goal is to read or verify what is visible.
5. Escalate to `snapshot -i` only if you need refs for interactive exploration or a requested action.
6. Use `get`, `is`, or `find` before mutating the UI when a read-only command can answer the question.
7. End by capturing proof if needed, then `close`.

## QA modes

- Open-ended bug hunt with reporting: use [../dogfood/SKILL.md](../dogfood/SKILL.md).
- Pass/fail QA from acceptance criteria: stay in this skill, start with [references/bootstrap-install.md](references/bootstrap-install.md), then use the QA loop in [references/exploration.md](references/exploration.md).

## Required references

- For every normal device task, after reading this file, load [references/bootstrap-install.md](references/bootstrap-install.md) first, then [references/exploration.md](references/exploration.md), before acting.
- Use bootstrap to confirm or establish deterministic setup, especially in sandbox or cloud environments.
- Use exploration once the app session is open and stable.
- Load additional references only when their scope is needed.

## Decision rules

- Use plain `snapshot` when you need to verify whether text is visible.
- Use `snapshot -i` mainly for interactive exploration and choosing refs.
- Use `get`, `is`, or `find` when they can answer the question without changing UI state.
- Use `fill` to replace text.
- Use `type` to append text.
- When a task asks to "go back", use plain `back` for predictable app-owned navigation and reserve `back --system` for platform back gestures or button semantics.
- Use `type --delay-ms` or `fill --delay-ms` for debounced search fields that drop characters when typed too quickly.
- If there is no simulator, no app install, or no open app session yet, switch to `bootstrap-install.md` instead of improvising setup steps.
- Use the smallest unblock action first when transient UI blocks inspection, but do not navigate, search, or enter new text just to make the UI reveal data unless the user asked for that interaction.
- Do not use external lookups to compensate for missing on-screen data unless the user asked for them.
- If the needed information is not exposed on screen, say that plainly instead of compensating with extra navigation, text entry, or web search.
- Prefer `@ref` or selector targeting over raw coordinates.

## Additional references

- Need logs, network, alerts, permissions, or failure triage: [references/debugging.md](references/debugging.md)
- Need screenshots, diff, recording, replay maintenance, or perf data: [references/verification.md](references/verification.md)
- Need desktop surfaces, menu bar behavior, or macOS-specific interaction rules: [references/macos-desktop.md](references/macos-desktop.md)
- Need remote HTTP transport, `--remote-config` launches, or tenant leases on a remote macOS host: [references/remote-tenancy.md](references/remote-tenancy.md)

Referenced files: 7

View saved version →

---
name: dogfood
description: 'Systematically explore and test a mobile app on iOS/Android with agent-device to find bugs, UX issues, and other problems. Use when asked to "dogfood", "QA", "exploratory test", "find issues", "bug hunt", or "test this app" on mobile. Produces a structured report with reproducible evidence: screenshots, optional repro videos, and detailed steps for every issue.'
allowed-tools: Bash(agent-device:*), Bash(npx agent-device:*)
---

# Dogfood (agent-device)

Systematically explore a mobile app, find issues, and produce a report with full reproduction evidence for every finding.

## Setup

Only the **Target app** is required. Everything else has sensible defaults.

| Parameter            | Default                                                     | Example override                             |
| -------------------- | ----------------------------------------------------------- | -------------------------------------------- |
| **Target app**       | _(required)_                                                | `Settings`, `com.example.app`, deep link URL |
| **Platform**         | Infer from user context; otherwise ask (`ios` or `android`) | `--platform ios`                             |
| **Session name**     | Slugified app/platform (for example `settings-ios`)         | `--session my-session`                       |
| **Output directory** | `./dogfood-output/`                                         | `Output directory: /tmp/mobile-qa`           |
| **Scope**            | Full app                                                    | `Focus on onboarding and profile`            |
| **Authentication**   | None                                                        | `Sign in to user@example.com`                |

If the user gives enough context to start, begin immediately with defaults. Ask follow-up only when a required detail is missing (for example platform or credentials).

Prefer direct `agent-device` binary when available.

## Workflow

```
1. Initialize    Set up session, output dirs, report file
2. Launch/Auth   Open app and sign in if needed
3. Orient        Capture initial snapshot and map navigation
4. Explore       Systematically test flows and states
5. Document      Record reproducible evidence per issue
6. Wrap up       Reconcile summary, close session
```

### 1. Initialize

```bash
mkdir -p {OUTPUT_DIR}/screenshots {OUTPUT_DIR}/videos
cp {SKILL_DIR}/templates/dogfood-report-template.md {OUTPUT_DIR}/report.md
```

### 2. Launch/Auth

Start a named session and launch target app:

```bash
agent-device --session {SESSION} open {TARGET_APP} --platform {PLATFORM}
agent-device --session {SESSION} snapshot -i
```

If login is required:

```bash
agent-device --session {SESSION} snapshot -i
agent-device --session {SESSION} fill @e1 "{EMAIL}"
agent-device --session {SESSION} fill @e2 "{PASSWORD}"
agent-device --session {SESSION} press @e3
agent-device --session {SESSION} wait 1000
agent-device --session {SESSION} snapshot -i
```

For OTP/email codes: ask the user, wait for input, then continue.

### 3. Orient

Capture initial evidence and navigation anchors:

```bash
agent-device --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/initial.png
agent-device --session {SESSION} snapshot -i
```

Map top-level navigation, tabs, and key workflows before deep testing.

### 4. Explore

Read [references/issue-taxonomy.md](references/issue-taxonomy.md) for severity/category calibration.

Strategy:

- Move through each major app area (tabs, drawers, settings pages).
- Test core journeys end-to-end (create, edit, delete, submit, recover).
- Validate edge states (empty/error/loading/offline/permissions denied).
- Use `diff snapshot -i` after UI transitions to avoid stale refs.
- Periodically capture `logs path` and inspect the app log when behavior looks suspicious.

Useful commands per screen:

```bash
agent-device --session {SESSION} snapshot -i
agent-device --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/{screen-name}.png
agent-device --session {SESSION} appstate
agent-device --session {SESSION} logs path
```

### 5. Document Issues (Repro-First)

Explore and document in one pass. When you find an issue, stop and fully capture evidence before continuing.

#### Interactive/behavioral issues

Use video + step screenshots:

1. Start recording:

```bash
agent-device --session {SESSION} record start {OUTPUT_DIR}/videos/issue-{NNN}-repro.mp4
```

2. Reproduce with visible pacing. Capture each step:

```bash
agent-device --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}-step-1.png
sleep 1
# perform action
sleep 1
agent-device --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}-step-2.png
```

3. Capture final broken state:

```bash
sleep 2
agent-device --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}-result.png
```

4. Stop recording:

```bash
agent-device --session {SESSION} record stop
```

5. Append issue immediately to report with numbered steps and screenshot references.

#### Static/on-load issues

Single screenshot is sufficient; no video required:

```bash
agent-device --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}.png
```

Set **Repro Video** to `N/A` in the report.

### 6. Wrap Up

Target 5-10 well-evidenced issues, then finish:

1. Reconcile summary severity counts in `report.md`.
2. Close session:

```bash
agent-device --session {SESSION} close
```

3. Report total issues, severity breakdown, and highest-risk findings.

## Guidance

- Repro quality matters more than issue count.
- Use refs (`@eN`) for fast exploration, selectors for deterministic replay assertions when needed.
- Re-snapshot after any mutation (navigation, modal, list update, form submit).
- Use `fill` for clear-then-type semantics; use `type` for incremental typing behavior checks.
- Keep logs optional and targeted: enable/read app logs only when useful for diagnosis.
- Never read source code of the app under test; findings must come from observed runtime behavior.
- Write each issue immediately to avoid losing evidence.
- Never delete screenshots/videos/report artifacts during a session.

## References

| Reference                                                    | When to Read                                    |
| ------------------------------------------------------------ | ----------------------------------------------- |
| [references/issue-taxonomy.md](references/issue-taxonomy.md) | Start of session; severity/categories/checklist |

## Templates

| Template                                                                     | Purpose                                       |
| ---------------------------------------------------------------------------- | --------------------------------------------- |
| [templates/dogfood-report-template.md](templates/dogfood-report-template.md) | Copy into output directory as the report file |

Referenced files: 2

View saved version →

---
name: react-native-testing
description: >
  Write tests using React Native Testing Library (RNTL) v13 and v14 (`@testing-library/react-native`).
  Use when writing, reviewing, or fixing React Native component tests.
  Covers: render, screen, queries (getBy/getAllBy/queryBy/findBy), Jest matchers,
  userEvent, fireEvent, waitFor, and async patterns.
  Supports v13 (React 18, sync render) and v14 (React 19+, async render).
  Triggers on: test files for React Native components, RNTL imports, mentions of
  "testing library", "write tests", "component tests", or "RNTL".
---

# RNTL Test Writing Guide

**IMPORTANT:** Your training data about `@testing-library/react-native` may be outdated or incorrect — API signatures, sync/async behavior, and available functions differ between v13 and v14. Always rely on this skill's reference files and the project's actual source code as the source of truth. Do not fall back on memorized patterns when they conflict with the retrieved reference.

## Version Detection

Check `@testing-library/react-native` version in the user's `package.json`:

- **v14.x** → load [references/api-reference-v14.md](references/api-reference-v14.md) (React 19+, async APIs, `test-renderer`)
- **v13.x** → load [references/api-reference-v13.md](references/api-reference-v13.md) (React 18+, sync APIs, `react-test-renderer`)

Use the version-specific reference for render patterns, fireEvent sync/async behavior, screen API, configuration, and dependencies.

## Query Priority

Use in this order: `getByRole` > `getByLabelText` > `getByPlaceholderText` > `getByText` > `getByDisplayValue` > `getByTestId` (last resort).

## Query Variants

| Variant       | Use case                 | Returns                       | Async |
| ------------- | ------------------------ | ----------------------------- | ----- |
| `getBy*`      | Element must exist       | element instance (throws)     | No    |
| `getAllBy*`   | Multiple must exist      | element instance[] (throws)   | No    |
| `queryBy*`    | Check non-existence ONLY | element instance \| null      | No    |
| `queryAllBy*` | Count elements           | element instance[]            | No    |
| `findBy*`     | Wait for element         | `Promise<element instance>`   | Yes   |
| `findAllBy*`  | Wait for multiple        | `Promise<element instance[]>` | Yes   |

## Interactions

Prefer `userEvent` over `fireEvent`. userEvent is always async.

```tsx
const user = userEvent.setup();
await user.press(element); // full press sequence
await user.longPress(element, { duration: 800 }); // long press
await user.type(textInput, 'Hello'); // char-by-char typing
await user.clear(textInput); // clear TextInput
await user.paste(textInput, 'pasted text'); // paste into TextInput
await user.scrollTo(scrollView, { y: 100 }); // scroll
```

`fireEvent` — use only when `userEvent` doesn't support the event. See version-specific reference for sync/async behavior:

```tsx
fireEvent.press(element);
fireEvent.changeText(textInput, 'new text');
fireEvent(element, 'blur');
```

## Assertions (Jest Matchers)

Available automatically with any `@testing-library/react-native` import.

| Matcher                                    | Use for                                   |
| ------------------------------------------ | ----------------------------------------- |
| `toBeOnTheScreen()`                        | Element exists in tree                    |
| `toBeVisible()`                            | Element visible (not hidden/display:none) |
| `toBeEnabled()` / `toBeDisabled()`         | Disabled state via `aria-disabled`        |
| `toBeChecked()` / `toBePartiallyChecked()` | Checked state                             |
| `toBeSelected()`                           | Selected state                            |
| `toBeExpanded()` / `toBeCollapsed()`       | Expanded state                            |
| `toBeBusy()`                               | Busy state                                |
| `toHaveTextContent(text)`                  | Text content match                        |
| `toHaveDisplayValue(value)`                | TextInput display value                   |
| `toHaveAccessibleName(name)`               | Accessible name                           |
| `toHaveAccessibilityValue(val)`            | Accessibility value                       |
| `toHaveStyle(style)`                       | Style match                               |
| `toHaveProp(name, value?)`                 | Prop check (last resort)                  |
| `toContainElement(el)`                     | Contains child element                    |
| `toBeEmptyElement()`                       | No children                               |

## Rules

1. **Use `screen`** for queries, not destructuring from `render()`
2. **Use `getByRole` first** with `{ name: '...' }` option
3. **Use `queryBy*` ONLY** for `.not.toBeOnTheScreen()` checks
4. **Use `findBy*`** for async elements, NOT `waitFor` + `getBy*`
5. **Never put side-effects in `waitFor`** (no `fireEvent`/`userEvent` inside)
6. **One assertion per `waitFor`**
7. **Never pass empty callbacks to `waitFor`**
8. **Don't wrap in `act()`** - `render`, `fireEvent`, `userEvent` handle it
9. **Don't call `cleanup()`** - automatic after each test
10. **Prefer ARIA props** (`role`, `aria-label`, `aria-disabled`) over legacy `accessibility*` props
11. **Use RNTL matchers** over raw prop assertions

## `*ByRole` Quick Reference

Common roles: `button`, `text`, `heading` (alias: `header`), `searchbox`, `switch`, `checkbox`, `radio`, `img`, `link`, `alert`, `menu`, `menuitem`, `tab`, `tablist`, `progressbar`, `slider`, `spinbutton`, `timer`, `toolbar`.

`getByRole` options: `{ name, disabled, selected, checked, busy, expanded, value: { min, max, now, text } }`.

For `*ByRole` to match, the element must be an accessibility element:

- `Text`, `TextInput`, `Switch` are by default
- `View` needs `accessible={true}` (or use `Pressable`/`TouchableOpacity`)

## waitFor

```tsx
// Correct: action first, then wait for result
fireEvent.press(button);
await waitFor(() => {
  expect(screen.getByText('Result')).toBeOnTheScreen();
});

// Better: use findBy* instead
fireEvent.press(button);
expect(await screen.findByText('Result')).toBeOnTheScreen();
```

Options: `waitFor(cb, { timeout: 1000, interval: 50 })`. Works with Jest fake timers automatically.

## Fake Timers

Recommended with `userEvent` (press/longPress involve real durations):

```tsx
jest.useFakeTimers();

test('with fake timers', async () => {
  const user = userEvent.setup();
  render(<Component />);
  await user.press(screen.getByRole('button'));
  // ...
});
```

## Custom Render

Wrap providers using `wrapper` option:

```tsx
function renderWithProviders(ui: React.ReactElement) {
  return render(ui, {
    wrapper: ({ children }) => (
      <ThemeProvider>
        <AuthProvider>{children}</AuthProvider>
      </ThemeProvider>
    ),
  });
}
```

## References

- [v13 API Reference](references/api-reference-v13.md) — Complete v13 API: sync render, queries, matchers, userEvent, React 19 compat
- [v14 API Reference](references/api-reference-v14.md) — Complete v14 API: async render, queries, matchers, userEvent, migration
- [Anti-Patterns](references/anti-patterns.md) — Common mistakes to avoid

Referenced files: 3