前言在上一篇文章中我们初识了 Midscene.js 这个 AI 驱动的 UI 自动化框架。本篇文章将深入讲解 Midscene.js 与 Playwright 测试套件的集成方式帮助你利用 AI 能力快速编写智能化的端到端测试用例。Midscene.js 提供了两种与 Playwright 配合使用的模式脚本模式适合快速体验、一次性数据抓取任务直接实例化 PlaywrightAgent 调用 AI 方法测试套件模式适合正式的 UI 自动化测试场景通过 Playwright 的 Fixture 机制注入 AI 能力集成方式适用场景核心类直接脚本集成快速原型、数据抓取、一次性自动化脚本PlaywrightAgent测试套件集成正式 UI 测试、CI/CD 流水线、团队协作PlaywrightAiFixture本文将重点围绕测试框架模式展开涵盖环境搭建、Fixture 注入、配置文件编写与报告器配置四大主题。一、Playwright 测试套件集成1.1环境准备首先确保项目中已安装Playwright 相关依赖npm install midscene/web playwright playwright/test --save-dev midscene/web 是 Midscene.js 的浏览器集成包提供了 Playwright Agent 与 Fixture 等核心能力。“midscene/web 是 Midscene.js 的浏览器集成包提供了 Playwright Agent 与 Fixture 等核心能力。”1.2 配置 AI 模型Midscene.js 通过环境变量来指定所使用的 AI 模型服务。在项目根目录创建 .env 文件# 模型服务地址支持 OpenAI 兼容接口 MIDSCENE_MODEL_BASE_URLhttps://api.openai.com/v1 # API Key MIDSCENE_MODEL_API_KEYsk-your-api-key # 模型名称 MIDSCENE_MODEL_NAMEgpt-4o # 模型系列如 qwen-vl-max、gpt-4o 等 MIDSCENE_MODEL_FAMILYgpt-4oMidscene.js 支持任何兼容 OpenAI 接口的模型服务包括1.3 目录结构建议一个典型的 Midscene.js Playwright 项目目录如下my-midscene-tests/ ├── .env # 环境变量模型配置 ├── playwright.config.ts # Playwright 配置文件 ├── package.json ├── e2e/ │ ├── fixture.ts # 自定义 Fixture注入 AI 能力 │ ├── ebay-search.spec.ts # 测试用例 │ └── login.spec.ts # 更多测试用例 └── midscene_run/ └── report/ # 测试报告输出目录二、Fixture 注入方式Fixture 是 Playwright 测试框架的核心机制之一。Midscene.js 通过 PlaywrightAiFixture 将 AI 能力注入到每个测试用例中让你可以像使用普通 Playwright fixture 一样调用 AI 方法。2.1 创建自定义 Fixture在 ./e2e/fixture.ts 中定义import { test as base } from playwright/test; import type { PlayWrightAiFixtureType } from midscene/web/playwright; import { PlaywrightAiFixture } from midscene/web/playwright; export const test base.extendPlayWrightAiFixtureType( PlaywrightAiFixture({ waitForNetworkIdleTimeout: 2000, // 操作后等待网络空闲的超时ms replanningCycleLimit: 30, // AI 重规划次数上限 }), );2.2 PlaywrightAiFixture() 完整配置项PlaywrightAiFixture() 接收一个可选配置对象支持所有 PlaywrightAgent 构造参数2.3 在测试用例中使用从自定义 fixture 中你可以直接解构出以下 AI 方法import { expect } from playwright/test; import { test } from ./fixture; test(搜索功能测试, async ({ ai, // 通用 Agent 实例 aiQuery, // 结构化数据查询 aiAssert, // AI 断言 aiInput, // 文本输入 aiTap, // 点击操作 aiScroll, // 页面滚动 aiWaitFor, // 等待某个条件满足 aiRightClick, // 右键点击 recordToReport, // 记录自定义内容到报告 }) { await page.goto(https://example.com); // 使用自然语言描述操作 await aiInput(无线耳机, 搜索框); await aiTap(搜索按钮); await aiWaitFor(搜索结果列表已加载出来, { timeoutMs: 5000 }); // 提取结构化数据 const items await aiQueryArray{ title: string; price: number }( 获取搜索结果中的商品标题和价格, ); console.log(搜索结果, items); expect(items?.length).toBeGreaterThan(0); // AI 断言 await aiAssert(界面左侧存在类目筛选功能); // 记录到报告 await recordToReport(搜索结果截图, { content: 耳机搜索的最终结果 }); });2.4 各 AI 方法功能速览2.5 访问底层 Agent 实例如果需要更底层的控制可以通过 agentForPage 获取原始的 PageAgent 实例test(底层 Agent 操作, async ({ agentForPage, page }) { const agent await agentForPage(page); // 执行任意 AI 操作 await agent.aiAct(点击登录按钮); // 获取内部日志 const logContent agent._unstableLogContent(); console.log(Agent 日志, logContent); // 手动记录到报告 await agent.recordToReport(); });三、playwright.config.ts 配置3.1 基础配置在项目根目录创建 playwright.config.tsimport { defineConfig } from playwright/test; export default defineConfig({ // 测试文件所在目录 testDir: ./e2e, // 单个测试用例的超时时间ms // AI 操作相比传统测试耗时更长建议设置 60-90 秒 timeout: 90 * 1000, // 全局 expect 断言超时 expect: { timeout: 30 * 1000, }, // 失败重试次数 retries: 1, // 并行执行的 worker 数量 workers: 1, // AI 测试建议设为 1避免并发冲突 // 使用 Chromium 浏览器推荐 use: { browserName: chromium, headless: true, viewport: { width: 1280, height: 720 }, // 设置 deviceScaleFactor 避免 headed 模式闪动 // deviceScaleFactor: 2, }, // 报告器配置详见第四章 reporter: [ [list], [midscene/web/playwright-reporter, { type: merged }], ], });3.2 关键配置说明timeout Midscene.js 的每次 AI 操作都需要与模型交互耗时远超传统选择器操作。建议将全局 timeout 设置为 90 * 100090 秒甚至更长避免 AI 推理过程中的误判超时。workers 由于 AI 模型 API 通常有并发限制且多个 worker 同时调用可能导致 API 限流或成本急剧上升。建议将 workers 设为 1 串行执行或者根据 API 配额谨慎设置。browserName 强烈推荐使用 chromium。Midscene.js 的部分高级能力如 CDP 协议操作在 Firefox 和 WebKit 上可能受限。headless AI 视觉模型不依赖浏览器的图形渲染在 CI 环境中可以设置 headless: true 以节省资源。在本地调试时可设为 false 观察执行过程。3.3 多个项目复用配置如果你的项目有多个测试场景如桌面端 移动端可以通过 projects 分别配置export default defineConfig({ timeout: 90 * 1000, reporter: [ [list], [midscene/web/playwright-reporter, { type: merged }], ], projects: [ { name: desktop, use: { browserName: chromium, viewport: { width: 1280, height: 720 }, }, testDir: ./e2e/desktop, }, { name: mobile, use: { browserName: chromium, viewport: { width: 390, height: 844 }, isMobile: true, }, testDir: ./e2e/mobile, }, ], });四、报告器配置Midscene.js 提供了专用的 Playwright Reporter能够生成包含截图、AI 操作日志和推理过程的 HTML 可视化报告。这是 Midscene.js 测试框架模式区别于脚本模式的核心优势之一。4.1 基础配置在 playwright.config.ts 的 reporter 数组中添加reporter: [ [list], // Playwright 原生终端列表报告 [midscene/web/playwright-reporter, { // Midscene 可视化报告 type: merged, // 报告合并模式 outputFormat: single-html, // 输出格式 }], ],4.2 type 选项合并 vs 独立报告建议 日常开发使用 merged 即可一目了然在 CI/CD 中如需单独归档每个用例的报告可切换为 separate。4.3 outputFormat 选项内嵌 vs 外部资源对比分析4.4 完整配置示例将上述所有配置整合到一个完整的 playwright.config.ts 中import { defineConfig } from playwright/test; export default defineConfig({ testDir: ./e2e, timeout: 90 * 1000, expect: { timeout: 30 * 1000, }, retries: 1, workers: 1, use: { browserName: chromium, headless: true, viewport: { width: 1280, height: 720 }, }, // 报告器终端列表 Midscene 可视化报告 reporter: [ [list], [ midscene/web/playwright-reporter, { type: merged, // 合并报告 outputFormat: single-html, // 内嵌截图方便本地查看 }, ], ], });4.5 报告文件的查看测试执行完毕后终端会输出报告文件的路径Midscene - report file updated: /Users/xxx/project/midscene_run/report/some_id.html直接用浏览器打开该 HTML 文件即可查看完整的测试报告。报告内容包括测试用例概览通过/失败状态、耗时AI 操作时间线每一步 AI 操作的描述与结果截图对比每一步操作前后的页面截图AI 推理过程模型在每一步的思考日志自定义记录通过 recordToReport() 添加的自定义内容提示如果你使用了 outputFormat: html-and-external-assets需要使用 npx serve midscene_run/report 或 python -m http.server 启动一个本地 HTTP 服务来查看报告不能直接用 file:// 协议打开。4.6 报告文件清理由于报告文件包含大量截图内嵌数据单次运行可能生成数十 MB 的报告。建议在 CI 中使用 merged 模式只保留最新的一份报告或在脚本中添加清理逻辑# 运行前清理旧报告rm -rf midscene_run/report npx playwright test五、常见问题与排错5.1 Playwright 浏览器下载太慢使用国内镜像加速PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright npx playwright install chromium5.2 测试运行时截图超时报 waiting for fonts to load在 CI 或容器环境中设置环境变量export PW_TEST_SCREENSHOT_NO_FONTS_READY15.3 select 下拉框无法点击原生 select 元素的下拉选项由操作系统渲染不在页面 DOM 中。Midscene.js 默认启用 forceChromeSelectRendering 来强制 Chrome 渲染选择框。如果遇到问题可以在自定义 Fixture 中确认该选项未被关闭。5.4 AI 操作执行超时检查以下几点playwright.config.ts 中的 timeout 是否足够大建议 ≥ 90 秒AI 模型 API 是否响应正常检查 waitForNetworkIdleTimeout 和 waitForNavigationTimeout 的值是否合理查看 replanningCycleLimit 是否太小导致 AI 提前放弃总结本文详细讲解了 Midscene.js 与 Playwright 测试框架的集成方式核心要点回顾Fixture 注入通过 PlaywrightAiFixture 将 AI 能力注入测试用例使用自然语言描述操作配置文件playwright.config.ts 中设置较长的 timeout、workers: 1、推荐使用 Chromium报告器通过 midscene/web/playwright-reporter 生成可视化 HTML 报告支持合并/独立、内嵌/外置资源两种模式AI 方法aiInput、aiTap、aiWaitFor、aiQuery、aiAssert 等十余个方法覆盖了绝大多数 UI 自动化场景有了这些基础你就可以开始用自然语言编写智能化的 Playwright 测试用例了。下一篇我们将继续深入 Midscene.js 的高级玩法敬请期待
Midscene.js框架（2）：Playwright 测试套件集成
前言在上一篇文章中我们初识了 Midscene.js 这个 AI 驱动的 UI 自动化框架。本篇文章将深入讲解 Midscene.js 与 Playwright 测试套件的集成方式帮助你利用 AI 能力快速编写智能化的端到端测试用例。Midscene.js 提供了两种与 Playwright 配合使用的模式脚本模式适合快速体验、一次性数据抓取任务直接实例化 PlaywrightAgent 调用 AI 方法测试套件模式适合正式的 UI 自动化测试场景通过 Playwright 的 Fixture 机制注入 AI 能力集成方式适用场景核心类直接脚本集成快速原型、数据抓取、一次性自动化脚本PlaywrightAgent测试套件集成正式 UI 测试、CI/CD 流水线、团队协作PlaywrightAiFixture本文将重点围绕测试框架模式展开涵盖环境搭建、Fixture 注入、配置文件编写与报告器配置四大主题。一、Playwright 测试套件集成1.1环境准备首先确保项目中已安装Playwright 相关依赖npm install midscene/web playwright playwright/test --save-dev midscene/web 是 Midscene.js 的浏览器集成包提供了 Playwright Agent 与 Fixture 等核心能力。“midscene/web 是 Midscene.js 的浏览器集成包提供了 Playwright Agent 与 Fixture 等核心能力。”1.2 配置 AI 模型Midscene.js 通过环境变量来指定所使用的 AI 模型服务。在项目根目录创建 .env 文件# 模型服务地址支持 OpenAI 兼容接口 MIDSCENE_MODEL_BASE_URLhttps://api.openai.com/v1 # API Key MIDSCENE_MODEL_API_KEYsk-your-api-key # 模型名称 MIDSCENE_MODEL_NAMEgpt-4o # 模型系列如 qwen-vl-max、gpt-4o 等 MIDSCENE_MODEL_FAMILYgpt-4oMidscene.js 支持任何兼容 OpenAI 接口的模型服务包括1.3 目录结构建议一个典型的 Midscene.js Playwright 项目目录如下my-midscene-tests/ ├── .env # 环境变量模型配置 ├── playwright.config.ts # Playwright 配置文件 ├── package.json ├── e2e/ │ ├── fixture.ts # 自定义 Fixture注入 AI 能力 │ ├── ebay-search.spec.ts # 测试用例 │ └── login.spec.ts # 更多测试用例 └── midscene_run/ └── report/ # 测试报告输出目录二、Fixture 注入方式Fixture 是 Playwright 测试框架的核心机制之一。Midscene.js 通过 PlaywrightAiFixture 将 AI 能力注入到每个测试用例中让你可以像使用普通 Playwright fixture 一样调用 AI 方法。2.1 创建自定义 Fixture在 ./e2e/fixture.ts 中定义import { test as base } from playwright/test; import type { PlayWrightAiFixtureType } from midscene/web/playwright; import { PlaywrightAiFixture } from midscene/web/playwright; export const test base.extendPlayWrightAiFixtureType( PlaywrightAiFixture({ waitForNetworkIdleTimeout: 2000, // 操作后等待网络空闲的超时ms replanningCycleLimit: 30, // AI 重规划次数上限 }), );2.2 PlaywrightAiFixture() 完整配置项PlaywrightAiFixture() 接收一个可选配置对象支持所有 PlaywrightAgent 构造参数2.3 在测试用例中使用从自定义 fixture 中你可以直接解构出以下 AI 方法import { expect } from playwright/test; import { test } from ./fixture; test(搜索功能测试, async ({ ai, // 通用 Agent 实例 aiQuery, // 结构化数据查询 aiAssert, // AI 断言 aiInput, // 文本输入 aiTap, // 点击操作 aiScroll, // 页面滚动 aiWaitFor, // 等待某个条件满足 aiRightClick, // 右键点击 recordToReport, // 记录自定义内容到报告 }) { await page.goto(https://example.com); // 使用自然语言描述操作 await aiInput(无线耳机, 搜索框); await aiTap(搜索按钮); await aiWaitFor(搜索结果列表已加载出来, { timeoutMs: 5000 }); // 提取结构化数据 const items await aiQueryArray{ title: string; price: number }( 获取搜索结果中的商品标题和价格, ); console.log(搜索结果, items); expect(items?.length).toBeGreaterThan(0); // AI 断言 await aiAssert(界面左侧存在类目筛选功能); // 记录到报告 await recordToReport(搜索结果截图, { content: 耳机搜索的最终结果 }); });2.4 各 AI 方法功能速览2.5 访问底层 Agent 实例如果需要更底层的控制可以通过 agentForPage 获取原始的 PageAgent 实例test(底层 Agent 操作, async ({ agentForPage, page }) { const agent await agentForPage(page); // 执行任意 AI 操作 await agent.aiAct(点击登录按钮); // 获取内部日志 const logContent agent._unstableLogContent(); console.log(Agent 日志, logContent); // 手动记录到报告 await agent.recordToReport(); });三、playwright.config.ts 配置3.1 基础配置在项目根目录创建 playwright.config.tsimport { defineConfig } from playwright/test; export default defineConfig({ // 测试文件所在目录 testDir: ./e2e, // 单个测试用例的超时时间ms // AI 操作相比传统测试耗时更长建议设置 60-90 秒 timeout: 90 * 1000, // 全局 expect 断言超时 expect: { timeout: 30 * 1000, }, // 失败重试次数 retries: 1, // 并行执行的 worker 数量 workers: 1, // AI 测试建议设为 1避免并发冲突 // 使用 Chromium 浏览器推荐 use: { browserName: chromium, headless: true, viewport: { width: 1280, height: 720 }, // 设置 deviceScaleFactor 避免 headed 模式闪动 // deviceScaleFactor: 2, }, // 报告器配置详见第四章 reporter: [ [list], [midscene/web/playwright-reporter, { type: merged }], ], });3.2 关键配置说明timeout Midscene.js 的每次 AI 操作都需要与模型交互耗时远超传统选择器操作。建议将全局 timeout 设置为 90 * 100090 秒甚至更长避免 AI 推理过程中的误判超时。workers 由于 AI 模型 API 通常有并发限制且多个 worker 同时调用可能导致 API 限流或成本急剧上升。建议将 workers 设为 1 串行执行或者根据 API 配额谨慎设置。browserName 强烈推荐使用 chromium。Midscene.js 的部分高级能力如 CDP 协议操作在 Firefox 和 WebKit 上可能受限。headless AI 视觉模型不依赖浏览器的图形渲染在 CI 环境中可以设置 headless: true 以节省资源。在本地调试时可设为 false 观察执行过程。3.3 多个项目复用配置如果你的项目有多个测试场景如桌面端 移动端可以通过 projects 分别配置export default defineConfig({ timeout: 90 * 1000, reporter: [ [list], [midscene/web/playwright-reporter, { type: merged }], ], projects: [ { name: desktop, use: { browserName: chromium, viewport: { width: 1280, height: 720 }, }, testDir: ./e2e/desktop, }, { name: mobile, use: { browserName: chromium, viewport: { width: 390, height: 844 }, isMobile: true, }, testDir: ./e2e/mobile, }, ], });四、报告器配置Midscene.js 提供了专用的 Playwright Reporter能够生成包含截图、AI 操作日志和推理过程的 HTML 可视化报告。这是 Midscene.js 测试框架模式区别于脚本模式的核心优势之一。4.1 基础配置在 playwright.config.ts 的 reporter 数组中添加reporter: [ [list], // Playwright 原生终端列表报告 [midscene/web/playwright-reporter, { // Midscene 可视化报告 type: merged, // 报告合并模式 outputFormat: single-html, // 输出格式 }], ],4.2 type 选项合并 vs 独立报告建议 日常开发使用 merged 即可一目了然在 CI/CD 中如需单独归档每个用例的报告可切换为 separate。4.3 outputFormat 选项内嵌 vs 外部资源对比分析4.4 完整配置示例将上述所有配置整合到一个完整的 playwright.config.ts 中import { defineConfig } from playwright/test; export default defineConfig({ testDir: ./e2e, timeout: 90 * 1000, expect: { timeout: 30 * 1000, }, retries: 1, workers: 1, use: { browserName: chromium, headless: true, viewport: { width: 1280, height: 720 }, }, // 报告器终端列表 Midscene 可视化报告 reporter: [ [list], [ midscene/web/playwright-reporter, { type: merged, // 合并报告 outputFormat: single-html, // 内嵌截图方便本地查看 }, ], ], });4.5 报告文件的查看测试执行完毕后终端会输出报告文件的路径Midscene - report file updated: /Users/xxx/project/midscene_run/report/some_id.html直接用浏览器打开该 HTML 文件即可查看完整的测试报告。报告内容包括测试用例概览通过/失败状态、耗时AI 操作时间线每一步 AI 操作的描述与结果截图对比每一步操作前后的页面截图AI 推理过程模型在每一步的思考日志自定义记录通过 recordToReport() 添加的自定义内容提示如果你使用了 outputFormat: html-and-external-assets需要使用 npx serve midscene_run/report 或 python -m http.server 启动一个本地 HTTP 服务来查看报告不能直接用 file:// 协议打开。4.6 报告文件清理由于报告文件包含大量截图内嵌数据单次运行可能生成数十 MB 的报告。建议在 CI 中使用 merged 模式只保留最新的一份报告或在脚本中添加清理逻辑# 运行前清理旧报告rm -rf midscene_run/report npx playwright test五、常见问题与排错5.1 Playwright 浏览器下载太慢使用国内镜像加速PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright npx playwright install chromium5.2 测试运行时截图超时报 waiting for fonts to load在 CI 或容器环境中设置环境变量export PW_TEST_SCREENSHOT_NO_FONTS_READY15.3 select 下拉框无法点击原生 select 元素的下拉选项由操作系统渲染不在页面 DOM 中。Midscene.js 默认启用 forceChromeSelectRendering 来强制 Chrome 渲染选择框。如果遇到问题可以在自定义 Fixture 中确认该选项未被关闭。5.4 AI 操作执行超时检查以下几点playwright.config.ts 中的 timeout 是否足够大建议 ≥ 90 秒AI 模型 API 是否响应正常检查 waitForNetworkIdleTimeout 和 waitForNavigationTimeout 的值是否合理查看 replanningCycleLimit 是否太小导致 AI 提前放弃总结本文详细讲解了 Midscene.js 与 Playwright 测试框架的集成方式核心要点回顾Fixture 注入通过 PlaywrightAiFixture 将 AI 能力注入测试用例使用自然语言描述操作配置文件playwright.config.ts 中设置较长的 timeout、workers: 1、推荐使用 Chromium报告器通过 midscene/web/playwright-reporter 生成可视化 HTML 报告支持合并/独立、内嵌/外置资源两种模式AI 方法aiInput、aiTap、aiWaitFor、aiQuery、aiAssert 等十余个方法覆盖了绝大多数 UI 自动化场景有了这些基础你就可以开始用自然语言编写智能化的 Playwright 测试用例了。下一篇我们将继续深入 Midscene.js 的高级玩法敬请期待
