#剧作家 ## 概述 Playwright 是一个适用于 Node.js 和 Python 的浏览器自动化框架，通过单个 API 支持 Chromium、Firefox 和 WebKit。它提供自动等待、Web 优先断言和完整的测试隔离，以实现可靠的端到端测试。 **何时使用：** 浏览器自动化、网页抓取、屏幕截图/PDF 生成、API 测试、配置 Playwright 测试、排除 Playwright 错误、隐身模式和反机器人绕过。 **何时不使用：** 简单的 HTTP 请求（使用 `fetch`）、单元测试（使用 Vitest/Jest）、大规模无服务器抓取（考虑 Cloudflare 浏览器渲染）。对于 E2E 测试架构（页面对象模型、CI 分片、测试组织、身份验证模式），请使用“e2e-testing”技能。 ## 快速参考图案| API / 配置 |要点 ---|---|--- 基础测试| `test('name', async ({ page }) => {})` |自动等待、Web 优先断言、测试隔离定位器| `page.getByRole()` / `page.locator()` |与 CSS 相比，更喜欢角色/标签/文本选择器断言| `expect(定位器).toBeVisible()` |自动重试，可配置超时 API测试| `request` 固定装置 / `apiRequestContext` |发送 HTTP 请求，验证响应咏叹调快照 | `expect(定位器).toMatchAriaSnapshot()` |通过 YAML 验证可访问性树结构类断言 | `expect(locator).toContainClass('active')` |匹配各个 CSS 类名称 (v1.52+) 可见光滤镜| `locator.filter({visible: true })` |仅匹配可见元素 (v1.51+) 测试步骤| `test.step('name', async (step) => {})` |超时、跳过和附件 (v1.50+) 隐身模式 | `playwright-extra` \+ 隐形插件 |修补 20 多个检测向量经过身份验证的会话 | `context.cookies()` \+ `addCookies()` |保存/恢复 cookie 和 IndexedDB 以实现持久性截图| `page.screenshot({ fullPage: true })` |等待关键元素首先加载 PDF 生成 | `page.pdf({ 格式: 'A4' })` |仅限 Chromium，设置 `printBackground: true` 时钟API | `页面.时钟` |在测试中冻结、快进或模拟时间 A11y断言| `toHaveAccessibleName`、`toHaveRole` |没有 axe-core 依赖的本机断言视口断言 | `expect(定位器).toBeInViewport()` |断言元素位于可见视口内仅更改测试 | `--only-changed=$GITHUB_BASE_REF` |仅运行自基本分支以来更改的测试文件码头工人 | `mcr.microsoft.com/playwright:v1.58.2-noble` |使用 `--init --ipc=host` 标志调试方法| `page.consoleMessages()` / `page.requests()` (v1.56+) |不需要事件侦听器加速板| HTML 报告器 (v1.57+) |识别缓慢的测试和瓶颈剧作家经纪人| `npx 剧作家 init-agents` | LLM 驱动测试的规划器、生成器、治疗器片状测试检测| `--fail-on-flaky-tests` (v1.50+) | CI 中不稳定测试的退出代码 1 修改实时回复 | `route.fetch()` \+ `route.fulfill()` |拦截真实响应，调整 JSON，返回它软断言| `expect.soft(定位器)` |不要因失败而停止测试，最后报告所有内容重试块 | `expect(async () => {}).toPass()` |默认超时为 0（永远）— 始终设置为 1 定制匹配器 | `expect.extend()` / `mergeExpects()` |定义或组合自定义断言方法可操作性矩阵 |每个操作自动等待检查 |单击：全部 5 个检查，填充：3，焦点/模糊：无测试修饰符| `test.fixme()` / `test.fail()` / `test.slow()` | fixme=跳过+跟踪，fail=断言失败，slow=3x 并行模式 | `test.describe.configure({ mode: 'serial' })` |串行、并行或默认的每个描述块拆解项目|安装项目上的“teardown”选项 |所有依赖项完成后自动清理 ## 常见错误错误|正确的模式 ---|--- 使用 CSS 选择器而不是角色选择器 |优先选择 `getByRole`、`getByLabel`、`getByText` 以获得弹性不关闭浏览器 |始终在“finally”块中“await browser.close()” 使用 `setTimeout` 进行等待 |使用定位器自动等待或“waitForLoadState” CI 代码中留下 `page.pause()` |使用“if (!process.env.CI)”进行防护 — 无限期地挂起 CI 点击无需等待 |使用具有内置自动等待功能的“locator().click()” 测试之间共享状态 |每个测试都通过固定装置获得新鲜的背景测试实施细节|断言用户可见的行为，而不是 DOM 结构硬编码等待动态内容|等待选择器出现或内容稳定断言中缺少 `await` |所有“expect()”断言返回承诺——必须等待所有抓取均使用相同的用户代理 |轮换用户代理以进行大量抓取使用“setTimeout”进行时间相关测试 |使用“page.clock” API 冻结/快进时间安装 axe-core 进行简单的 a11y 检查 |使用本机 `toHaveAccessibleName`/`toHaveRole` 断言在没有明确超时的情况下使用“toPass()” |始终传递 `{ timeout: 10_000 }` — 默认值为 0（永远） Service Worker 默默地阻止 `page.route()` |使用 MSW 时在上下文配置中设置 `serviceWorkers: 'block'` 使用“fill()”进行自动完成/反跳输入 |使用带有可选延迟的“pressSequentially()”来进行每次击键处理 `storageState` 丢失 sessionStorage | `storageState` 只保存 cookies + localStorage — 通过 `addInitScript()` 注入 sessionStorage ## 代表团 * **选择器故障排除**：使用 `Explore` 代理 * **测试模式审查** ：使用 `Task` 代理 * **代码审查** ：委托给 `code-reviewer` 代理 > 对于 E2E 测试架构、页面对象模型模式、CI 分片策略、身份验证流程、视觉回归工作流程或测试组织，请使用“e2e 测试”技能。＃＃参考 * [快速启动和安装]() * [E2E 测试模式和断言]() * [选择器策略和最佳实践]() * [配置和Docker部署]() * [Docker 和 CI]() * [调试方法及性能分析]() * [常见自动化模式]() * [隐身模式和反机器人绕过]() * [已知问题及解决方案]() * [特定站点的阻止和绕过]() * [常见问题排查]() * [网络测试、模拟和 API 模式]() * [输入模式、可操作性和测试修饰符]() * [高级断言、轮询、自定义匹配器和注释]() * [高级主题：MCP、AI 代理、并行上下文]()

剧作家

包含技能