gate-ci-a11y

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Gate CI with Real A11y CLI

借助Real A11y CLI管控CI流程

Shell/CI surface for live URLs. Docs: https://real-a11y.dev/packages/cli
Commands: https://real-a11y.dev/packages/cli/commands
Config: https://real-a11y.dev/packages/cli/configuration
PR bot recipe: https://real-a11y.dev/guide/ci-diff-bot

面向实时URL的Shell/CI操作界面。文档：https://real-a11y.dev/packages/cli
命令：https://real-a11y.dev/packages/cli/commands
配置：https://real-a11y.dev/packages/cli/configuration
PR机器人方案：https://real-a11y.dev/guide/ci-diff-bot

Install in CI

在CI中安装

npm i -D @real-a11y-dev/cli@beta playwright
npx real-a11y install

Serve the app (or point at a preview URL), wait until healthy, then audit.

npm i -D @real-a11y-dev/cli@beta playwright
npx real-a11y install

启动应用（或指向预览URL），等待应用就绪后执行审计。

Simple gate

简单管控

npx real-a11y audit http://localhost:3000

Exit 1 on error-severity findings.
Exit 2 (or non-zero failure) when the URL is unreachable — never treat network failure as a clean pass.
Optional
```
a11y.config.json
```
with
```
defaults
```
and
```
urls
```
for multi-page runs.

npx real-a11y audit http://localhost:3000

若发现错误级问题，退出码为1。
若URL无法访问，退出码为2（或非零失败）——绝不将网络故障视为检查通过。
可选配置文件
```
a11y.config.json
```
，通过
```
defaults
```
和
```
urls
```
实现多页面运行。

PR regression (snapshot → diff)

PR回归检测（快照→差异对比）

On the base ref:

real-a11y snapshot <url> --output base.json

(or configured set)

On the PR ref:

real-a11y snapshot <url> --output pr.json

```
real-a11y diff base.json pr.json
```
— fails on new regressions
Use
```
--format md
```
for PR comments; optional
```
--explain
```
for structural hints (advisory only — do not treat as a hard signal alone)

Identity matching uses fingerprints — do not line-diff raw JSON by hand. Noisy live pages (timestamps, ads) may need

--ignore-view-line

(see CLI docs / D3).

Capture baselines in a fresh session if you also use

--session

for acts.

在基准分支上执行：
```
real-a11y snapshot <url> --output base.json
```
（或已配置的URL集合）

在PR分支上执行：

real-a11y snapshot <url> --output pr.json

执行
```
real-a11y diff base.json pr.json
```
——若出现新的回归问题则检查失败
使用
```
--format md
```
生成PR评论；可选
```
--explain
```
参数获取结构提示（仅作参考——请勿单独将其作为硬性判断依据）

身份匹配采用指纹识别——请勿手动对比原始JSON的行差异。包含动态内容（如时间戳、广告）的页面可能需要使用

--ignore-view-line

参数（详见CLI文档/D3）。

如果同时使用

--session

参数执行操作，请在全新会话中捕获基线。

Adopting on existing debt

适配既有问题场景

Use baseline suppression on real-a11y snapshot
(not

audit

) so only new issues fail the build:

npx real-a11y snapshot --config a11y.config.json --update-baseline
npx real-a11y snapshot --config a11y.config.json \
  --baseline .a11y-baseline.json --fail-on error

--baseline

is also valid on

diff

. Suppressed items still report but don’t fail. Re-baseline after intentional a11y fixes or after locator/fingerprint format changes called out in release notes.

在**

real-a11y snapshot

**（而非

audit

）命令中使用基线抑制功能，仅让新出现的问题导致构建失败：

npx real-a11y snapshot --config a11y.config.json --update-baseline
npx real-a11y snapshot --config a11y.config.json \
  --baseline .a11y-baseline.json --fail-on error

--baseline

参数同样适用于

diff

命令。被抑制的项目仍会被报告，但不会导致构建失败。在完成针对性的无障碍修复后，或在版本说明中提及的定位器/指纹格式变更后，需重新生成基线。

Artifacts

产物

Prefer documented reporters (

sarif

junit

json

jsonl

) for uploads to code-scanning / test dashboards. The CLI is not a crawler — name the URLs.

优先使用官方文档支持的报告格式（

sarif

、

junit

、

json

jsonl

）上传至代码扫描/测试仪表盘。该CLI并非爬虫工具——需明确指定要检查的URL。