> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Get started: iOS · Midscene Test · Model API Key {#get-started}

These are the setup steps for Midscene on **iOS** with **Midscene Test** and a **Model API Key**. To choose another combination, see [all setup paths](/get-started.md#all-setup-paths).

## Install Node.js
Install Node.js `^20.19.0 || ^22.12.0 || >=24.0.0`, then check that `node -v` works in your terminal.
The commands below use pnpm. If it is not installed yet, run `npm install -g pnpm`.

## Connect the iOS device through WDA
Midscene communicates with iOS physical devices and simulators through a running WebDriverAgent (WDA) service. If WDA is already running and reachable from your computer, skip directly to [Verify the WDA service status](#verify-wda-status).

### Build and start WebDriverAgent

Before you begin, prepare the following iOS development environment:

- macOS (required for iOS development and device debugging)
- Xcode and Xcode Command Line Tools
- An iOS Simulator or physical iOS device

:::info Version requirement

WebDriverAgent version must be **>= 7.0.0**.

:::

Follow the official Appium documentation to build and start WebDriverAgent (WDA):

- **Simulator setup**: [Run Prebuilt WDA](https://appium.github.io/appium-xcuitest-driver/latest/guides/run-prebuilt-wda/)
- **Physical device setup**: [Real Device Configuration](https://appium.github.io/appium-xcuitest-driver/latest/getting-started/device-setup/)

### Configure a physical device and forward the port

iOS Simulators expose WDA directly on `localhost` and do not require port forwarding—if you are using a simulator or a remote WDA service, skip to [Verify the WDA service status](#verify-wda-status).

When using a physical iOS device:

1. Connect the device to your Mac via USB and tap **Trust This Computer** when prompted on the device.
2. Enable **Developer Mode** (**Settings > Privacy & Security > Developer Mode**) and **UI Automation** (**Settings > Developer > Enable UI Automation**) on the device.
3. After signing and starting WDA on the device, use `iproxy` (installable via `brew install libimobiledevice`) to forward the WDA port (`8100` by default) from the device to your Mac:

```bash
iproxy 8100 8100 YOUR_DEVICE_ID
```

Replace `YOUR_DEVICE_ID` with your device's UDID, and keep both WDA and `iproxy` running. When connecting multiple devices or using custom ports, forward each device to a distinct local port and use that port in Playground or your project configuration.

### Verify the WDA service status {#verify-wda-status}

Open the WDA `/status` endpoint in your browser or terminal from the computer running Midscene:

- **Default local URL**: `http://localhost:8100/status` (if using a custom port, remote host, or gateway, use the actual service address)
- **Expected JSON response**:

```json
{
  "value": {
    "build": {
      "version": "10.1.1",
      "time": "Sep 24 2025 18:56:41",
      "productBundleIdentifier": "com.facebook.WebDriverAgentRunner"
    },
    "os": {
      "testmanagerdVersion": 65535,
      "name": "iOS",
      "sdkVersion": "26.0",
      "version": "26.0"
    },
    "device": "iphone",
    "ios": {
      "ip": "10.91.115.63"
    },
    "message": "WebDriverAgent is ready to accept commands",
    "state": "success",
    "ready": true
  },
  "sessionId": "BCAD9603-F714-447C-A9E6-07D58267966B"
}
```

A JSON response containing `"ready": true` confirms that WDA is ready to accept commands. Note the WDA host and port (or gateway base URL) so you can use the same connection settings in Playground and your project.

## Create a test project

```bash
pnpm dlx @midscene/test create my-tests \
  --platform ios \
  --package-manager pnpm
cd my-tests
```

The command generates the project files, installs dependencies, and generates the Node Spec. It does not run tests. For the generated files, see [Project structure](/midscene-test/use.md#project-structure).

## Configure a model

In the `my-tests` directory, copy `.env.example` to `.env`:
```bash
cp .env.example .env
```

Choose a model below. Its configuration has four values. Open **Get API key** to create a key with the provider, then replace `......` in `MIDSCENE_MODEL_API_KEY` with it.

The configuration below is for Doubao-Seed-2.1 Turbo. Other recommended models:

- [Qwen3.7 Plus](/model-api-setup.md#qwen) (Alibaba)
- [DeepSeek V4.1 Flash](/model-api-setup.md#deepseek) (DeepSeek)
- [Gemini 3.5 Flash](/model-api-setup.md#gemini) (Google)
- [GPT-6 Sol](/model-api-setup.md#gpt) (OpenAI)
- [Kimi K3](/model-api-setup.md#kimi) (Moonshot AI)
- [MiMo V2.6 Pro](/model-api-setup.md#xiaomi-mimo) (Xiaomi)
- [GLM-5V-Turbo](/model-api-setup.md#glm-v) (Zhipu AI)
- [Ling-3.0-flash-VL](/model-api-setup.md#ant-ling) (Ant Group)

**Volcano Engine** ([Get API key](https://console.volcengine.com/ark))

```bash
MIDSCENE_MODEL_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
MIDSCENE_MODEL_API_KEY="......"
MIDSCENE_MODEL_NAME="doubao-seed-2-1-turbo-260628"
MIDSCENE_MODEL_FAMILY="doubao-seed"
```

**OpenRouter** ([Get API key](https://openrouter.ai/settings/keys))

```bash
MIDSCENE_MODEL_BASE_URL="https://openrouter.ai/api/v1"
MIDSCENE_MODEL_API_KEY="......"
MIDSCENE_MODEL_NAME="bytedance-seed/seed-2-1-turbo"
MIDSCENE_MODEL_FAMILY="doubao-seed"
```

For other versions and usage notes, see [Doubao Seed series](/model-api-setup.md#doubao-seed-model).

To compare models, see the [Model selection guide](/model-selection.md). For compatible models such as UI-TARS, see [Use a model API key](/model-api-setup.md#supported-models).

Fill in the four `MIDSCENE_MODEL_*` values in `.env` with this configuration.

## Verify the model and finish setup
Verify model connectivity and Midscene compatibility. The command reads `.env` from the current directory and does not need a browser or device:
```bash
pnpm exec midscene-test model verify
```
If the check fails, see [Verify model connectivity](/model-config.md#verify-model-connectivity).

The project connects to WDA on `localhost:8100` by default. For another address, set `WDA_HOST` and `WDA_PORT` in `.env`, or `WDA_BASE_URL` when you connect through a gateway.

## Run the example and inspect the report

The example opens React TodoMVC in the device's browser and first checks that the list is empty. Keep the device unlocked. If todos remain from an earlier run, select **All** and delete every todo, including completed ones.

```bash
pnpm test
```
The terminal prints the results and a `Report:` path. Open the HTML report, then select a case and a step to inspect screenshots, inputs, outputs, and errors. Reports are written to `midscene_run/report/` by default.
When the case passes, your model, environment, and project are all working. For execution options, see [Run tests](/midscene-test/running.md).

## Next steps
- **Explore more examples**: [Showcases](/showcases.md) includes demo videos and full execution reports across platforms.

- **Test your own app**: In `cases/todo.yaml`, replace the TodoMVC setup in `beforeEach` with a `launch` Node that opens your app:

  ```yaml
  beforeEach:
    - launch: com.example.app

  cases:
    - name: Open the home screen
      steps:
        - aiAssert: The home screen of the app is visible
  ```

  Use the package name on Android, the bundle identifier on iOS, or the bundle name on HarmonyOS. See [Built-in Nodes across platforms](/midscene-test/builtin-nodes.md) for other system operations.

- **Write and organize cases**: [Write YAML cases](/midscene-test/writing.md) covers inputs, variables, tags, and hooks.
- **Run in CI**: [Run in GitHub Actions](/midscene-test/running.md#run-in-github-actions).