用途：面向编写应用的前端工程师，与核心目录中面向测试作者的指南相对。目标是在 DOM 上暴露一个小而稳定、机器可读的契约，让测试与 AI 智能体能够确定性地定位元素，避免不稳定。
核心观念：data-testid 是 UI 自动化层的公共 API；一旦测试或智能体依赖它，重命名就是破坏性变更。应优先构建可访问的标记，然后在自动化需要持久句柄的地方，添加经过深思熟虑、命名良好、唯一且稳定的测试 ID。
黄金规则：
- 语义化 HTML 优先——为元素提供真实的 role/label/可访问名称，使 getByRole/getByLabel 可用，然后再添加测试 ID。
- 仅在 role、label、文本不足以定位时才加 data-testid——无 role 的自定义组件、作用域容器、列表行、动态或本地化区域。getByRole 已能唯一定位的控件无需添加。
- 命名以全局唯一为目标——feature-component-element[-variant]，使用 kebab-case。
- 列表中用稳定的领域键作后缀，绝不用数组索引——user-row-${user.id} 可行，user-row-${index} 不可行。
- 将取值与文本、语言环境、样式和 DOM 位置解耦，这些会变化，测试 ID 不应随之改变。
- 统一使用一个属性——data-testid 是 Playwright 默认的 testIdAttribute，不要混用 data-test/data-qa。
涵盖主题：data-testid 约定（何时使用、命名、唯一性、稳定性）；框架模式（React、Vue、Angular、Svelte）、集中管理 ID 与生产环境剥离。
相关：core/locators.md 与 core/locator-strategy.md 为消费侧资料，讲解编写测试时如何选择定位器；官方文档见 Playwright 的 Locators 与 Best Practices。
限制：资料未提供具体安装命令、完整代码示例、价格或平台信息，暂未提供。