data-test-id 是自动化测试最稳妥的标记方式，应聚焦功能意图命名、避免重复、禁用 aria-label/title 定位，并注意 ssr 水合后属性丢失问题。
data-test-id 属性是目前最稳妥的标记方式
自动化测试脚本（尤其是 Playwright、Cypress 或 Selenium）需要稳定、语义无关的选择器，data-test-id 是行业事实标准。它不参与样式或交互逻辑，也不会被业务代码误删或动态修改，比用 id 或 class 更可靠。
常见错误是把测试 ID 和 UI 文本强绑定，比如写成 data-test-id="submit-button" —— 一旦按钮文案改成“确认提交”，这个属性就失去可读性但又不敢删，反而造成维护混乱。
- 命名应聚焦功能意图，而非视觉表现：
data-test-id="checkout-form-submit"比data-test-id="blue-button"更可持续 - 避免在循环渲染中生成重复值：React/Vue 列表项必须结合唯一 key，如
data-test-id={`product-card-${item.id}`} - 构建时可通过 ESLint 插件（如
eslint-plugin-testing-library）校验是否遗漏关键交互元素的标记
为什么不能用 aria-label 或 title 做测试定位
aria-label 和 title 属于可访问性/用户体验属性，内容会随本地化语言切换而变化，且可能被 JS 动态覆盖。测试脚本一旦依赖它们，CI 环境里切了中文 locale 就直接报 Element not found。
更隐蔽的问题是：某些组件库（如 Ant Design、MUI）会自动注入 title，导致多个元素撞车；而 aria-label 在无文本节点的图标按钮中常由父级逻辑拼接生成，不具备静态可预测性。
- 实操建议：把
aria-label仅用于屏幕阅读器支持，测试定位一律走data-test-id - 若需复用文案做断言（如“验证按钮显示‘保存草稿’”），应单独用
textContent或innerText断言，而非靠属性定位
Cypress 中 queryByTestId 的底层其实是 CSS 属性选择器
Cypress 的 cy.getByTestId()（需启用 cypress-testing-library 插件）本质是封装了 [data-test-id="xxx"] 这类 CSS 选择器。这意味着它的行为完全受 CSS 优先级和 DOM 可见性规则约束——不是“魔法定位”。
典型翻车场景：元素被 display: none 或 visibility: hidden 隐藏时，cy.getByTestId("xxx") 默认不重试等待，直接失败；而原生 cy.get('[data-test-id="xxx"]') 同样如此，区别只在语法糖层面。
- 必须配合显式等待：用
cy.getByTestId("xxx").should("be.visible")而非假设自动等待 - 若元素在 Shadow DOM 内，
data-test-id必须写在 shadow root 内部节点上，外部容器加无效 - 避免嵌套过深的选择器链，如
cy.getByTestId("form").find("[data-test-id='input']")—— 直接给 input 加独立data-test-id更稳
Playwright 的 getByRole + name 组合有时比 data-test-id 更健壮
对按钮、链接、输入框等有明确语义的元素，Playwright 推荐优先用 getByRole("button", { name: "提交" })。这不是替代 data-test-id，而是互补：前者验证可访问性实现是否正确，后者保障定位稳定性。
问题在于，name 匹配默认是模糊匹配（含子串），且大小写敏感。如果按钮实际文本是“提交订单”，但测试写成 { name: "提交" }，看似能过，但后续文案微调（如变成“立即提交”）就会断裂。
- 生产环境建议：用
getByRole("button", { name: /^提交订单$/ })强制全字精确匹配 - 当组件使用图标+文字混合布局时，
name可能取不到预期值，此时退回到getByTestId()是合理选择 - 注意：
getByRole不适用于自定义 div 模拟的控件，必须确保有正确的role和aria-*属性，否则查无此元素
data-test-id 在服务端渲染（SSR）和客户端水合（hydration）过程中的时机差——服务端吐出的 HTML 有该属性，但 JS 激活后某些框架会清空或重写整个 DOM 节点，导致属性丢失。这种情况不会报错，但测试脚本会静默找不到元素。务必在 hydrate 完成后检查 DOM 是否仍存在对应 data-test-id。前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
