SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场e2e-playwright-testing

e2e-playwright-testing

测试与质量

查看项目

更新于 10-14 05:32

技能介绍

用途

E2E Playwright Testing 提供可靠端到端浏览器测试的模式与约定，适用于撰写或审查 Playwright E2E 测试、为新项目搭建 E2E 测试、调试不稳定的浏览器测试，以及测试表单提交、认证流程与用户交互等场景。

栈检测

在编写或审查 E2E 测试前，先检测项目技术栈：

  • 检测 Playwright：检查 package.json 的 devDependencies 中是否存在 "@playwright/test"，并查看 playwright.config.js 或 playwright.config.ts。存在则使用本技能的 Playwright 模式；若存在 cypress，则本技能不适用。
  • 检测前端框架：检查 package.json 依赖，如 "react" + "@inertiajs/react"、"react" + "react-router"、"vue"、"next" 等。原因包括：React + Inertia.js 应使用 waitForURL 而非 waitForLoadState('networkidle')（Inertia 使用 history.pushState）；React 受控输入中 fill() 适用于文本，日期/时间需要 keyboard.type()；SPA 导航不会整页刷新，断言需等待内容而非网络空闲。
  • 检测认证模式：区分基于会话（如 Laravel Sanctum）或基于令牌（JWT）。会话用 storageState 保存 cookie；令牌可能需保存到 localStorage。
  • 检测限流：检查路由是否有 throttle 中间件。若开发环境存在，约 5 次登录尝试后会遇到 429。解决方案：仅生产环境限流，或在测试环境提高限制。

规则类别与优先级

  • 定位器（CRITICAL，前缀 loc）：loc-prefer-role-locators（优先 getByRole/getByLabel 而非 CSS 选择器）；loc-strict-mode（用 exact/first/scoped 处理严格模式违规）。
  • 认证（CRITICAL，前缀 auth）：auth-storage-state（通过 setup 项目模式复用登录状态）。
  • 断言（HIGH，前缀 assert）：assert-web-first（使用自动重试的 expect(locator) 断言）。
  • 表单与输入（HIGH，前缀 form）：form-react-date-inputs（React 应用中日期/时间使用 keyboard.type()）；form-custom-checkboxes（处理 sr-only 复选框组件）。
  • 测试组织（MEDIUM，前缀 org）：org-mirror-routes（目录结构镜像路由分组）。
  • 可靠性（MEDIUM，前缀 rel）：rel-no-wait-for-timeout（绝不使用任意 waitForTimeout）。

关键模式

定位器优先级：1）Role，最佳，映射无障碍语义，如 page.getByRole('button', { name: 'Submit' })、page.getByRole('tab', { name: 'Network' })、page.getByRole('heading', { name: 'Dashboard' })；2）Label，用于表单字段，如 page.getByLabel('Email')；3）Text，用于静态内容，歧义时使用 exact，如 page.getByText('Welcome', { exact: true })；4）ID，用于缺少合适标签的输入，如 page.locator('#password')；最后才用 CSS 选择器，如 page.locator('button.submit-btn')。

认证 setup 模式：setup 项目按角色登录一次，所有测试复用该状态（90+ 测试只需 3 次登录而非 90 次）。测试文件中使用 test.use({ role: 'customer' })，并在测试里通过 authedPage 访问页面。

React 日期输入陷阱：fill() 不会为日期/时间输入触发 React onChange，应改用 keyboard.type()，例如先点击日期输入再 keyboard.type('16042026')（DDMMYYYY），时间输入 keyboard.type('1000AM')。

严格模式修复：getByRole('button', { name: 'Verified' }) 会同时匹配 "Verified" 与 "Unverified"，应加 exact: true；getByText('POS Demo') 会匹配标题与面包屑，应用 Role 消歧，如 getByRole('heading', { name: 'POS Demo' })。

并行决策：Playwright 默认 fullyParallel: true，适用于测试相互独立、各自创建数据的场景；当测试共享带可变状态的种子数据库时，应改为 workers: 1，否则一个测试的购买事务会改变另一个测试预期的余额。

配置模板

配置示例包含：testDir 为 './specs'；fullyParallel 与 workers 按共享状态决定；forbidOnly 在 CI 下启用；retries 在 CI 下为 2，否则 0；reporter 使用 html 与 list；use 中设置 baseURL（默认 http://localhost:8000）、trace: 'on-first-retry'、screenshot: 'only-on-failure'、video: 'retain-on-failure'；projects 包含 auth-setup、chrome（Desktop Chrome，依赖 auth-setup）与 mobile（iPhone 14，依赖 auth-setup，testMatch 为 /responsive/）。

元数据与参考

版本 1.0.0，共 6 个类别 8 条规则，许可证 MIT。参考资料包括 Playwright 文档、最佳实践、定位器指南、认证指南、测试断言、自动等待，以及完整编译文档 AGENTS.md。

限制

本技能仅适用于使用 @playwright/test 的项目；若项目使用 Cypress 则不适用。其他未在资料中说明的适用条件、平台支持或收费信息暂未提供。