#Get started: iOS · Midscene Test · Model API Key

These are the setup steps for Midscene on iOS with Midscene Test and a Model API Key. To choose another combination, change the answers below or see all setup paths.

Step 1

#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.

Step 2

#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.

#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

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

• Simulator setup: Run Prebuilt WDA
• Physical device setup: Real Device Configuration

#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.

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:

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

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:

{
  "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.

Step 3

#Create a test project

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.

Step 4

#Configure a model

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

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.

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"

For other versions and usage notes, see Doubao Seed series.

To compare models, see the Model selection guide. For compatible models such as UI-TARS, see Use a model API key.

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

Step 5

#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:

pnpm exec midscene-test model verify

If the check fails, see 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.

Step 6

#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.

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.

Step 7

#Next steps

• Explore more examples: Showcases 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:

  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 for other system operations.

• Write and organize cases: Write YAML cases covers inputs, variables, tags, and hooks.
• Run in CI: Run in GitHub Actions.

Want to try another platform or way to use Midscene? Back to top to change your selections.