#开始使用：Android · Vitest · 模型 API Key

本页是在 Android 上使用 Vitest、通过模型 API Key 接入模型的配置步骤。如需其他组合，请修改下方的选择，或查看全部配置路径。

第 1 步

#安装 Node.js

安装 Node.js ^20.19.0 || ^22.12.0 || >=24.0.0，并确认终端中可以执行 node -v。

下文命令使用 pnpm。如果尚未安装，请运行 npm install -g pnpm。

第 2 步

#连接 Android 设备

运行 Midscene 的电脑需要通过 adb 连接目标 Android 设备，支持 USB 和无线 adb 两种连接方式。如果已安装 adb 并连接好设备，可直接跳至确认设备连接。

#安装 adb

• 通过 Android Studio 或独立的 Android 命令行工具安装 adb。
• 在终端运行以下命令，验证 adb 是否安装成功：

adb --version

输出类似以下内容即表示安装成功：

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)

• 参考 Android 环境变量文档配置 ANDROID_HOME 环境变量，并检查是否生效：

echo $ANDROID_HOME

输出应指向本机安装的 Android SDK 目录，例如：

/Users/your_username/Library/Android/sdk

#开启调试并连接设备

以下以 USB 连接为例；如果设备已通过无线 adb 连接，可继续使用现有连接。

1. 在手机系统设置的「开发者选项」中开启 USB 调试（若同时存在 USB 调试（安全设置），请一并开启，以确保支持触控事件注入）。
2. 使用支持数据传输的 USB 数据线将手机连接到电脑。
3. 保持手机解锁亮屏，在手机弹出的授权窗口中勾选并允许 USB 调试。

#确认设备连接

在终端运行以下命令检查连接状态：

adb devices -l

输出中设备状态显示为 device 即表示连接就绪：

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

如果同时连接了多台设备，请记录目标设备所在行第一列的设备 ID（如上例中的 s4ey59），以便后续在 Playground 或项目配置中指定该设备。

若未显示目标设备或状态不是 device，请按以下情况排查：

• 列表为空：USB 连接请检查数据线（需支持数据传输）、USB 连接模式和 USB 调试开关；无线连接请检查网络及 adb connect 连接状态。
• unauthorized：请解锁手机屏幕，在手机弹出的授权窗口中勾选并允许 USB 调试。
• offline：请重新建立 USB 或无线 adb 连接，必要时重启 adb 服务。请确认设备状态变为 device 后再继续后续步骤。

第 3 步

#配置模型

在下方选择一个模型，它的配置包含四项。点击获取 API Key到服务商创建 API Key，再用它替换 MIDSCENE_MODEL_API_KEY 中的 ......。

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"

其他版本与使用说明请参阅豆包 Seed 系列。

各模型的差异请参阅模型选择指南。UI-TARS 等兼容模型请参阅使用模型 API Key。

在项目目录中，把这四项配置写入 .env 文件。如果还没有项目，请先新建一个目录并在其中运行 pnpm init。

第 4 步

#搭建项目

在 .env 所在的项目目录中，验证模型配置：

pnpm dlx @midscene/test@latest model verify

如果验证失败，请参阅验证模型连接。

#安装依赖

pnpm add -D vitest dotenv @midscene/android

#配置 Vitest

新建 vitest.config.ts。如果项目已在使用 Vitest，可以将设备测试配置单独保存为 vitest.device.config.ts，运行时通过 --config vitest.device.config.ts 指定，以免影响现有的单元测试配置。

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 },
  },
});

由于模型调用和设备连接耗时较长，请根据实际用例适当调大 testTimeout 与 hookTimeout。在共享同一台设备时，需关闭文件级并行（fileParallelism: false）并保持用例串行执行（sequence.concurrent: false），同时避免在代码中调用 test.concurrent 或 describe.concurrent。相关配置项详见 Vitest 的 fileParallelism、testTimeout 和 hookTimeout 文档。

第 5 步

#编写测试

新建 e2e/settings.test.ts，在 beforeEach 中为每个用例创建新的 Agent，并在 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');
});

连接多台设备时，通过 agentFromAdbDevice(deviceId) 指定设备 ID。连接参数详见 Android SDK 文档。

dotenv/config 用于从项目的 .env 文件加载模型配置（Playground 中的配置不会自动同步到测试进程）。

当 aiAssert 的断言未通过时，会直接抛出错误，Vitest 随即将其所在用例标记为失败，并继续执行 afterEach 销毁 Agent。你也可以用 aiQuery 等方法提取界面数据，再交给 Vitest 的 expect 进行校验。更多交互与提取方法见 Agent API 参考。

第 6 步

#运行测试并查看报告

pnpm exec vitest run e2e/settings.test.ts

运行后，Vitest 会在终端汇总用例的通过或失败状态；Midscene SDK 则默认在 midscene_run/report/ 下生成各 Agent 的执行报告，并在终端打印报告路径。在浏览器中打开生成的 HTML 报告，即可查看各步骤的截图、AI 执行过程和断言结果。

与 Playwright Test 不同，Vitest 接入直接使用 SDK 内置的报告生成机制，无需额外部署 reporter。Vitest 的测试结果与 Midscene 的 Agent 报告相互独立；如需合并或进一步处理报告文件，请参阅处理报告文件。

测试通过且报告中能看到每一步的截图，即表示模型、运行环境和项目都已正常工作。

第 7 步

#下一步

• 查看更多案例：案例展示收录了各平台的演示视频和完整执行报告。

• 查阅 API：API reference 列出了全部 Agent 方法及其参数。
• 将 AI 调用与代码结合：关键 API 说明了 aiAct、即时操作和洞察类 API 的适用场景。

• 多个测试共用设备：生命周期与设备独占说明了多个测试共用一台设备时如何创建和销毁 Agent。

想尝试其他平台或使用方式？回到顶部修改选择。