Mobile MCP: let AI agents drive your iOS and Android apps. MCP server for simulators, emulators and real devices. Works with Claude Code, Codex, Cursor and any MCP client.
TypeScript agentandroidandroid-automationappium-alternativeclaude-codecodexcursoremulatoriosios-automationmcpmcp-servermobilemobile-automationmobile-testingreal-devicesimulatorskills
docs: guide from an agent session to a Mobilewright test in GitHub Actions (#530)
Gil Megidish4f159ff86d32
diff --git a/README.ja.md b/README.ja.mdindex dbffd58..3c8e815 100644--- a/README.ja.md+++ b/README.ja.md@@ -419,7 +419,7 @@ test('sign in', async ({ screen }) => {});```-`npm init mobilewright@latest` から始めましょう。+`npm init mobilewright@latest` から始めましょう。エージェントのセッションから GitHub Actions で動くテストまでの流れは[ステップバイステップガイド](docs/mobilewright-ci.md)(英語)をご覧ください。### ☁️ クラウドデバイスでスケールするdiff --git a/README.md b/README.mdindex 17055fe..eb8b051 100644--- a/README.md+++ b/README.md@@ -430,7 +430,7 @@ test('sign in', async ({ screen }) => {});```-Start with `npm init mobilewright@latest`.+Start with `npm init mobilewright@latest`. The [step-by-step guide](docs/mobilewright-ci.md) goes from an agent session to a test running in GitHub Actions.### ☁️ Scale up, use a cloud devicediff --git a/README.zh-CN.md b/README.zh-CN.mdindex 5edb796..41a20d6 100644--- a/README.zh-CN.md+++ b/README.zh-CN.md@@ -419,7 +419,7 @@ test('sign in', async ({ screen }) => {});```-从 `npm init mobilewright@latest` 开始。+从 `npm init mobilewright@latest` 开始。[分步指南](docs/mobilewright-ci.md)(英文)介绍了如何从一次智能体会话得到在 GitHub Actions 中运行的测试。### ☁️ 扩展规模,使用云设备diff --git a/docs/mobilewright-ci.md b/docs/mobilewright-ci.mdnew file mode 100644index 0000000..bca7b0a--- /dev/null+++ b/docs/mobilewright-ci.md@@ -0,0 +1,211 @@+# From Mobile MCP to CI++Mobile MCP lets a coding agent such as Claude Code or Cursor drive an iOS simulator, an Android emulator or a real device. It is a good way to explore an app and check a flow by hand. An agent session is not a test, though: it costs tokens on every run and the agent can take a different path each time.++This guide turns one agent session into a [Mobilewright](https://mobilewright.dev/?utm_source=mobile-mcp&utm_medium=docs&utm_campaign=agent-to-ci) test that runs the same way every time, then runs that test in GitHub Actions on every pull request.++The examples use [Milliways](https://github.com/mobile-next/Milliways), our sample app. Replace the bundle ID and the steps with your own app's.++## 1. Install Mobile MCP++Run the installer:++```bash+npx @mobilenext/mobile-mcp@latest install+```++It finds the MCP clients on your machine (Claude Code, Cursor, VS Code, Codex, Windsurf and more), lets you pick which ones to set up, and adds Mobile MCP to each of them. Add `--yes` to set up every client it finds without asking.++To set up a client by hand instead, see [Installation and configuration](../README.md#installation-and-configuration) in the README.++Then boot a simulator, start an emulator, or plug in a device.++## 2. Let the agent explore the flow++Ask the agent to do the flow you want to cover, in plain words. You don't need to install the app first; the agent can do that too:++```text+Download and install the app from https://github.com/mobile-next/Milliways/releases/latest+on the iPhone simulator. Then open it, start a new order, add two Green Salads,+open the order and check that the total is ₭44.00.+```++The agent picks the right build for the device (the simulator `.zip`, the `.apk` for Android, or the `.ipa` for a real iPhone), downloads it, and installs it with Mobile MCP.++The agent reads the screen through Mobile MCP's element list, taps by element, and reports what it saw at each step:++++This is the time to fix the flow: if the agent gets stuck or the app misbehaves, you see it here, before any test code exists.++## 3. Ask for a Mobilewright test++In the same session, ask the agent to write down what it just did:++```text+Now write what you just did as a Mobilewright test in tests/order.spec.ts.+Use getByRole and getByText locators, not coordinates, and end with an+assertion on the order screen.+```++If the project does not use Mobilewright yet, the agent (or you) can add it first:++```bash+npm init mobilewright@latest+```++The agent already knows the labels and roles of every element it tapped, so the locators come straight from the session. For the flow above it writes:++`tests/order.spec.ts`:++```ts+import { test, expect } from '@mobilewright/test';++test('adds two green salads to the order', async ({ screen }) => {+ await screen.getByText('New Order').tap();+ await screen.getByText('Green Salad').tap();+ await screen.getByRole('button', { name: '+' }).tap();+ await screen.getByRole('button', { name: 'Add to Order' }).tap();++ await screen.getByRole('button', { name: /View Order/ }).tap();+ await expect(screen.getByText('Your Order')).toBeVisible();+ await expect(screen.getByText('2 × ₭22.00')).toBeVisible();+});+```++`mobilewright.config.ts`:++```ts+import { defineConfig } from 'mobilewright';++export default defineConfig({+ platform: 'ios',+ bundleId: 'com.mobilenext.Milliways',+ deviceName: /iPhone/,+});+```++Mobilewright waits for each element before acting on it, so there are no sleeps in the test. See [Locators](https://mobilewright.dev/docs/guides/locators) and [Assertions](https://mobilewright.dev/docs/guides/assertions) if you want to tighten what the agent wrote.++## 4. Run it locally++```bash+npx mobilewright test --reporter list,html+```++```+Running 1 test using 1 worker++ ✓ 1 tests/order.spec.ts:3:5 › adds two green salads to the order (8.7s)++ 1 passed (14.1s)+```++Open the report with `npx mobilewright show-report`:++++From now on this flow runs in seconds, without an agent and without tokens. Keep using Mobile MCP to explore new flows and to debug a failing test, and ask the agent to update the test when the app changes.++## 5. Run it in GitHub Actions++In CI, run the tests on remote devices instead of simulators. The runner doesn't need a Mac or a simulator: Mobilewright allocates a device on [Mobile Next Cloud](https://mobilewright.dev/docs/cloud-providers/mobile-next-cloud), installs your app on it, runs the tests, and uploads the report to your dashboard.++Switch the driver when an API key is present, so the same config keeps working locally:++`mobilewright.config.ts`:++```ts+import { defineConfig, type MobilewrightConfig } from 'mobilewright';+import { MobileNextDriver } from '@mobilewright/driver-mobilenext';++const config: MobilewrightConfig = {+ platform: 'ios',+ bundleId: 'com.mobilenext.Milliways',+ deviceName: /iPhone/,+};++if (process.env.MOBILENEXT_API_KEY) {+ config.driver = new MobileNextDriver();+ config.deviceType = 'real';+ config.installApps = ['./build/app.ipa'];+}++export default defineConfig(config);+```++Create an API key at [mobilenext.ai](https://mobilenext.ai/cloud?utm_source=mobile-mcp&utm_medium=docs&utm_campaign=agent-to-ci), add it to your repository as the `MOBILENEXT_API_KEY` secret, and create `.github/workflows/mobilewright.yml`:++`.github/workflows/mobilewright.yml`:++```yaml+name: Mobilewright Tests+on:+ push:+ branches: [main]+ pull_request:+ branches: [main]++permissions:+ contents: read++jobs:+ build:+ runs-on: macos-latest+ steps:+ - uses: actions/checkout@v4+ - run: ./scripts/build-app.sh # produces build/app.ipa+ - uses: actions/upload-artifact@v4+ with:+ name: app+ path: build/++ test:+ needs: build+ runs-on: ubuntu-latest+ timeout-minutes: 30+ env:+ MOBILENEXT_API_KEY: ${{ secrets.MOBILENEXT_API_KEY }}+ steps:+ - uses: actions/checkout@v4+ - uses: actions/download-artifact@v4+ with:+ name: app+ path: build/+ - uses: actions/setup-node@v4+ with:+ node-version: 24+ - run: npm ci+ - run: npx mobilewright test --reporter list,html++ - uses: actions/upload-artifact@v4+ if: ${{ !cancelled() }}+ with:+ name: mobilewright-report+ path: mobilewright-report/+ retention-days: 30+```++Key points:++- **Build once, test anywhere.** The `build` job compiles the app on a Mac. The `test` job only needs Node.js and the app file, so it runs on `ubuntu-latest`, which costs less and starts faster.+- **Android** works the same way: point `installApps` at your `.apk` and set `platform: 'android'`, or add a [project](https://mobilewright.dev/docs/test/projects) per platform.+- **More devices.** Raise `--workers` to run tests on several cloud devices at once.+- **`if: ${{ !cancelled() }}`** uploads the report when tests fail, which is when you need it.++Mobile Next Cloud is one of several [cloud providers](https://mobilewright.dev/docs/cloud-providers) Mobilewright supports; the workflow is the same for the others, with their driver and credentials. [Best Practices](https://mobilewright.dev/docs/guides/best-practices) covers splitting the build from the test job, and when to use workers or sharding.++## Tips for prompts++- **Name the end state.** "Check that the total is ₭44.00" gives the test a real assertion. "Add a salad" gives it nothing to check.+- **Ask for role and text locators.** The agent sees coordinates too. Coordinates break on the next screen size; `getByRole` and `getByText` don't.+- **One flow per test.** Ask for a separate test per flow instead of one long script, so a failure points at one thing.+- **Run it before you commit it.** Ask the agent to run `npx mobilewright test` and fix the test until it passes.++## See also++- [Best Practices](https://mobilewright.dev/docs/guides/best-practices) for running Mobilewright in CI+- [Cloud providers](https://mobilewright.dev/docs/cloud-providers)+- [Setting up CI](https://mobilewright.dev/docs/getting-started/ci), for local simulators and emulators+- [Agent CLI](https://mobilewright.dev/docs/agent-cli/introduction), a shell alternative to Mobile MCP for agents+- [Codegen](https://mobilewright.dev/docs/guides/codegen), to record a test by clicking instead of promptingdiff --git a/docs/screenshots/mobile-mcp-agent-session.png b/docs/screenshots/mobile-mcp-agent-session.pngnew file mode 100644index 0000000..9d3afcfBinary files /dev/null and b/docs/screenshots/mobile-mcp-agent-session.png differdiff --git a/docs/screenshots/mobile-mcp-html-report.png b/docs/screenshots/mobile-mcp-html-report.pngnew file mode 100644index 0000000..5bd61d8Binary files /dev/null and b/docs/screenshots/mobile-mcp-html-report.png differ