#Get started: Android · Vitest · ChatGPT subscription

These are the setup steps for Midscene on Android with Vitest and a ChatGPT subscription. 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

#Sign in with your ChatGPT subscription

First, run the following command in your terminal:

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 write these lines to a .env file in your project directory. If you are starting without a project, create a directory and run pnpm init in it first.

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.

Step 4

#Set up the project

In the project directory that contains .env, verify the model configuration:

pnpm dlx @midscene/test@latest model verify

If the check fails, see Verify model connectivity.

#Install dependencies

pnpm add -D vitest dotenv @midscene/android

#Configure Vitest

Create vitest.config.ts. If your project already uses Vitest for unit tests, you can save this configuration separately as vitest.device.config.ts and pass --config vitest.device.config.ts when running device tests, leaving your existing test configuration untouched.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    include: ['e2e/**/*.test.ts'],
    environment: 'node',
    testTimeout: 90_000,
    hookTimeout: 90_000,
    fileParallelism: false,
    sequence: { concurrent: false },
  },
});

Because model calls and device connections take longer than standard unit tests, adjust testTimeout and hookTimeout to fit your test cases. When running against a single shared device, disable file parallelism (fileParallelism: false) and run tests sequentially (sequence.concurrent: false), and avoid test.concurrent or describe.concurrent. For details, see the Vitest documentation on fileParallelism, testTimeout, and hookTimeout.

Step 5

#Write a test

Create e2e/settings.test.ts, initializing a new Agent for each test in beforeEach and destroying it in afterEach:

import 'dotenv/config';
import { afterEach, beforeEach, test } from 'vitest';
import { agentFromAdbDevice } from '@midscene/android';

let agent: Awaited<ReturnType<typeof agentFromAdbDevice>> | undefined;

beforeEach(async () => {
  agent = await agentFromAdbDevice();
});

afterEach(async () => {
  const currentAgent = agent;
  agent = undefined;
  await currentAgent?.destroy();
});

test('scroll through settings', async () => {
  if (!agent) throw new Error('Agent was not initialized');

  await agent.launch('com.android.settings');
  await agent.aiWaitFor('The Settings app is visible');
  await agent.aiAct('Scroll down one screen');
  await agent.aiAssert('The Settings app is still visible');
});

If multiple devices are connected, pass a device ID to agentFromAdbDevice(deviceId). See the Android SDK guide for connection options.

dotenv/config loads model settings from the project's .env file (settings in the Playground are not automatically shared with test runs).

When an aiAssert check fails, it throws an error, causing Vitest to mark the test as failed before running afterEach to clean up the Agent. You can also extract data from the screen with methods like aiQuery and pass the result to Vitest's expect. For more interaction and extraction methods, see the Agent API reference.

Step 6

#Run the test and inspect the report

pnpm exec vitest run e2e/settings.test.ts

Vitest prints the pass or fail status of each test in the terminal, while the Midscene SDK generates an execution report for each Agent under midscene_run/report/ by default and prints the report path. Open the generated HTML file in a browser to inspect step-by-step screenshots, AI execution details, and assertion results.

Unlike Playwright Test, Vitest integration uses the SDK's built-in report generation directly and does not require a custom reporter. Vitest test results and Midscene Agent reports are generated separately; to merge or further process report files, see Process report files.

When the test passes and the report shows each step with screenshots, your model, environment, and project are all working.

Step 7

#Next steps

• Explore more examples: Showcases includes demo videos and full execution reports across platforms.

• Look up APIs: API reference lists every Agent method and its options.
• Combine AI calls with code: Key APIs explains when to use aiAct, instant actions, and insight APIs.

• Share a device across tests: Lifecycle and exclusive device access explains how to create and destroy Agents when tests share one device.

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