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

These are the setup steps for Midscene on Android 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 Android device

Midscene uses adb on your computer to communicate with the target Android device over either USB or wireless adb. If adb is already installed and your device is connected, skip directly to Verify the device connection.

#Install adb

• Install adb via Android Studio or the standalone Android command-line tools.
• Run the following command to verify the installation:

adb --version

Output similar to the following confirms a working installation:

Android Debug Bridge version 1.0.41
Version 34.0.4-10411341
Installed as /usr/local/bin/adb
Running on Darwin 24.3.0 (arm64)

• Configure the ANDROID_HOME environment variable as described in Android environment variables, then check that it takes effect:

echo $ANDROID_HOME

The output should point to your local Android SDK directory, for example:

/Users/your_username/Library/Android/sdk

#Enable debugging and connect the device

The steps below use a USB connection as an example. If your device is already connected over wireless adb, you can keep using that connection.

1. In your phone's Developer options, enable USB debugging (and USB debugging (Security settings) if available, so Midscene can inject touch events).
2. Connect the phone to your computer using a USB cable that supports data transfer.
3. Keep the phone unlocked and accept the Allow USB debugging prompt on the screen.

#Verify the device connection

Run the following command to check the connection status:

adb devices -l

When the device status shows device, the connection is ready:

List of devices attached
s4ey59	device usb:34603008X product:cezanne model:M2006J device:cezan transport_id:3

If multiple devices are connected, note the device ID in the first column (such as s4ey59 above) so you can select the target device in Playground or your project configuration.

If the target device does not appear with the device status, check the following:

• Empty list: For USB, check the data cable (ensure it is not charge-only), USB connection mode, and USB debugging toggle; for wireless adb, check the network and adb connect status.
• unauthorized: Unlock the phone screen and accept the Allow USB debugging prompt on the device.
• offline: Reconnect the USB cable or wireless adb session, and restart adb if needed. Proceed only after the status shows device.

Step 3

#Create a test project

pnpm dlx @midscene/test create my-tests \
  --platform android \
  --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.

If more than one device is connected, set ANDROID_DEVICE_ID in .env to an ID from adb devices -l.

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.