开始使用：Web · Playwright Test · 模型 API Key

本页是在 Web 上使用 Playwright 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 步

配置模型

在下方选择一个模型，它的配置包含四项。点击获取 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 文件。如果还没有项目，请先新建一个目录并在其中运行 pnpm init。

第 3 步

搭建项目

在 .env 所在的项目目录中，验证模型配置：

pnpm dlx @midscene/test@latest model verify

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

安装依赖并配置 Playwright

如果该目录中还没有 Playwright Test 项目，请先安装 Playwright Test 及其 Chromium 浏览器：

pnpm add -D @playwright/test
pnpm exec playwright install chromium

npm

yarn

pnpm

bun

deno

npm install @midscene/web dotenv --save-dev

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

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：

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 导入。

第 4 步

编写测试

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 参考。

第 5 步

运行测试并查看报告

在项目目录下运行测试：

pnpm exec playwright test e2e/todo.spec.ts

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

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

第 6 步

下一步

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

查阅 API：API reference 列出了全部 Agent 方法及其参数。
将 AI 调用与代码结合：关键 API 说明了 aiAct、即时操作和洞察类 API 的适用场景。

配置 fixture 和 reporter：进一步配置介绍了 Agent 选项、指定页面操作和报告选项。

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

#开始使用：Web · Playwright Test · 模型 API Key

#安装 Node.js

#配置模型

#搭建项目

#安装依赖并配置 Playwright

#创建 fixture

#编写测试

#运行测试并查看报告

#下一步