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

# 开始使用：Web · Playwright Test · ChatGPT 订阅 {#get-started}

本页是在 **Web** 上使用 **Playwright Test**、通过 **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`。

## 使用 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)。

### 安装依赖并配置 Playwright
如果该目录中还没有 Playwright Test 项目，请先安装 Playwright Test 及其 Chromium 浏览器：
```bash
pnpm add -D @playwright/test
pnpm exec playwright install chromium
```

```sh [npm]
npm install @midscene/web dotenv --save-dev
```

```sh [yarn]
yarn add @midscene/web dotenv --save-dev
```

```sh [pnpm]
pnpm add @midscene/web dotenv --save-dev
```

```sh [bun]
bun add @midscene/web dotenv --save-dev
```

```sh [deno]
deno add npm:@midscene/web npm:dotenv --save-dev
```

在 `playwright.config.ts` 中加入以下配置（如果项目中还没有该文件，请新建），并保留项目原有的其他配置和 reporter：

```typescript title="playwright.config.ts"
import 'dotenv/config';
import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './e2e',
  timeout: 90_000,
  use: { browserName: 'chromium' },
  reporter: [
    ['list'],
    ['@midscene/web/playwright-reporter'],
  ],
});
```

`dotenv/config` 用于从项目的 `.env` 文件加载模型配置（Chrome 插件 Playground 中的配置不会自动同步到测试进程）。由于模型调用耗时较长，建议适当调大 `timeout`，具体数值可根据实际用例调整。
### 创建 fixture
新建 `e2e/fixture.ts`，通过 `PlaywrightAiFixture` 扩展 Playwright 的 `test`：

```typescript title="e2e/fixture.ts"
import { test as base } from '@playwright/test';
import {
  PlaywrightAiFixture,
  type PlayWrightAiFixtureType,
} from '@midscene/web/playwright';

export const test = base.extend<PlayWrightAiFixtureType>(
  PlaywrightAiFixture(),
);
```

在需要使用 Midscene 的测试文件中，从 `./fixture` 导入 `test`；`expect` 仍从 `@playwright/test` 导入。

## 编写测试

```typescript title="e2e/todo.spec.ts"
import { expect } from '@playwright/test';
import { test } from './fixture';

test('add a todo', async ({ page, aiAct, aiAssert }) => {
  await page.goto('https://todomvc.com/examples/react/dist/');
  await expect(page).toHaveTitle(/TodoMVC/);

  await aiAct('Add a todo named Try Midscene');
  await aiAssert('The todo list contains Try Midscene');
});
```

Playwright 的 `page`、`expect` 可以与 Midscene 的 AI 方法在同一测试中配合使用。在这个示例中，Playwright 负责打开页面并校验标题，Midscene 负责添加待办事项并断言页面结果。除 `aiAct` 和 `aiAssert` 外，fixture 还提供 `aiTap`、`aiInput`、`aiQuery`、`aiWaitFor` 等方法，详见 [Agent API 参考](/zh/reference/index.md#interaction-methods)。

## 运行测试并查看报告

在项目目录下运行测试：

```bash
pnpm exec playwright test e2e/todo.spec.ts
```

测试结束后，Midscene reporter 会在终端输出报告路径（默认保存在 `midscene_run/report/` 下）。在浏览器中打开生成的 HTML 报告，即可查看各步骤的截图、AI 执行过程和断言结果，方便回溯执行细节或排查失败原因。

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

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

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

- **配置 fixture 和 reporter**：[进一步配置](/zh/integrate-with-playwright.md#进一步配置)介绍了 Agent 选项、指定页面操作和报告选项。