> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agi.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# App Testing & QA

> Walk your app's flows on real hardware and get structured reports back.

Because the agent operates a real device through the actual UI, it makes a tireless manual tester: walk the onboarding, poke every screen, and report what it saw - on the exact hardware and OS build your users have.

## The basic pattern

```text theme={null}
Open my app "Acme Notes" on the test phone, go through the onboarding flow
as a new user, and report every screen you saw and anything that looked
broken. Ask me before granting any permissions.
```

Notes on the prompt:

* **Name the app exactly** as it appears on the device. Verify it is
  installed first with [`phone_get_state`](/api-reference/tools/phone-get-state),
  which lists launchable apps with label and package name.
* **"Ask me before granting any permissions"** turns permission dialogs into
  `needs_user_control` handoffs instead of silent grants.
* **Ask for a structured report** - "for each screen: name, what you did,
  what happened, anything unexpected" - so results drop straight into your
  bug tracker.

## Sizing test runs

Long flows are where timeouts and action limits live. Two levers:

* **Raise `per_call_timeout_s`** (default 300 s, max 900) for genuinely long
  walks.
* **Split into several tasks in one session** - one per flow (onboarding,
  settings, checkout). A task that hits `terminal: "iteration_limit"` is the
  signal to break it up further. Splitting also means a crash in one flow
  doesn't cost you the report from the previous flows.

```text theme={null}
Task 1: "Open Acme Notes, complete onboarding as a new user, report each screen."
Task 2: "Now create a note titled 'QA test', add a photo, and verify it saves."
Task 3: "Now open settings, toggle dark mode, and report any visual glitches."
```

## Watching the run

* Set `include_steps: true` on
  [`phone_task_monitor`](/api-reference/tools/phone-task-monitor) to pull the
  task's recorded steps - screenshots and agent thinking - and `since_step`
  to fetch only new ones as the run progresses.
* Execution is visible on the device screen, so you can literally watch the
  test happen.
* Use [`phone_task_message`](/api-reference/tools/phone-task-message) to steer
  mid-run: "skip the newsletter dialog and continue."

## Repeatable runs

For benchmark or regression fleets, [`phone_run_task`](/api-reference/tools/phone-run-task) accepts optional trace tags - `run_id`, `run_type`, and `task_metadata` - to label runs for later analysis. Leave them unset for normal use.

<Note>
  Keep test devices dedicated where possible: one task runs per device at a
  time, and a new MCP task displaces the previous one. Pause a device with
  [`phone_device_pause`](/api-reference/tools/phone-device-pause) when its
  test data must not be disturbed.
</Note>

## Related

<CardGroup cols={2}>
  <Card title="Monitoring" icon="chart-line" href="/guides/best-practices/monitoring">
    Steps, screenshots, and live debugging
  </Card>

  <Card title="Performance" icon="bolt" href="/guides/best-practices/performance">
    Timeouts and task sizing
  </Card>
</CardGroup>