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

# Get started: Android · Midscene Test · ChatGPT subscription {#get-started}

These are the setup steps for Midscene on **Android** with **Midscene Test** and a **ChatGPT subscription**. 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 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](#verify-device-connection).

### Install adb

- Install `adb` via [Android Studio](https://developer.android.com/studio) or the standalone [Android command-line tools](https://developer.android.com/studio#command-line-tools-only).
- Run the following command to verify the installation:

```bash
adb --version
```

Output similar to the following confirms a working installation:

```log
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](https://developer.android.com/tools/variables), then check that it takes effect:

```bash
echo $ANDROID_HOME
```

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

```log
/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.

![android usb debug](/images/android-usb-debug-en.png)

### Verify the device connection {#verify-device-connection}

Run the following command to check the connection status:

```bash
adb devices -l
```

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

```log
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`.

## Create a test project

```bash
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](/midscene-test/use.md#project-structure).

## Sign in with your ChatGPT subscription
First, run the following command in your terminal:

```bash
pnpm dlx @midscene/cli model siwc login
```

Follow the terminal instructions to sign in to ChatGPT in your browser and authorize plan usage. You can choose a name for your Agent during authorization. Once authorized, the Agent appears on your ChatGPT usage page.

The command saves credentials to `~/.midscene/siwc.json`. Complete this sign-in manually before first use.

Then, in the `my-tests` directory, copy `.env.example` to `.env`:
```bash
cp .env.example .env
```
Leave `MIDSCENE_MODEL_BASE_URL` and `MIDSCENE_MODEL_API_KEY` empty. Set `MIDSCENE_MODEL_NAME` and `MIDSCENE_MODEL_FAMILY`, and add `MIDSCENE_MODEL_AUTH_MODE`:

```bash
MIDSCENE_MODEL_AUTH_MODE="siwc"
MIDSCENE_MODEL_NAME="gpt-6-sol"
MIDSCENE_MODEL_FAMILY="gpt-6"
```
Available models depend on your ChatGPT account. For credentials and usage, see [Use a ChatGPT subscription](/chatgpt-subscription.md#usage-and-credentials).

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

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

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