> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# 开始使用：桌面端 · Vitest · ChatGPT 订阅 {#get-started}

本页是在**桌面端**上使用 **Vitest**、通过 **ChatGPT 订阅**接入模型的配置步骤。如需其他组合，请查看[全部配置路径](/zh/get-started.md#all-setup-paths)。

## 安装 Node.js
安装 Node.js `^20.19.0 || ^22.12.0 || >=24.0.0`，并确认终端中可以执行 `node -v`。
下文命令使用 pnpm。如果尚未安装，请运行 `npm install -g pnpm`。

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

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

使用 Xvfb 时，请确保被测应用同样启动在该虚拟显示器环境中（本机带有物理显示器时无需开启此项）。
如需通过 RDP 控制远程 Windows 桌面，请参阅[桌面端环境配置](/zh/platforms/desktop.md#connect-device)。

## 使用 ChatGPT 订阅登录
首先，在终端运行：

```bash
pnpm dlx @midscene/cli model siwc login
```

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

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

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

```bash
MIDSCENE_MODEL_AUTH_MODE="siwc"
MIDSCENE_MODEL_NAME="gpt-6-sol"
MIDSCENE_MODEL_FAMILY="gpt-6"
```
可用模型以你的 ChatGPT 账号为准。凭据与额度说明请参阅[使用 ChatGPT 订阅](/zh/chatgpt-subscription.md#额度与凭据)。

## 搭建项目
在 `.env` 所在的项目目录中，验证模型配置：
```bash
pnpm dlx @midscene/test@latest model verify
```
如果验证失败，请参阅[验证模型连接](/zh/model-config.md#verify-model-connectivity)。

### 安装依赖

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

```typescript title="vitest.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](https://vitest.dev/config/fileparallelism)、[testTimeout](https://vitest.dev/config/testtimeout) 和 [hookTimeout](https://vitest.dev/config/hooktimeout) 文档。

## 编写测试

新建 `e2e/settings.test.ts`，在 `beforeEach` 中为每个用例创建新的 Agent，并在 `afterEach` 中销毁：

```typescript title="e2e/settings.test.ts"
import 'dotenv/config';
import { afterEach, beforeEach, test } from 'vitest';
import { agentForComputer } from '@midscene/computer';

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

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

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.aiWaitFor('The Settings app is visible');
  await agent.aiAct('Scroll down one screen');
  await agent.aiAssert('The Settings app is still visible');
});
```
运行前，打开系统设置应用，将可滚动的设置页面置于前台，并在测试期间保持可见。权限和连接参数详见[桌面端 SDK 文档](/zh/sdk/desktop.md)。

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

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

## 运行测试并查看报告

```bash
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 报告相互独立；如需合并或进一步处理报告文件，请参阅[处理报告文件](/zh/consume-report-file.md)。

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

## 下一步
- **查看更多案例**：[案例展示](/zh/showcases.md)收录了各平台的演示视频和完整执行报告。

- **查阅 API**：[API reference](/zh/reference.md) 列出了全部 Agent 方法及其参数。
- **将 AI 调用与代码结合**：[关键 API](/zh/basics.md#javascript-orchestration) 说明了 `aiAct`、即时操作和洞察类 API 的适用场景。

- **多个测试共用设备**：[生命周期与设备独占](/zh/sdk/vitest.md#生命周期与设备独占)说明了多个测试共用一台设备时如何创建和销毁 Agent。