> For the complete documentation index, see [llms.txt](https://docs.mozark.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mozark.ai/mcp/mozark-mcp-docs/guides/run-tests-on-a-real-device.md).

# Run tests on a real device

Execute test cases on Mozark cloud devices with Optics.

**Optics** executes a test case step-by-step on a real Android or iOS device in Mozark's cloud, verifies every step from a screenshot, and hands you a reusable automation script at the end.

## What to expect

The assistant follows a strict, transparent procedure. You'll be asked a few setup questions—they're deliberate, because some choices can't be changed once a session starts.

{% stepper %}
{% step %}

## Choose the test case

> *"Run TC-12 on a real device."*

Or paste steps inline:

> *"On a device: open the app, tap Sign in, enter a wrong password, confirm the error toast."*
> {% endstep %}

{% step %}

## Pick a device

The assistant lists **free devices** (`appium_list_free_devices`) and asks you to choose, unless you already named a model.
{% endstep %}

{% step %}

## Choose capture options

Capture can't be enabled retroactively, so you're asked up front. Pick any combination:

| Option               | What you get                      |
| -------------------- | --------------------------------- |
| Screen recording     | Video of the whole session        |
| Screenshots          | Per-step images                   |
| Device logs          | logcat / syslog                   |
| Network logs         | HAR file                          |
| App profiling        | CPU / memory / battery profile    |
| Live log streaming   | Logs as they happen               |
| Live video streaming | Watch the run live                |
| Clean session apps   | Uninstall session apps afterwards |
| {% endstep %}        |                                   |

{% step %}

## Provide the app package

The assistant will ask for the exact **Android package** or **iOS bundle ID**—for example, `com.yourcompany.app`. It never guesses one.

If you don't know it, say so—the assistant can open the app from the drawer and read the real package from the device.
{% endstep %}

{% step %}

## Choose the locator ladder

Each step needs to find something on screen. Three strategies are always available; you choose the **order** they're tried in. The recommended default:

1. **Text (OCR)** — matches visible words. Works on Android *and* iOS, and on Flutter / React Native apps. Produces cross-platform scripts. *Recommended first.*
2. **XPath** — queries the view hierarchy. Precise, but Android-only and brittle to layout changes.
3. **AI fallback** — reads the position from the screenshot and taps by percentage. Works on anything, but records no intent, so it isn't exportable.

The assistant probes the screen first and tells you if a rung won't work for your app—for example, no view hierarchy means XPath is dropped.
{% endstep %}

{% step %}

## Watch it run

For every step you'll see:

* **Action** — the keyword and locator used
* **Result** — whether the keyword ran *and* whether it did what the step intended
* **Observation** — what's on screen now
* **Expected result** — verified or not, with reasoning
* **Next** — the next step or fallback

Each verified step is confirmed with an `assert_presence` check. If a step fails, the assistant works down your locator ladder before reporting a failure—it never skips a step silently.
{% endstep %}

{% step %}

## Results and export

At the end you get a pass/fail summary per step and an **Optics YAML script** built from text locators—ready to replay on Android or iOS, or to add to CI. The device is released automatically.
{% endstep %}
{% endstepper %}

## Recording into a test run

If you say *"Run TR-8 on a device"* rather than naming a test case, the assistant also writes results back to TCM as it goes: starts the test case in the run, marks each step Passed/Failed, attaches a screenshot as evidence on failures, and finishes the run with a real status.

{% hint style="warning" %}
**Blocked runs.** If the app can't reach the first screen—an OTP gate, paywall, or missing account—the assistant stops immediately, shows you the screenshot, and asks what it needs rather than burning attempts.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.mozark.ai/mcp/mozark-mcp-docs/guides/run-tests-on-a-real-device.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.