关于 playwright-frontend
面向前端工程师的 Playwright 标记指南，帮助构建稳定、可机器识别的 DOM 定位约定。它先强调语义化和可访问标记，再在必要时使用稳定且唯一的 data-testid。
主要功能
- 01制定 data-testid 命名约定
- 02优先使用语义化 HTML 和可访问名称
- 03确保测试 ID 唯一且稳定
- 04为列表项使用稳定领域键
- 05统一使用 data-testid 属性
适用场景
- 01为自动化测试设计 DOM 定位方式
- 02为自定义控件添加稳定测试标识
- 03降低本地化或样式变更造成的测试脆弱性
- 04在 React、Vue、Angular 或 Svelte 中规范测试 ID
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/playwright-frontend确认已加载。
附带文件data-testid-conventions.mdexamples.md
详细介绍
Playwright 前端（编写可定位标记）
目标读者：编写应用的前端工程师——与
core/中面向测试编写者的指南相对应。你要做的是在 DOM 上提供一份小巧、稳定、机器可读的契约，让测试和 AI Agent 都能确定性地定位元素，避免不稳定问题。
data-testid 是 UI 自动化层的公共 API：一旦测试或 Agent 依赖它，重命名就会成为破坏性变更。先编写无障碍标记，然后在自动化需要持久定位依据的地方，有意识地添加命名清晰、唯一且稳定的测试 ID。
指南索引
| 主题 | 指南 |
|---|---|
data-testid 约定（使用时机、命名、唯一性、稳定性） | data-testid-conventions.md |
| 框架模式（React、Vue、Angular、Svelte）+ 集中管理 ID + 生产环境移除 | examples.md |
黄金规则
- 优先使用语义化 HTML — 为元素提供真实的角色、标签或无障碍名称，以便
getByRole/getByLabel能够正常工作；然后再添加测试 ID。 - 仅在角色、标签和文本不够用时添加
data-testid— 例如没有角色的自定义控件、范围容器、列表行，以及动态或本地化区域。若getByRole已能唯一定位某个控件，就不需要添加。 - 命名时确保全局唯一 —
feature-component-element[-variant]，使用kebab-case。 - 列表项使用稳定的领域键作为后缀，绝不使用数组索引 —
user-row-${user.id}✅ /user-row-${index}❌。 - 让值与文本、区域设置、样式和 DOM 位置解耦 — 这些都可能变化，测试 ID 则不应改变。
- 统一使用一种属性 —
data-testid是 Playwright 默认的testIdAttribute；不要混用data-test/data-qa。
相关内容
- core/locators.md / core/locator-strategy.md — 面向使用者的内容：编写测试时如何选择定位器。
- Playwright 官方文档：定位器、最佳实践。
评论
支持 Markdown