cypress-tap

使用 cypress tap 驱动 Cypress

cypress tap 可控制已运行的 cypress open 会话。使用它迭代测试规范、检查测试报告器和命令日志，并在无需 GUI 交互的情况下读取被测应用。 一次性无头批处理请改用 cypress run。

核心循环

npx cypress tap sessions                    # confirm a session; note pid if several exist
npx cypress tap status                      # baseline startedAt + spec
npx cypress tap run cypress/e2e/foo.cy.ts   # async — returns immediately
# poll status until passed|failed for your spec with a changed startedAt
npx cypress tap reporter
npx cypress tap reporter --test-id r3       # one test: log, network, stubs, error

run 是异步的。陈旧的判定与新鲜判定在所有字段上都相同，唯独 startedAt 除外；而监视器重新运行已选中的测试规范时，即使没有运行你的文件，也可能推进 startedAt。请以 startedAt、spec 和终止状态作为判断依据。不要等待观察到 running——快速测试可能在两次轮询之间就已完成。可直接复制粘贴的轮询器： session-lifecycle.md。JSON 字段辅助工具： json-recipes.md。

在轮询循环中，如果项目固定了 Cypress 版本，优先使用 ./node_modules/.bin/cypress tap …，而不是 npx cypress tap …。

前提条件

• 从包元数据或锁文件确认解析出的 Cypress 版本为 15.21.0+，且包含 tap。不要使用 tap --help 探测未知的较旧版本；低于最低版本的预发布版本可能会尝试发现会话，而不是打印帮助信息。
• 会话必须使用 Electron、Chrome、Chromium 或 Edge。不支持 Firefox 和 WebKit。
• cypress open 以及任何已配置的 baseUrl 开发服务器必须已在运行。
• 当前工作目录（cwd）决定使用哪个 Cypress 二进制文件，以及自动选择哪个会话。当目标项目固定使用较旧版本的 Cypress 时，请从兼容的代码库运行 tap，并在每次调用时传入 --session <pid>。

按任务选择文档

• 启动、选择或轮询会话： 阅读 session-lifecycle.md。
• 运行测试规范或查看其结果： 阅读 session-lifecycle.md 和 reading-results.md。
• 编写或检查测试规范： 阅读 recipes.md 和 reading-the-app.md。
• 诊断故障： 阅读 recipes.md、 reading-results.md 和 reading-the-app.md。
• 命令失败、挂起、项目错误或输出异常： 阅读 troubleshooting.md。
• 解析 --json 或编写轮询脚本： 阅读 json-recipes.md。
• 一次性非交互式批处理： 使用 cypress run，而不是 tap。

只阅读当前任务所需的参考文档。

核心命令

• sessions：可访问的会话、项目根目录、测试类型和浏览器；JSON 还会提供支持状态和渲染器健康状态。
• status：生命周期阶段、已选中的测试规范、运行标识、计数、构建错误和当前固定项。
• specs：与会话测试类型对应的可运行项目相对测试规范路径。
• run <spec>：分派测试规范后立即返回。
• reporter：测试规范概览和测试 ID；使用 --test-id 时，显示完整的测试尝试信息。
• command：一行命令日志，包含网络数据、快照和控制台属性。
• pin：将应用帧回退到某个命令快照。
• dom、aria、inspect：读取已稳定的应用或当前固定的快照。

所有命令均接受 --session <pid>、--json 和 --timeout <ms>。在确认构建版本受支持后，可使用 npx cypress tap <command> --help 查看命令专属标志。帮助信息根据实时会话契约生成——若帮助信息与此技能说明不一致，请以帮助信息为准。

不可妥协的结果判定规则

run 确认的是任务已派发，而不是已执行，并且会在新一轮运行开始前返回。在这段时间内， status 和应用读取仍可能返回上一轮运行看似合理的结果和页面。

对于每次显式运行：

1. 读取当前的 startedAt。
2. 仅派发一个 spec。
3. 每次轮询只获取一份 status --json 响应。
4. 仅当预期的 spec 对应的结果为 passed 或 failed，且 startedAt 非空并已变化时，才接受该结果。只有当该会话中该 spec 从未启动过运行时，startedAt 才为 null——也就是首次选择时构建失败的情况。如果重跑或监视器触发的重新构建失败，startedAt 仍会更新，因此应按正常流程处理。仅首次选择时才保留 null 回退逻辑（可观察到的基线已变化，或此前观察到 loading/running）。
5. 限制循环次数；如果没有收到匹配的新结果，则判定失败。

保存当前激活的 spec 会触发监视器自动运行。编辑后，要么使用该次运行，要么等待它结束，再获取基线并派发下一次运行。切勿有意让两次运行同时进行。

成功的 status 调用可能会短暂返回空白或不完整的负载。将缺失字段视为“继续等待”，而非状态变化。status 非零退出表示命令失败，而不是读取不完整：停止轮询并报告错误。

只有 passed 和 failed 才是结果。构建失败会被判定为 failed，诊断信息位于 status.error 中，即使此时可能还没有任何测试。只有 status 会携带该诊断信息——reporter 会将构建失败显示为空 spec。

关键正确性规则

1. 指定目标会话。 如果存在多个会话，或自动选择行为异常，请检查 sessions，并在每次调用时传入 --session <pid>。自动选择可能选中其他项目或无响应的会话。端到端测试和组件测试使用不同的会话：它们可以共用一个 projectRoot，但公开的 specs 列表不同，而且只有 status 会指出哪个会话作出了响应——其他命令的输出中都不包含 pid。
2. 保留二进制文件的位置。 每次调用时，Cwd 都会控制 npx 的解析位置。如果项目固定使用较旧版本的 Cypress，请从兼容的检出目录运行命令，并传入 --session <pid>。
3. 不要解析失败的命令。 解析 JSON 前先检查退出代码。受支持构建中的失败通常会写入 stderr，但旧版兼容性失败可能会写入 stdout。有歧义的选择器是有意设置的例外：它会以退出代码 1 结束，并在 stdout 中列出匹配项。
4. 检查兼容性时，不要丢弃调度命令的 stdout。 较旧版本的 Cypress 可能会将 Unknown command "tap" 和用法文本打印到 stdout；重定向会掩盖原因。
5. 将可能很大的 JSON 重定向到文件。 reporter --test-id --json 和 command --json 的输出可能达到数百 KB。请将其保存到文件后再解析。
6. 断定内容不存在前，先检查输出是否被截断。 dom 和 aria 会限制输出长度。如果出现 (output truncated)，请缩小选择器范围或提高限制。
7. 断定内容不存在前，先检查实时 frame 是否正常。 末尾处于待处理或跳过状态的测试可能会导致已稳定的 runner 显示空白占位内容，而应用读取仍以退出代码 0 结束。请确认一个已知的应用锚点。如果 frame 为空，请固定上一个真实命令的快照，并改为读取该状态。
8. 编辑或删除 spec 前，先读取结果。 结果和快照保存在 Cypress 应用的内存中，重新运行、重启、重命名或删除后都可能消失。
9. 清除固定快照。 检查完命令快照后，运行 pin --clear；否则后续应用读取仍会描述固定的旧状态。即使人类可读输出显示 FAILED TO CLEAR PIN，退出代码为 0 且结果为 cleared:false 也只是无害的空操作。
10. 使用适合读取实时状态的命令。 当前表单控件值请使用 aria：dom 和 inspect 可能显示初始 HTML value 属性，而 inspect 可能会省略无障碍值。要精确读取实时区域、toast、状态和标签文本，请使用 dom，因为 aria 可能会省略后代文本。
11. 连续探测宽泛选择器时使用 ;，不要使用 &&。 对于 dom/aria/inspect，匹配数为零时退出代码为 0，有歧义时退出代码为 1。能够枚举匹配项的宽泛探测结果很有用；使用 && 会在第一个有歧义的选择器之后丢弃所有后续命令。
12. 通过测试不等于完成全部验证。 显示绿色结果后，请读取 reporter --test-id，并确认拦截器的匹配次数、存根的使用情况，以及你关心的请求是否已被存根。请参阅 reading-results.md 和 json-recipes.md。

输出约定

• 人类可读输出用于阅读；--json 用于解析，可能包含更多数据。默认渲染通常更适合一次性调试：它会内嵌代码帧，并按日志顺序穿插网络事件。
• 退出码为 0 不代表你的目标已实现。 tap 不会启动 Cypress。没有会话时，退出码为 0 的情况下，status 为 not connected；sessions 会打印指引，而不是 JSON。选择器未匹配、specs 为空以及未知的 --session pid 也可能以退出码 0 结束。应根据字段判断，而不是根据是否有输出判断。
• 对于已知生命周期阶段（包括 not connected），status 会以退出码 0 结束。发现、兼容性、不支持的浏览器以及渲染器故障会导致退出码 1，有时不会输出 stdout；轮询器必须在遇到非零退出码时立即失败。
• dom、aria 和 inspect 必须恰好选中一个元素。匹配不明确时会以退出码 1 结束，并给出候选选择器。未匹配不属于 CLI 故障：dom 和 inspect 会报告 found:false；aria 在未匹配和元素没有无障碍节点这两种情况下都会返回空树。
• 故障信息以普通文本呈现，没有稳定的错误代码。应根据退出状态判断，而不是根据消息文本判断。

性能默认设置

• 优先使用一次 reporter --test-id 读取，而不是针对每一行分别调用一次 command。
• 获得最新判定并确认实时帧正常后，可并发执行彼此独立的应用读取操作。
• 如果有界状态轮询失败，请检查 sessions 中的 rendererResponsive: false；应重启卡住的渲染器，而不是增大 --timeout。

根据症状查阅

症状	阅读
轮询卡住，或判定可能不是我的	session-lifecycle.md
编辑了文件；不确定哪些内容重新运行了	session-lifecycle.md（文件监视器）
JSON 键为空或猜错了	json-recipes.md
列、e 行或测试 ID 的含义	reading-results.md
测试数量 ≠ 预期的 it 数量	reading-results.md、recipes.md（组件）
故障排查或标记看起来不对	recipes.md、reading-the-app.md
退出码为 1，但输出看起来正常	troubleshooting.md