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

# Run your own Appium tests

> Point your existing Appium suite at the Minitap hub and read every test, recording and log in Script runs.

Your team's Appium tests can run on Minitap devices without changing the tests themselves. You point the Appium driver at the Minitap hub instead of your local server, add a few capabilities, and each test runs on its own device, recorded from start to end. The results show up in **Script runs**, next to Mini's runs.

> [!NOTE]
>
> **Beta.** Script runs are being tried with a few teams first. Android apps with UiAutomator2, and iOS apps with XCUITest on iPhone simulators. Ask the Minitap team to turn them on for your workspace.

## Set up

Open **Settings → Test frameworks** and tick **Appium**. The setup walks you through the same three things:

1. **An API key.** Your tests sign in with a workspace [API key](https://www.minitap.ai/docs/minitest/workspace/api-keys.md). Keep it in your CI's secret store as `MINITAP_API_KEY`.
2. **The app ID.** The app the results belong to. Copy it from the setup; it isn't a secret.
3. **The hub URL.** Shown in the setup. Your tests open their session there.

The app under test is a build you [uploaded](https://www.minitap.ai/docs/minitest/setup/upload-a-build.md), written `minitap://build/<build id>`, or the `https://` URL of an APK. For an iOS app, see [iOS](#ios).

```python theme={"theme":{"light":"github-light","dark":"vesper"}}
import os

from appium import webdriver
from appium.options.android import UiAutomator2Options

options = UiAutomator2Options()
options.set_capability("minitap:apiKey", os.environ["MINITAP_API_KEY"])
options.set_capability("minitap:appId", os.environ["MINITAP_APP_ID"])
options.set_capability("minitap:runName", os.environ.get("MINITAP_RUN_NAME"))
options.set_capability("appium:app", "minitap://build/9c1d…")

driver = webdriver.Remote(os.environ["MINITAP_HUB_URL"], options=options)
try:
    ...  # your test, unchanged
    driver.execute_script("minitap:setStatus", {"status": "passed", "name": "Login"})
except Exception as error:
    driver.execute_script(
        "minitap:setStatus", {"status": "failed", "name": "Login", "reason": str(error)}
    )
    raise
finally:
    driver.quit()
```

The setup also has the Java and WebdriverIO versions, and the GitHub Actions and GitLab CI jobs.

### WebdriverIO

Point the WebdriverIO runner at the hub and report each test in `afterTest`. Don't add the Appium service: Minitap runs Appium for you.

```ts theme={"theme":{"light":"github-light","dark":"vesper"}}
// wdio.conf.ts
const hub = new URL(process.env.MINITAP_HUB_URL!);
const minitap = {
  'minitap:apiKey': process.env.MINITAP_API_KEY,
  'minitap:appId': process.env.MINITAP_APP_ID,
  'minitap:runName': process.env.MINITAP_RUN_NAME,
};

export const config: WebdriverIO.Config = {
  protocol: 'https',
  hostname: hub.hostname,
  port: 443,
  path: hub.pathname,
  specs: ['./test/specs/**/*.ts'],
  capabilities: [
    {
      platformName: 'Android',
      'appium:automationName': 'UiAutomator2',
      'appium:app': 'minitap://build/<android build id>',
      ...minitap,
    },
    {
      platformName: 'iOS',
      'appium:automationName': 'XCUITest',
      'appium:deviceName': 'iPhone 16 Pro',
      'appium:app': 'minitap://build/<ios build id>',
      ...minitap,
    },
  ],
  framework: 'mocha',
  reporters: ['spec', ['junit', { outputDir: './junit' }]],
  afterTest: async (test, _context, { passed, error }) => {
    await browser.execute('minitap:setStatus', {
      status: passed ? 'passed' : 'failed',
      name: test.title,
      reason: error?.message,
    });
  },
};
```

Each spec file runs as one session per device, and every session of the job forms one run. WebdriverIO's JUnit reporter keeps working as before.

> [!TIP]
>
> React Native apps often draw a label and its container with the same text. If WebdriverIO stops on a strict selector error, set `strictSelectors: false` or narrow the selector.

### Robot Framework

With AppiumLibrary, open the app on the hub in the test setup and report in the teardown:

```robotframework theme={"theme":{"light":"github-light","dark":"vesper"}}
*** Settings ***
Library           AppiumLibrary
Test Setup        Open The App
Test Teardown     Report And Close

*** Keywords ***
Open The App
    Open Application    %{MINITAP_HUB_URL}
    ...    platformName=Android
    ...    appium:automationName=UiAutomator2
    ...    appium:app=minitap://build/<android build id>
    ...    minitap:apiKey=%{MINITAP_API_KEY}
    ...    minitap:appId=%{MINITAP_APP_ID}
    ...    minitap:runName=%{MINITAP_RUN_NAME}
    ...    minitap:testName=${TEST NAME}

Report And Close
    ${status}=    Set Variable If    '${TEST STATUS}' == 'PASS'    passed    failed
    Execute Script    minitap:setStatus    status=${status}    name=${TEST NAME}    reason=${TEST MESSAGE}
    Close Application
```

Pass `minitap:setStatus`'s fields as named arguments: `Execute Script` sends them as the one object the command expects. Robot's `output.xml`, `log.html` and `report.html` are written as usual. For iOS, use `platformName=iOS`, `appium:automationName=XCUITest` and an iOS build; in AppiumLibrary, iOS predicate locators are written `predicate=label == "Sign In"`.

## Capabilities

| Capability | Required | What it does |
| - | - | - |
| `platformName` | yes | `Android` or `iOS` |
| `minitap:apiKey` | yes | Your workspace API key |
| `minitap:appId` | yes | The app the results belong to |
| `appium:app` | no | `minitap://build/<build id>`, or an `https://` URL of an APK (Android) or a simulator `.app.zip` (iOS) |
| `minitap:runName` | no | Groups the tests of one CI job into one run (see [How tests form a run](#how-tests-form-a-run)) |
| `minitap:testName` | no | The test's name when `minitap:setStatus` doesn't give one |
| `minitap:commitSha` | no | The commit under test |
| `appium:deviceName` | no | The device model (see [Choose the device](#choose-the-device)) |
| `appium:platformVersion` | no | The Android or iOS version |
| `appium:newCommandTimeout` | no | Seconds without a command before the session ends, and the longest a session waits for a device. 60 by default, 900 at most. A new session's first command must still come within 30 seconds |

Your other `appium:*` capabilities go to Appium as they are. `appium:automationName` must be `UiAutomator2` on Android and `XCUITest` on iOS. Minitap keeps the capabilities you sent with each test, except the API key and anything named like a key, token, secret, password or credential.

## Report each test

Minitap sees WebDriver commands, not tests, so tell it how the test went before you quit the driver:

```python theme={"theme":{"light":"github-light","dark":"vesper"}}
driver.execute_script(
    "minitap:setStatus", {"status": "failed", "name": "Login", "reason": "no OTP field"}
)
```

`status` is `passed` or `failed`, `reason` is what you'd read in the test report. A session that never calls it shows **No status reported**. The test's status is yours: Minitap never changes it. When something goes wrong on Minitap's side (no device, the app didn't install, the session timed out), the test also shows a **Minitap issue** with the reason, apart from its status.

## How tests form a run

Each WebDriver session is one test. Tests that share a `minitap:runName` form one run in **Script runs**, so set it from your CI's run id, for example `${{ github.run_id }}` in GitHub Actions or `$CI_PIPELINE_ID` in GitLab. Without a run name, tests on the same `minitap:commitSha` form one run, and a test with neither stands alone.

## Choose the device

Script runs use Android emulators and iPhone simulators. Without device capabilities, an Android test runs on an Android 15 phone emulator and an iOS test on an iOS 27 iPhone simulator. Pick another one with:

| Capability | Android | iOS |
| - | - | - |
| `appium:deviceName` | `Android phone` (default) or `Android tablet` | Any iPhone name, like `iPhone 16 Pro` |
| `appium:platformVersion` | `14` or `15` (default) | `26` or `27` (default) |

Names that local setups often carry, like `Android Emulator`, `emulator-5554` or `iPhone Simulator`, don't pick a model, so you can keep them. A device that doesn't exist refuses the session with a message naming what you asked for.

A run never mixes devices of a platform. Its first test to get a device sets it, and every later test of the run gets the same one, waiting for it when it's busy rather than running somewhere else. A later test asking for another device is refused: give it its own `minitap:runName` to run it apart. Android and iOS tests can share a run, each platform on its own device.

## iOS

iOS tests run unchanged on an iPhone simulator, with XCUITest.

```python theme={"theme":{"light":"github-light","dark":"vesper"}}
import os

from appium import webdriver
from appium.options.ios import XCUITestOptions

options = XCUITestOptions()
options.set_capability("minitap:apiKey", os.environ["MINITAP_API_KEY"])
options.set_capability("minitap:appId", os.environ["MINITAP_APP_ID"])
options.set_capability("minitap:runName", os.environ.get("MINITAP_RUN_NAME"))
options.set_capability("appium:app", "minitap://build/3fb3…")
options.set_capability("appium:deviceName", "iPhone")

driver = webdriver.Remote(os.environ["MINITAP_HUB_URL"], options=options)
```

The rest of the test, `minitap:setStatus` included, is the same as on Android. A few things differ:

* **The build is a simulator build**: an `.app` built for the iOS simulator, zipped as `.app.zip`. A device `.ipa` can't run on a simulator, and a test given one, or an Android build, is refused with a message naming the build.
* **Minitap installs the app** before the test starts, and opens it. Installing another app during the test (`mobile: installApp`) is refused.
* **Minitap records the screen**, like on Android. Appium's own screen recording (`mobile: startRecordingScreen`) isn't available.
* Minitap sets how Appium reaches the simulator: the capabilities you'd use for a local WebDriverAgent (`appium:webDriverAgentUrl`, `appium:usePreinstalledWDA`, `appium:udid`…) are ignored.

> [!NOTE]
>
> **Coming soon.** iPads, physical iPhones, app permissions (`mobile: setPermission`) and the device's system log aren't available on iOS yet. A test asking for an iPad is refused.

## How many tests run at once

Your workspace runs as many tests at once as its plan allows. Start more than that, say 30 tests on a plan of 10 devices, and the first 10 run while the others wait their turn, first come first served. Each one starts as soon as a device frees up.

A waiting test waits at most its `appium:newCommandTimeout`. Past it, the session is refused with a message naming the device, how many tests asked for one and how many your workspace has, and the test shows a **Minitap issue**. For a long suite, raise `appium:newCommandTimeout` (up to 900 seconds), and make sure your Appium client's own HTTP timeout is at least as long.

Once a test gets its device, it has 30 seconds to send its first command, whatever its `appium:newCommandTimeout`. A session that sends none is taken for a client that gave up waiting: it ends and its device goes to the next test. Appium clients send their first command right away, so this only matters if your test pauses between creating the driver and using it.

## Read the results

Open **Results → Script runs**. Each run lists its tests with their status, failure reason and any Minitap issue. Open a test to watch its recording and read its Appium log, and download the run as a JUnit report.

From the terminal, the [CLI](https://www.minitap.ai/docs/minitest/reference/cli-commands.md) reads the same thing:

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
minitest script-runs list --status failed
minitest script-runs get <run id>
minitest script-runs recording <run id> --test "Login"
minitest script-runs junit <run id>
```

## How long we keep them

| What | Kept |
| - | - |
| Runs, tests and recordings | 90 days |
| Appium logs | 30 days |

After 30 days, a test's Appium log reads as deleted.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.