data-test-id比id/class更适合作为定位依据，因其专为测试设计、不参与样式或逻辑，前端改版时几乎不变；而id常被框架动态生成，class则随UI高频变更。
data-test-id 为什么比 id/class 更适合作为定位依据
因为 data-test-id 是专为测试存在的属性，不参与样式、逻辑或渲染，前端改版时几乎不会动它；而 id 常被框架动态生成（如 email-input-abc123），class 则随 UI 改版高频变更（如从 form-input 变成 input-v2）。命名必须聚焦功能意图，比如 data-test-id="login-password-input"，而不是视觉描述（"blue-submit-btn"）。
注意几个坑：
- 在 React/Vue 列表中重复使用时，必须结合唯一 key：
data-test-id={`product-card-${item.id}`} - SSR 水合后可能丢失该属性：Next.js 14+ 默认保留，Nuxt 3 需显式配置
ssr-identifiers - 不能加在父容器上就以为万事大吉——目标是输入框，
data-test-id就得落在<input>自身，不是外层<div>
CSS 选择器怎么写才不容易翻车
cssSelector 性能好、可读性强，但写法稍有不慎就脆。优先用属性组合，比如 [data-test-id="search-input"] 或 button[type="submit"][data-test-id]；避免依赖层级深度，像 div > form > div > input 这种一加个中间容器就失效。
常见错误场景：
立即学习“前端免费学习笔记（深入）”；
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
- 硬写多值 class：
.input-error匹配失败，因为实际 class 是"input error focus"——应改用属性匹配[class*="error"]或直接换input[name="email"] - 用
input标签名全局匹配，结果选中了页脚的隐藏 input ——必须加上下文限定，如form#login-form input[name="password"] - 误信浏览器开发者工具里“Copy selector”生成的路径，它常含伪类或动态类名，复制即失效
XPath 什么时候该用、怎么写才稳
XPath 不是原罪，错的是写法。绝对路径 /html/body/div[2]/section/div/input 一改结构就崩，因为它在数第几个 div，而不是找“登录邮箱输入框”。真正稳定的写法是靠属性和语义：
- 用相对路径 + 属性条件：
//input[@name="email" and @type="text"] - 文本匹配必须加
normalize-space()处理空白：//button[normalize-space(text())="提交"] - 禁用轴操作：
following-sibling、parent::这类隐含结构假设的写法，前端重构时极易断裂 - 慎用
//全局搜索——性能差且易命中非目标节点；先缩小范围：//form[@data-testid="login-form"]//input[@name="password"]
定位失败时，先查什么、再做什么
报 NoSuchElementException 或 StaleElementReferenceException 不是终点，而是线索入口。第一步永远是在 DevTools 控制台执行 document.querySelector('[data-test-id="xxx"]')，看返回是不是 null。
接下来按顺序排查：
- 元素是否在 Shadow DOM 内？如果是，
data-test-id必须写在 shadow root 内部节点上，挂在外层容器无效 - 是否已渲染但不可见？
display: none或visibility: hidden下，cy.getByTestId("xxx")默认不等待可见，需显式加.should("be.visible") - 是否动态加载？AJAX 渲染的元素，不能靠
presence_of_element_located就完事——要根据操作选对等待条件：element_to_be_clickable才保证可交互 - SSR 水合后属性是否还在？尤其 Vue/Nuxt 项目，得确认服务端注入的
data-test-id是否被 hydration 抹掉
最常被忽略的一点：定位器本身没问题，但元素还没“活”过来——比如 React 中某个 input 的 data-test-id 在组件 mount 后才挂载，此时任何查找都为空。得配合框架生命周期或自定义事件做等待，而不是只盯着选择器。
