#Get started: HarmonyOS · Midscene Test · ChatGPT subscription

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

Midscene uses hdc on your computer to communicate with the target HarmonyOS NEXT device. If hdc is already installed and your device is connected, skip directly to Verify the device connection.

#Install HDC

HDC (HarmonyOS Device Connector) is the official command-line tool for communicating with HarmonyOS devices. Install it using either of the following methods:

• Via DevEco Studio (recommended)
• Via the standalone HarmonyOS Command Line Tools

Run the following command to verify the installation:

hdc version

A version number in the terminal output confirms a working installation.

export HDC_HOME=/path/to/hdc/directory

#Enable debugging and connect the device

1. On your HarmonyOS device, open Settings > System > Developer options and enable USB debugging.
2. Connect the device to your computer using a USB cable that supports data transfer.
3. Keep the device unlocked and accept the debugging authorization prompt on the screen.

#Verify the device connection

Run the following command to check the connection status:

hdc list targets

A device ID in the output confirms that the device is connected and ready:

0123456789ABCDEF

If multiple devices are connected, note the target device ID so you can select it in Playground or your project configuration. If the output is empty or [Empty], check the USB cable, USB connection mode, USB debugging toggle, and the authorization prompt on the device.

Step 3

#Create a test project

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

#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, in the my-tests directory, copy .env.example to .env:

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:

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 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 HARMONY_DEVICE_ID in .env to an ID from hdc list targets. If hdc is not on PATH, set HDC_HOME.

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.