> 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 · 模型 API Key {#get-started}

本页是在 **Web** 上使用 **Playwright Test**、通过**模型 API Key** 接入模型的配置步骤。如需其他组合，请查看[全部配置路径](/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`。

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

下方是 Doubao-Seed-2.1 Turbo 的配置。其他推荐模型：

- [Qwen3.7 Plus](/zh/model-api-setup.md#qwen) (阿里巴巴)
- [DeepSeek V4.1 Flash](/zh/model-api-setup.md#deepseek) (深度求索)
- [Gemini 3.5 Flash](/zh/model-api-setup.md#gemini) (Google)
- [GPT-6 Sol](/zh/model-api-setup.md#gpt) (OpenAI)
- [Kimi K3](/zh/model-api-setup.md#kimi) (月之暗面)
- [MiMo V2.6 Pro](/zh/model-api-setup.md#xiaomi-mimo) (小米)
- [GLM-5V-Turbo](/zh/model-api-setup.md#glm-v) (智谱)
- [Ling-3.0-flash-VL](/zh/model-api-setup.md#ant-ling) (蚂蚁集团)

**火山引擎** ([获取 API Key](https://console.volcengine.com/ark))

```bash
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"
```

**OpenRouter** ([获取 API Key](https://openrouter.ai/settings/keys))

```bash
MIDSCENE_MODEL_BASE_URL="https://openrouter.ai/api/v1"
MIDSCENE_MODEL_API_KEY="......"
MIDSCENE_MODEL_NAME="bytedance-seed/seed-2-1-turbo"
MIDSCENE_MODEL_FAMILY="doubao-seed"
```

其他版本与使用说明请参阅[豆包 Seed 系列](/zh/model-api-setup.md#doubao-seed-model)。

各模型的差异请参阅[模型选择指南](/zh/model-selection.md)。UI-TARS 等兼容模型请参阅[使用模型 API Key](/zh/model-api-setup.md#支持的模型)。

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

## 搭建项目
在 `.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 选项、指定页面操作和报告选项。