索引 data-testid 与 ARIA 属性：解决 AI 测试幻觉的新思路

AI 编码代理生成集成测试和端到端测试，是目前开发者工作流中回报率最高的用法之一。但代理在一个具体环节上反复翻车：猜测 DOM 元素选择器。

典型失败场景是这样的——代理写出 await page.click(".btn-primary-submit")，然后测试挂掉，因为这个 class 名根本不存在。它不是逻辑错了，而是「看」不到前端的真实结构，只能靠猜。TokenCap 给出的解法是：把前端的测试定位契约事先抽取出来，喂给代理，而不是让它盲猜。

问题根源：代理在盲猜选择器

AI 代理生成测试时，最脆弱的一环不是断言逻辑，而是如何定位页面上的元素。开发者写测试时脑子里有组件结构，知道哪个按钮有 data-testid，哪个下拉框有 role="combobox"。代理没有这层上下文。

它能看到的往往只是零散的代码片段或模糊的页面描述，于是退回到最原始的策略：拼一个看起来合理的 CSS 选择器。class 名、层级路径、标签组合，全靠语言模型的先验。这类选择器即便偶尔命中，也极其脆弱——前端一次样式重构就能让整套测试崩掉，而且崩的原因和业务逻辑毫无关系。

TokenCap 的做法是把这件事从「猜」变成「查」：解析 JSX AST 节点，把显式的测试属性提取出来，集中索引。

JSX AST：JSX 是 React 中用来描述 UI 结构的语法扩展，浏览器无法直接执行，需要先被编译成普通的 JavaScript 函数调用。抽象语法树（AST）是源码经过词法和语法分析后形成的树状结构，每个节点对应代码中的一个语法单元，比如一个 JSX 元素、一个属性、一段文本。与直接读取渲染后的 HTML 不同，AST 保留源码的行号、属性名和嵌套关系，因此可以精确定位「第 68 行那个 <select> 上的 role 属性是什么」。这正是 TokenCap 能稳定抽取定位属性的基础——它处理的是结构化的源码，而不是充满运行时噪声的页面快照。

ARIA：全称 Accessible Rich Internet Applications，是一套由 W3C 制定的属性规范，用来给屏幕阅读器等辅助技术描述元素的语义和状态。诸如 role="dialog"、aria-label="关闭" 这类属性，让原本只是 <div> 的元素获得可被程序理解的角色和名称。测试框架（如 Playwright 的 getByRole）正是借助这层语义来定位元素，因此基于 ARIA 的定位器在样式重构时依然有效，同时也间接驱动了产品的可访问性质量。

TokenCap 索引了什么

TokenCap 在 src/frontend/testIds.js 中定义并提取以下几类属性：

1. 测试标识符：data-testid、data-test、data-cy
2. 无障碍角色：role="button"、role="navigation"、role="dialog"
3. 屏幕阅读器标签：aria-label、aria-labelledby、aria-describedby
4. 表单关联：htmlFor 与 input id 的配对关系

这四类覆盖了现代前端测试定位的主要手段。特别值得一提的是表单关联这一项——htmlFor 和 id 的配对在 JSX 里是分散的，代理很难靠上下文推断出「这个 label 对应哪个输入框」，但 AST 解析可以精确捕获这层绑定关系。

把 ARIA 属性和测试标识符放在同一份索引里，还有一个额外好处：它天然引导代理使用无障碍最佳实践。getByRole("combobox", { name: "Billing Tier" }) 这类定位方式，既比 CSS 路径稳定，又顺带验证了组件的可访问性。

htmlFor 与 id 配对：在 HTML 和 JSX 中，<label htmlFor="email">邮箱</label> 与 <input id="email" /> 通过 htmlFor（对应 HTML 的 for 属性）和 id 建立关联，点击标签即可聚焦输入框，屏幕阅读器也会把标签文本念给用户听。但这层绑定跨越了两个可能相距很远的元素，语言模型仅凭零散上下文很难可靠推断「这个 label 到底对应哪个 input」。AST 解析可以遍历同一作用域内的节点，把这种配对关系精确提取出来，从而让代理用 getByLabel("邮箱") 这类稳定定位器，而不是猜测输入框的 class 名。

快照机制：让代理「看到」定位契约

索引本身不会自动帮到代理，关键在于怎么把它交到代理手里。TokenCap 通过 tokencap make 命令生成组件快照，把测试定位契约直接写进前端组件的描述里：

### Component: UserBillingForm (src/components/UserBillingForm.jsx)
Testing Selectors:
  - Submit Button: `getByTestId("billing-submit-button")` (line 42)
  - Plan Selector: `getByRole("combobox", { name: "Billing Tier" })` (line 68)
  - Card Input: `getByTestId("card-element-input")` (line 95)

这份快照的信息密度值得注意：每个定位器都带了行号，代理可以顺着行号回到源码确认上下文；定位方式统一采用 Playwright 的 getByTestId / getByRole 风格，而不是生硬的 CSS 选择器。

代理拿到这份上下文后再生成测试，就不再需要推测 DOM 结构。它知道提交按钮叫 billing-submit-button，知道套餐选择器是一个名为 "Billing Tier" 的 combobox。生成出来的测试自然是定位准确的，而且用的是现代无障碍查询方式。

Playwright 定位器风格：Playwright 推荐使用面向用户语义的定位器，getByTestId 匹配 data-testid 等测试属性，getByRole 则依据 ARIA 角色加可访问名称来查找元素，例如 getByRole("combobox", { name: "Billing Tier" }) 表示查找一个角色为下拉组合框、可访问名称为 "Billing Tier" 的元素。相比 div > form > div:nth-child(3) > select 这类 CSS 路径，语义定位器不依赖 DOM 层级和临时 class 名，前端结构调整后通常仍然可用。把快照统一成这种风格，等于让代理直接产出符合最佳实践的测试代码，而不是生成后又需要人工替换的脆弱选择器。

这解决的不只是「幻觉」

把这个问题简单归为「AI 幻觉」其实低估了它的价值。真正的转变在于：把前端的隐式契约显式化。

data-testid 和 ARIA 属性本来就是开发者写给测试工具看的「接口」，只是过去这些接口只服务于人类写的测试。现在它们同样服务于 AI 代理。索引层做的事情，是把这个早已存在的接口暴露给新的消费方。

这也意味着维护成本的变化。团队只要保持 data-testid 命名规范、ARIA 属性填写完整，代理生成的测试就会持续稳定。反过来，如果前端本身定位属性混乱，索引也只能如实反映这种混乱——工具不会魔法般修复糟糕的可测试性。

从工程角度看，这种做法比让代理去读整个 DOM 树或渲染后的 HTML 要高效得多：AST 解析拿到的是精确的、带行号的属性映射，token 消耗可控，准确率也高。对于任何已经在用 AI 代理写测试的团队，把测试定位属性纳入前端索引，是一个投入产出比相当高的改动。