<p>data-test-* 属性必须挂载在 <html> 或 <body> 上，不能写在 <head> 里；应统一用 data-test- 前缀、语义化值命名，优先用 CSS 属性选择器定位，并在 CI/CD 中校验缺失与重复。</p>
data-test-* 属性必须挂载在 或 上，不能写在 里
写了也白写——浏览器解析时直接忽略，document.head.dataset 读不到，getAttribute() 返回 null。根本原因是 HTML 规范只允许 <head> 包含 <title>、<meta>、<link> 等特定标签，data-* 不在其白名单中。
常见翻车现场：
- 服务端模板往
<head data-env="staging">里注入环境标识 → 前端测试脚本初始化失败 - 自动化框架依赖
data-test-user-id做登录态校验 → 实际运行时取值为空，全走默认逻辑
正确做法：统一挂到 <html> 标签上，它解析最早、永不被重写，且 document.documentElement.dataset 可在任意时机安全读取。
命名要稳定、可读、无歧义，避免和业务逻辑属性混用
data-test-id、data-test-button="submit" 这类命名是推荐的；而 data-id、data-name 或直接复用 id 属性就容易出问题——前者可能被后端模板或 JS 框架动态覆盖，后者常因组件复用、循环渲染导致重复或不可控。
立即学习“前端免费学习笔记（深入）”；
关键原则：
- 前缀固定为
data-test-，明确标识用途，与data-user-、data-config-隔离 - 值尽量语义化，如
data-test-section="api-docs"，别用data-test-id="123" - 禁止用动态生成的 hash、timestamp、随机数作值，否则每次构建都变，定位脚本失效
定位时优先用 CSS 选择器匹配 data-test-*，而非 XPath
用 document.querySelector('[data-test-button="confirm"]') 比 //button[@data-test-button='confirm'] 更快、更轻量、兼容性更好。Selenium、Playwright、Cypress 都原生支持属性选择器，且现代浏览器对 [attr="val"] 的查询做了深度优化。
注意几个实际坑点：
- CSS 选择器不区分大小写，但属性值区分：
data-test-type="Modal"和data-test-type="modal"是两个不同值 - 含空格或特殊字符的值必须加引号：
[data-test-label="Save changes"]，漏引号会解析失败 - 不要嵌套太深：
div[data-test-container] button[data-test-action]容易因 DOM 结构微调而断裂，单层定位更稳
CI/CD 中需校验 data-test-* 是否缺失或重复
上线前跑一次静态检查，能拦住大量低级错误。比如用 ESLint + custom rule 或 HTMLHint 扫描：
- 所有
button、a、input[type="submit"]必须有data-test-* - 同一页面内
data-test-id值不可重复（可用document.querySelectorAll('[data-test-id]').length快速验证） - 禁止出现
data-test-开头但无后续内容的属性（如data-test-），那是拼写错误
真正难的不是加属性，而是让团队长期坚持——把它变成 PR 合并前的必过门禁，比写文档管用得多。
