cypress-tap

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Driving Cypress with

cypress tap

使用

cypress tap

驱动Cypress

cypress tap

controls an already-running

cypress open

session. Use it to iterate on specs, inspect the reporter and command log, and read the app under test without GUI interaction. Use

cypress run

instead for a one-shot headless batch.

cypress tap

用于控制已运行的

cypress open

会话。你可以用它迭代测试用例、查看报告器和命令日志，无需GUI交互即可读取被测应用内容。如果是一次性无头批量运行，请使用

cypress run

替代。

Prerequisites

前提条件

Confirm from package metadata or the lockfile that the resolved Cypress is 15.21.0+ and contains
```
tap
```
. Do not use
```
tap --help
```
to probe an unknown older build; prereleases below the version floor may attempt session discovery instead of printing help.
The session must use Electron, Chrome, Chromium, or Edge. Firefox and WebKit are unsupported.
```
cypress open
```
and any configured
```
baseUrl
```
dev server must already be running.
The cwd chooses both the Cypress binary and the automatically selected session. When the target project pins an older Cypress, run
```
tap
```
from a compatible checkout and pass
```
--session <pid>
```
on every call.

从包元数据或锁文件确认已安装的Cypress版本为15.21.0+且包含
```
tap
```
功能。不要使用
```
tap --help
```
探查未知的旧版本构建；低于最低版本的预发布版本可能会尝试会话发现而非打印帮助信息。
会话必须使用Electron、Chrome、Chromium或Edge浏览器。Firefox和WebKit暂不支持。
```
cypress open
```
及所有已配置的
```
baseUrl
```
开发服务器必须已启动。
当前工作目录（cwd）会同时选择Cypress二进制文件和自动选中的会话。当目标项目固定了旧版本Cypress时，请从兼容的代码检出目录运行
```
tap
```
，并在每次调用时传入
```
--session <pid>
```
参数。

Route by task

按任务选择指引

Start, select, or poll a session: read session-lifecycle.md.
Run a spec or read its results: read session-lifecycle.md and reading-results.md.
Author or inspect a spec: read recipes.md and reading-the-app.md.
Diagnose a failure: read recipes.md, reading-results.md, and reading-the-app.md.
Command failure, hang, wrong project, or surprising output: read troubleshooting.md.
One noninteractive batch: use
```
cypress run
```
, not
```
tap
```
.

Read only the references required for the current task.

启动、选择或轮询会话： 阅读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。
非交互式批量运行： 使用
```
cypress run
```
，而非
```
tap
```
。

仅阅读当前任务所需的参考文档即可。

Core commands

核心命令

```
sessions
```
: reachable sessions, project roots, testing types, and browsers; JSON adds support and renderer health.
```
status
```
: lifecycle stage, selected spec, run identity, counts, build error, and active pin.
```
specs
```
: runnable project-relative spec paths for the session's testing type.
```
run <spec>
```
: dispatches a spec and returns immediately.
```
reporter
```
: spec overview and test ids; with
```
--test-id
```
, the complete test attempt.
```
command
```
: one command-log row with network data, snapshots, and console properties.
```
pin
```
: rewinds the app frame to a command snapshot.
```
dom
```
,
```
aria
```
,
```
inspect
```
: read the settled app or currently pinned snapshot.

All commands accept

--session <pid>

--json

, and

--timeout <ms>

. On a confirmed supported build, use

npx cypress tap <command> --help

for command-specific flags.

```
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

查看命令专属参数。

The non-negotiable verdict rule

不可协商的结果判定规则

run

confirms dispatch, not execution, and returns before the new run starts. During that gap,

status

and app reads can still return the previous run's plausible verdict and page.

For every explicit run:

Read the current
```
startedAt
```
.
Dispatch exactly one spec.
Poll one
```
status --json
```
response at a time.
Accept only
```
passed
```
or
```
failed
```
for the expected
```
spec
```
with a non-empty, changed
```
startedAt
```
.
```
startedAt
```
is null only when no run has ever started for that spec in the session — a build failure on first selection. A build that fails on rerun or on a watcher rebuild still advances
```
startedAt
```
, so it takes the normal path. Keep the null fallback (a changed observable baseline, or a preceding
```
loading
```
/
```
running
```
observation) for the first-selection case only.
Bound the loop and fail if no matching fresh verdict arrives.

Saving the active spec triggers an automatic watcher run. After editing, either use that run or let it settle before taking a baseline and dispatching another. Never intentionally put two runs in flight.

Blank and partial payloads from a successful

status

call occur transiently. Treat missing fields as "keep waiting," not as a state change. A nonzero

status

exit is a command failure, not a partial read: stop polling and report it.

Only

passed

and

failed

are verdicts. A build failure is

failed

with the diagnostic in

status.error

, possibly before any tests exist.

status

is the only surface that carries that diagnostic —

reporter

renders a failed build as an empty spec.

run

命令仅确认分发成功，而非执行完成，会在新运行开始前返回。在此间隙，

status

和应用读取仍可能返回上一次运行的合理结果和页面状态。

对于每一次显式运行：

读取当前的
```
startedAt
```
值。
精确分发一个测试用例。
每次轮询一条
```
status --json
```
响应。
仅接受预期测试用例的
```
passed
```
或
```
failed
```
状态，且对应的
```
startedAt
```
值非空且已变更。只有当会话中该测试用例从未启动过运行时，
```
startedAt
```
才会为null——即首次选择时出现构建失败。重新运行或观察器重建时的构建失败仍会更新
```
startedAt
```
，因此遵循正常流程。仅在首次选择场景下保留null的回退逻辑（即已变更的可观察基线，或之前观察到的
```
loading
```
/
```
running
```
状态）。
为轮询设置时间限制，若未收到匹配的最新结果则判定失败。

保存活动测试用例会触发自动观察器运行。编辑后，要么使用该运行结果，要么等待其稳定后再获取基线并分发下一次运行。切勿同时运行两个测试任务。

成功调用

status

时可能会出现空白或部分负载，这是临时现象。将缺失字段视为“继续等待”，而非状态变更。

status

命令非零退出码表示命令失败，而非部分读取：停止轮询并报告该错误。

只有

passed

和

failed

是有效结果状态。构建失败属于

failed

状态，诊断信息在

status.error

中，可能在测试用例存在前就出现。

status

是唯一承载该诊断信息的入口——

reporter

会将构建失败渲染为空测试用例。

Critical correctness rules

关键正确性规则

Target the intended session. If several sessions exist, or auto-selection behaves oddly, inspect
```
sessions
```
and pass
```
--session <pid>
```
. Auto-selection can choose another project or an unresponsive session.
Preserve the binary location. Cwd controls
```
npx
```
resolution on every call. When the project pins an older Cypress, run commands from a compatible checkout and pass
```
--session <pid>
```
.
Do not parse failed commands. Check the exit code before parsing JSON. Supported-build failures generally use stderr, but older compatibility failures may use stdout. An ambiguous selector is the intentional exception: it exits
```
1
```
and lists matches on stdout.
Do not discard dispatch stdout while checking compatibility. An older Cypress may print
```
Unknown command "tap"
```
and usage text to stdout; redirecting it hides the cause.
Redirect potentially large JSON.
```
reporter --test-id --json
```
and
```
command --json
```
can be hundreds of kilobytes. Save them to a file and parse the file.
Check truncation before concluding absence.
```
dom
```
and
```
aria
```
cap output. Narrow the selector or raise the limit when
```
(output truncated)
```
appears.
Sanity-check the live frame before concluding absence. A trailing pending/skipped test can leave the settled runner on a blank placeholder while app reads still exit
```
0
```
. Confirm a known app anchor. If the frame is blank, pin a snapshot from the last real command and read that state instead.
Read results before editing or deleting the spec. Results and snapshots live in the Cypress app's memory and can disappear on rerun, restart, rename, or deletion.
Clear pins. After inspecting a command snapshot, run
```
pin --clear
```
; otherwise later app reads continue to describe the pinned past. An exit-
```
0
```
```
cleared:false
```
result is a benign no-op even if human output says
```
FAILED TO CLEAR PIN
```
.
Use the right reader for live state. Use
```
aria
```
for current form-control values:
```
dom
```
and
```
inspect
```
can show the initial HTML
```
value
```
attribute, and
```
inspect
```
may omit the accessibility value. Use
```
dom
```
for exact live-region, toast, status, and label text because
```
aria
```
may omit descendant text.

定位目标会话：如果存在多个会话，或自动选择行为异常，请查看
```
sessions
```
并传入
```
--session <pid>
```
参数。自动选择可能会选中其他项目或无响应的会话。
保留二进制文件位置：每次调用时，当前工作目录（cwd）会控制
```
npx
```
的解析逻辑。当项目固定了旧版本Cypress时，请从兼容的代码检出目录运行命令，并传入
```
--session <pid>
```
参数。
不要解析失败的命令：解析JSON前先检查退出码。支持版本的失败通常使用stderr输出，但旧版本兼容性失败可能使用stdout输出。模糊选择器是例外情况：它会以退出码1退出，并在stdout中列出匹配项。
检查兼容性时不要丢弃分发的stdout输出：旧版本Cypress可能会在stdout中打印
```
Unknown command "tap"
```
和使用说明；重定向输出会隐藏问题原因。
重定向可能过大的JSON输出：
```
reporter --test-id --json
```
和
```
command --json
```
的输出可能达到数百KB。请将其保存到文件后再解析。
得出“不存在”结论前检查是否被截断：
```
dom
```
和
```
aria
```
会限制输出大小。当出现
```
(output truncated)
```
时，请缩小选择器或提高限制。
得出“不存在”结论前检查实时框架：末尾的待定/跳过测试可能会让稳定后的运行器停留在空白占位符，而应用读取仍会以退出码0返回。请确认已知的应用锚点。如果框架为空，请固定最后一条真实命令的快照并读取该状态。
编辑或删除测试用例前读取结果：结果和快照存储在Cypress应用的内存中，重新运行、重启、重命名或删除测试用例时可能会丢失。
清除固定项：检查命令快照后，运行
```
pin --clear
```
；否则后续的应用读取仍会描述固定的历史状态。即使人类输出显示
```
FAILED TO CLEAR PIN
```
，退出码0且
```
cleared:false
```
的结果是良性的无操作。
使用正确的读取器获取实时状态：使用
```
aria
```
获取当前表单控件的值：
```
dom
```
和
```
inspect
```
可能显示初始HTML的
```
value
```
属性，而
```
inspect
```
可能会忽略无障碍访问值。使用
```
dom
```
获取精确的实时区域、提示框、状态和标签文本，因为
```
aria
```
可能会忽略后代文本。

Output contract

输出约定

Human output is for reading;
```
--json
```
is for parsing and may contain much more data.
```
status
```
exits
```
0
```
for known lifecycle stages, including
```
not connected
```
. Discovery, compatibility, unsupported-browser, and renderer failures exit
```
1
```
, sometimes with no stdout; a poller must fail fast on that nonzero exit.
```
dom
```
,
```
aria
```
, and
```
inspect
```
require exactly one selected element. Ambiguity exits
```
1
```
with candidate selectors. A miss is not a CLI failure:
```
dom
```
and
```
inspect
```
report
```
found:false
```
;
```
aria
```
returns an empty tree both for a miss and for an element with no accessibility node.
Failures are prose without stable error codes. Branch on exit status, not message text.

人类可读输出用于查看；
```
--json
```
格式用于解析，可能包含更多数据。
```
status
```
命令在已知生命周期阶段（包括
```
not connected
```
）会以退出码0退出。发现失败、兼容性失败、不支持的浏览器和渲染器失败会以退出码1退出，有时无stdout输出；轮询器必须在非零退出码时快速失败。
```
dom
```
、
```
aria
```
和
```
inspect
```
要求精确选中一个元素。模糊选择会以退出码1退出并列出候选选择器。未找到元素不属于CLI失败：
```
dom
```
和
```
inspect
```
会报告
```
found:false
```
；
```
aria
```
对于未找到元素或无障碍节点为空的元素都会返回空树。
失败信息为描述性文本，无稳定错误码。请根据退出状态分支处理，而非消息文本。

Performance defaults

性能默认规则

Prefer one
```
reporter --test-id
```
read over one
```
command
```
call per row.
After a fresh verdict and live-frame sanity check, independent app reads may run concurrently.
If bounded status polling fails, inspect
```
sessions
```
for
```
rendererResponsive: false
```
; restart a wedged renderer instead of increasing
```
--timeout
```
.

优先使用一次
```
reporter --test-id
```
读取，而非每行调用一次
```
command
```
。
获取最新结果并完成实时框架合理性检查后，独立的应用读取可并发执行。
如果有限制的状态轮询失败，请查看
```
sessions
```
中的
```
rendererResponsive: false
```
；重启卡住的渲染器而非增加
```
--timeout
```
参数。

cypress-tap

Original

Translation

Driving Cypress with
`cypress tap`

使用
`cypress tap`
驱动Cypress

Prerequisites

前提条件

Route by task

按任务选择指引

Core commands

核心命令

The non-negotiable verdict rule

不可协商的结果判定规则

Critical correctness rules

关键正确性规则

Output contract

输出约定

Performance defaults

性能默认规则

cypress-tap

Original

Translation

Driving Cypress with cypress tap

使用cypress tap驱动Cypress

Prerequisites

前提条件

Route by task

按任务选择指引

Core commands

核心命令

The non-negotiable verdict rule

不可协商的结果判定规则

Critical correctness rules

关键正确性规则

Output contract

输出约定

Performance defaults

性能默认规则

Driving Cypress with
`cypress tap`

使用
`cypress tap`
驱动Cypress