data-test-id比id/class更适合作为定位依据，因其专为测试设计、不参与渲染与样式、命名聚焦功能意图且支持唯一性扩展，能有效解耦测试代码与DOM结构演化。
HTML结构本身不是“不稳定”的根源，而是前端迭代中定位策略与DOM演化节奏不匹配的体现。真正需要治理的，不是HTML，而是测试代码对HTML的依赖方式。
为什么data-test-id比id/class更适合作为定位依据
前端开发中，id常被用于JS逻辑或样式控制，class随UI改版高频变动；而data-test-id是专为测试存在的语义标记，不参与渲染、不绑定样式、不触发行为——它唯一的作用就是让测试脚本能稳定找到目标元素。
- 命名必须聚焦功能意图，例如
data-test-id="checkout-form-submit"，而非视觉描述（如"blue-button"） - 避免在列表渲染中重复：React/Vue中应结合唯一key，写成
data-test-id={`product-card-${item.id}`} - SSR水合后属性可能丢失，需确认框架是否保留该属性（Next.js 14+默认保留，Nuxt 3需显式配置）
- 不要用
aria-label或title替代——它们会随语言切换、JS动态注入而变化，CI环境切locale就失效
CSS选择器和XPath该怎么选、怎么写才不翻车
CSS选择器性能更好、可读性更强，XPath表达力更足但易写成“脆路径”。关键不在工具，而在写法逻辑。
- CSS优先用属性组合：
[data-test-id="login-input"]或button[type="submit"][data-test-id]，避免依赖层级深度 - XPath禁用绝对路径：
/html/body/div[2]/form/input—— 页面微调即崩；改用相对+属性定位：//input[@name="email" and @type="text"] - 慎用文本匹配：
//button[contains(text(), "提交")]在多语言或文案微调时失效；若必须用，应配合normalize-space()处理空白 - 避免轴操作（如
following-sibling），这类写法隐含结构假设，前端重构时极易断裂
定位失败时，先查什么、再做什么
报NoSuchElementException或StaleElementReferenceException不是终点，而是线索入口。
立即学习“前端免费学习笔记（深入）”；
- 先确认元素是否真实存在：用浏览器DevTools执行
document.querySelector('[data-test-id="xxx"]')，看返回是否为null - 检查是否在Shadow DOM内：若元素在
#shadow-root下，data-test-id必须写在shadow内部节点上，父容器加无效 - 确认可见性状态：元素可能已渲染但
display: none或visibility: hidden，此时cy.getByTestId("xxx")默认不等待可见，需显式加.should("be.visible") - 排查动态加载：元素由AJAX或React.lazy引入，需配合显式等待，而非
time.sleep()硬等待
稳定性治理最难的部分，不是写对一个XPath，而是让整个团队把data-test-id当成接口契约来维护——它一旦写进组件，就意味着“这个元素的业务角色已定义”，后续任何UI调整都不能破坏它。否则，再多的重试、等待、POM封装，都只是给裂缝贴胶带。
