> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.tester.army/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.tester.army/_mcp/server.

# Migrate from Appium

> Convert Appium mobile test suites in Java, Python, or JavaScript to TesterArmy AI-powered tests with a single agent prompt. Drop the capabilities, drivers, and locators.

Appium suites carry the same weight as Selenium, plus mobile-specific overhead: desired capabilities, an Appium server, driver setup for iOS and Android, and locator strategies like accessibility IDs, XPath, and `UiSelector`. Most of that exists to point a script at the right element on the screen.

TesterArmy runs your app on cloud simulators and emulators and tests it with an AI agent that sees the screen, so there are no capabilities, drivers, or locators to maintain. The fastest migration path is letting your coding agent (Claude Code, Cursor, Codex) read your Appium suite and convert it with the [TesterArmy CLI](/cli).

## How concepts map

| Appium                                           | TesterArmy                                                                                  |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| A test method driving the Appium `driver`        | A mobile test with natural-language steps                                                   |
| `driver.findElement(...).click()` / `sendKeys()` | `act` steps ("Tap the profile icon", "Enter the search term")                               |
| Framework assertions on element state            | `assert` steps ("The settings screen shows the notifications toggle")                       |
| Login helpers / auth screens                     | `login` step + [project credentials](/auth/credentials)                                     |
| Desired capabilities + Appium server             | Nothing to manage - runs on TesterArmy [cloud simulators/emulators](/mobile/overview)       |
| Accessibility ID / XPath / `UiSelector` locators | Not needed - the agent finds elements visually                                              |
| `WebDriverWait` / implicit waits                 | Not needed - the agent waits like a human                                                   |
| Page Object Model classes                        | Not needed - the intent in their method names becomes step text                             |
| `app` capability pointing at a build             | An uploaded [app build](/mobile/app-uploads) (iOS Simulator `.app`, Android `.apk`/`.apks`) |
| Device farm / emulator management                | Managed cloud devices                                                                       |
| CI job running the suite                         | [GitHub Actions](/mobile/github-actions) or `ta ci`                                         |

## What translates and what doesn't

The page object pattern helps here: method names like `loginScreen.signInWithValidUser()` already describe user intent, which is exactly what a TesterArmy step is.

Things to leave behind:

* **Capabilities, drivers, and the Appium server** - there is no equivalent because none of it is needed.
* **Physical-device-only features** - camera and biometrics (Face ID, Touch ID) are not available on simulators. [Contact us](mailto:support@tester.army) if you need real devices.
* **Device-build artifacts** (`.ipa`, `.aab`, `.xapk`) - TesterArmy needs an iOS Simulator `.app` or an Android `.apk`/`.apks`. See [App Uploads](/mobile/app-uploads).

## Prerequisites

```bash
npm install -g testerarmy
ta auth
```

Get an API key from the [dashboard](https://tester.army/dashboard/profile/api-keys). For non-interactive agent sessions, set `TESTERARMY_API_KEY` instead. You also need a mobile build: an iOS Simulator `.app` or an Android `.apk`/`.apks` - see [App Uploads](/mobile/app-uploads).

## The migration prompt

Paste this into your coding agent in the repository that contains your Appium tests. It works for Java, Python, C#, Ruby, and JavaScript bindings:

```txt
Migrate this repository's Appium mobile test suite to TesterArmy using the
TesterArmy CLI (`ta`). Verify auth first with `ta status --json`, and use
`ta --help` plus subcommand help to discover commands. Prefer --json output.

1. Discover: find all Appium test classes/modules, page object/screen
   classes, and the desired capabilities (platformName, app path, etc.).
   Note whether the suite targets iOS, Android, or both.

2. Create a TesterArmy mobile project (skip if one exists in
   `ta projects list`):
   echo '{"name":"<app name>","url":"","projectType":"mobile"}' | ta projects create --json

3. Build and upload the app artifact. For iOS use an iOS Simulator `.app`
   build; for Android use a release `.apk` or `.apks`. Do not use .ipa,
   .aab, or .xapk. Upload it:
   ta upload-app --app-path <path-to-build> --project <projectId> --json
   Report the uploaded app ID.

4. Save durable context as project memories (category site_structure,
   importance high): key screens, the login flow, and domain knowledge
   encoded in screen objects (e.g. "Settings is reachable from the profile
   tab after signing in").
   echo '{"category":"site_structure","title":"...","content":"...","importance":"high"}' | ta memories create --project <projectId> --json

5. Convert each Appium test method into a TesterArmy mobile test:
   - Express the USER INTENT in plain English. Use screen object method
     names as a guide. Drop all locators (accessibility id, XPath,
     UiSelector), capabilities, waits, and retry logic - the TesterArmy
     agent finds elements visually and waits on its own.
   - tap/click/sendKeys/swipe -> steps with type "act"
   - assertions on element/screen state -> steps with type "assert"
   - login helpers and auth setup -> one step with type "login"
   - Keep tests focused: 3-10 steps. Split long scenario methods into
     separate tests.
   - Skip pure API tests and unit tests of utilities.
   Create each test with platform "mobile":
   echo '{"title":"<test name>","description":"Migrated from <class/file>","platform":"mobile","steps":[{"title":"Tap the profile icon","type":"act"},{"title":"The settings screen is visible","type":"assert"}]}' | ta tests create --project <projectId> --json
   Step types: act, assert, login, screenshot.

6. Never hardcode passwords in test steps. If the suite reads credentials
   from config files or env vars, tell me which credentials to add and I
   will run:
   echo '{"kind":"login","label":"...","username":"...","password":"..."}' | ta projects credentials-create <projectId> --json

7. Tell me each created test ID and remind me to select the uploaded app
   on each test (dashboard App Upload tab), then run them to verify. A
   migrated test can also be run remotely with
   `ta tests run <testId> --remote --wait --json` once the app is selected.

8. Report a summary table: Appium test method -> TesterArmy test ID, the
   uploaded app ID, plus anything you intentionally skipped and why.
```

## After the migration

1. Open each migrated test in the [dashboard](https://tester.army/dashboard), select your uploaded build in the **App Upload** tab, and run it to confirm it passes - see [App Uploads](/mobile/app-uploads).
2. Add [credentials](/auth/credentials) for the logins your auth helpers handled.
3. Wire the suite into CI with [GitHub Actions](/mobile/github-actions) or [Expo EAS](/mobile/expo-eas), replacing your Appium job and device farm.
4. Decommission the Appium server, drivers, and screen object layer once TesterArmy runs are green.

## Next steps

How TesterArmy runs mobile tests on cloud devices.

Build and upload an iOS Simulator or Android build.

Run migrated mobile tests in CI.

Install, authenticate, and run your first test.