在 TypeScript/JavaScript 项目中进行…

适用于使用 Playwright 编写 TS/JS E2E 测试，并希望测试稳定、可维护、可并行执行的场景。

适用场景

解决思路

1. 用简洁、技术化的 TypeScript/JavaScript 编写测试，并提供准确的类型定义。
2. 测试命名：使用描述性名称，清楚表达预期行为。
3. Fixtures 与隔离：使用 Playwright fixtures（`test`、`page`、`expect`）保证测试隔离和一致性。
4. Setup/Teardown：使用 `test.beforeEach` 和 `test.afterEach` 管理干净状态。
5. DRY 原则：把可复用逻辑抽取到 helper 函数，避免重复。
6. 定位器：优先使用基于角色的定位器（`page.getByRole`、`page.getByLabel`、`page.getByText`），而不是复杂选择器；当存在 `data-testid` 属性时使用 `page.getByTestId`。
7. 配置：利用 `playwright.config.ts` 做全局设置和环境配置。
8. 错误处理：实现合理的错误处理，并提供清晰的失败信息。
9. 跨浏览器测试：用 projects 覆盖多个浏览器/设备；优先使用内置配置对象如 `devices`。
10. 断言：优先使用 web-first assertions（`toBeVisible`、`toHaveText`）和 `expect` matchers，而不是 `assert` 语句。
11. 时序：避免硬编码超时；使用 `page.waitFor` 等待特定条件。
12. 并行化：确保测试可并行可靠运行，且没有共享状态冲突。
13. 文档：为 helper 函数添加 JSDoc 注释；避免行内代码注释。
14. 聚焦：针对关键用户路径编写稳定、可维护、反映真实行为的测试。
15. 参考官方文档：遵循 https://playwright.dev/docs/writing-tests 的指导。
16. 示例结构：使用 `import { test, expect } from '@playwright/test';`，用 `test.describe` 分组，在 `test.beforeEach` 中 `await page.goto('/feature-url')`，在 `test` 中按 Arrange/Act/Assert 组织，如 `page.getByRole('button', { name: 'Submit' })` 点击后 `await expect(page.getByText('Success')).toBeVisible()`。

适用边界 · 注意事项

• 非 TypeScript/JavaScript 项目或非 Playwright 测试栈不适用。
• 无浏览器、无法运行 Playwright 的环境（如仅纯 Node.js 单元测试、非 Web 应用）不适用。
• 不应把 E2E 测试用于替代大量单元测试或仅验证内部实现细节的场景。