#开始使用：HarmonyOS · Midscene Test · 模型 API Key

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

第 1 步

#安装 Node.js

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

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

第 2 步

#连接 HarmonyOS 设备

运行 Midscene 的电脑需要通过 hdc 连接目标 HarmonyOS NEXT 设备。如果已安装 hdc 并连接好设备，可直接跳至确认设备连接。

#安装 HDC

HDC（HarmonyOS Device Connector）是 HarmonyOS 官方提供的设备连接命令行工具，可通过以下任一方式安装：

• 通过 DevEco Studio 安装（推荐）
• 下载 HarmonyOS 命令行工具（Command Line Tools）独立安装

在终端运行以下命令，验证 hdc 是否安装成功：

hdc version

终端输出版本号即表示安装成功。

export HDC_HOME=/path/to/hdc/directory

#开启调试并连接设备

1. 在 HarmonyOS 设备的系统设置中进入「系统 > 开发者选项」，开启 USB 调试。
2. 使用支持数据传输的 USB 数据线将设备连接到电脑。
3. 保持设备解锁亮屏，并在设备弹窗中允许 USB 调试授权。

#确认设备连接

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

hdc list targets

终端输出设备序列号（Device ID）即表示连接就绪：

0123456789ABCDEF

如果同时连接了多台设备，请记录目标设备的序列号，以便后续在 Playground 或项目配置中指定该设备。若输出为空或显示 [Empty]，请检查 USB 数据线、连接模式、USB 调试开关及手机端的调试授权弹窗。

第 3 步

#创建测试项目

pnpm dlx @midscene/test create my-tests \
  --platform harmony \
  --package-manager pnpm
cd my-tests

该命令会生成项目文件、安装依赖并生成 Node 说明书，不会运行测试。生成的文件说明请参阅项目结构。

第 4 步

#配置模型

在 my-tests 目录中，将 .env.example 复制为 .env：

cp .env.example .env

在下方选择一个模型，它的配置包含四项。点击获取 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 中的四项 MIDSCENE_MODEL_* 变量。

第 5 步

#验证模型并完成配置

运行以下命令，检查模型能否连通、是否与 Midscene 兼容。该命令只读取当前目录下的 .env，不需要浏览器或设备：

pnpm exec midscene-test model verify

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

如果连接了多台设备，请在 .env 中将 HARMONY_DEVICE_ID 设置为 hdc list targets 输出中的设备 ID。如果 hdc 不在 PATH 中，请设置 HDC_HOME。

第 6 步

#运行示例并查看报告

示例会在设备浏览器中打开 React TodoMVC，并先检查列表为空。请保持设备解锁。如果列表中留有之前运行产生的待办事项，请切换到 All 并删除全部事项（包括已完成的事项）。

pnpm test

终端会输出测试结果和 Report: 报告路径。打开 HTML 报告，选择用例和步骤即可查看截图、输入输出和错误信息。报告默认保存在 midscene_run/report/ 目录下。

用例通过即表示模型、运行环境和项目都已正常工作。运行参数请参阅运行测试。

第 7 步

#下一步

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

• 测试自己的应用：在 cases/todo.yaml 中，将 beforeEach 里的 TodoMVC 初始化步骤替换为打开应用的 launch Node：

  beforeEach:
    - launch: com.example.app
  
  cases:
    - name: 打开首页
      steps:
        - aiAssert: 应用首页已显示

  Android 使用包名，iOS 使用 Bundle ID，HarmonyOS 使用 bundle name。其他系统操作请参阅各平台预置 Node。

• 编写和组织用例：编写 YAML 用例介绍了输入、变量、标签和 hooks。
• 在 CI 中运行：请参阅在 GitHub Actions 中运行。

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