#开始使用：桌面端 · Midscene Test · ChatGPT 订阅

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

第 1 步

#安装 Node.js

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

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

第 2 步

#授予桌面系统权限

• macOS：需要为启动 Playground 或运行脚本的终端 / IDE（如 Terminal、iTerm2、VS Code、Cursor、WebStorm 等）授予两项独立的系统权限：
  1. 辅助功能权限（用于控制鼠标与键盘）：前往「系统设置 > 隐私与安全性 > 辅助功能」开启对应应用的开关（详见 nut.js macOS 配置说明）。
  2. 屏幕录制权限（用于截取桌面画面）：前往「系统设置 > 隐私与安全性 > 屏幕录制」开启对应应用的开关。授权后请完全退出并重启该终端或 IDE，再启动 Playground。
• Windows：操作常规权限的桌面程序无需额外配置。但受 Windows 用户界面特权隔离（UIPI）机制限制，未提权的普通进程无法向「以管理员身份运行」的高权限窗口注入鼠标点击或按键事件（光标仍能移动到目标位置，但点击和按键会被系统静默丢弃）。建议优先以普通权限启动被测程序；若被测程序必须以管理员身份运行，请同样以管理员身份启动运行 Midscene 的终端或 Node.js 进程（详见下方常见问题）。
• Linux（图形桌面）：需安装 ImageMagick 以提供截图能力。
• Linux（无头服务器 / CI 环境）：在没有物理显示器的 Linux 服务器（如 GitHub Actions）上运行时，需安装 Xvfb 与 ImageMagick，并开启无头（Headless）模式自动创建虚拟显示器：

# 安装依赖
sudo apt-get install -y xvfb x11-xserver-utils imagemagick

使用 Xvfb 时，请确保被测应用同样启动在该虚拟显示器环境中（本机带有物理显示器时无需开启此项）。

如需通过 RDP 控制远程 Windows 桌面，请参阅桌面端环境配置。

第 3 步

#创建测试项目

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

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

第 4 步

#使用 ChatGPT 订阅登录

首先，在终端运行：

pnpm dlx @midscene/cli model siwc login

按照终端提示，在浏览器中登录 ChatGPT 并授权使用订阅额度。授权时可以自行设置 Agent 名称；完成后，可在 ChatGPT 的使用情况页面查看已授权的 Agent。

命令会将凭据保存到 ~/.midscene/siwc.json。首次使用前需要手动完成这一步登录。

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

cp .env.example .env

MIDSCENE_MODEL_BASE_URL 和 MIDSCENE_MODEL_API_KEY 留空。设置 MIDSCENE_MODEL_NAME 和 MIDSCENE_MODEL_FAMILY，并添加 MIDSCENE_MODEL_AUTH_MODE：

MIDSCENE_MODEL_AUTH_MODE="siwc"
MIDSCENE_MODEL_NAME="gpt-6-sol"
MIDSCENE_MODEL_FAMILY="gpt-6"

可用模型以你的 ChatGPT 账号为准。凭据与额度说明请参阅使用 ChatGPT 订阅。

第 5 步

#验证模型并完成配置

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

pnpm exec midscene-test model verify

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

如需控制主显示器以外的显示器，请在 .env 中设置 COMPUTER_DISPLAY_ID。在无界面 Linux 环境中，还需设置 MIDSCENE_COMPUTER_HEADLESS_LINUX=true。

第 6 步

#运行示例并查看报告

示例会在目标显示器的浏览器中打开 React TodoMVC，并先检查列表为空。运行期间请勿移动鼠标或操作键盘。如果列表中留有之前运行产生的待办事项，请切换到 All 并删除全部事项（包括已完成的事项）。

pnpm test

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

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

第 7 步

#下一步

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

• 测试自己的应用：在被控制的显示器上打开目标应用，再用 aiAct 和 aiAssert 描述步骤。如需在用例中启动或重置应用，请开发自定义 Node。

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

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