@ accesslint/ vitest (英语)
Vitest的无障碍断言. 添加一个 toBeAccessible() 火柴电源 访问提示 检查WCAG 2.2 A级和AA级的违法行为.
安装
npm install --save-dev @accesslint/vitest
vitest ^ 2.0 需要作为对等依赖.
设置
添加 @accesslint/vitest 作为您 Vitest 配置中的设置文件 :
// vitest.config.ts
import { defineConfig } from "vitest/config";
export default defineConfig({
test: {
setupFiles: ["@accesslint/vitest"],
},
});
此自动注册 toBeAccessible() 选手.
人工登记
import { accesslintMatchers } from "@accesslint/vitest/matchers";
import { expect } from "vitest";
expect.extend(accesslintMatchers);
使用量
通过任何 DOM Element 改为 expect() 打电话 toBeAccessible()数字 :
const container = document.createElement("div");
container.innerHTML = '<img src="photo.jpg" alt="A photo">';
expect(container).toBeAccessible();
违章行为范围为您所通过元素的后人,因此您可以单独测试组件. 当元素不是文档根时,页级规则(html-has-lang, (中文(简体) ), document-title,地标等)自动跳出——以 componentMode: false 如果你想要他们回来.
框架配方
与任何DOM一起工作,生产在一个jsdom或幸福度环境中.
反应.. @testing-library/react
import { render } from "@testing-library/react";
import { LoginForm } from "./LoginForm";
test("LoginForm is accessible", () => {
const { container } = render(<LoginForm />);
expect(container).toBeAccessible();
});
维- @testing-library/vue
import { render } from "@testing-library/vue";
import LoginForm from "./LoginForm.vue";
test("LoginForm is accessible", () => {
const { container } = render(LoginForm);
expect(container).toBeAccessible();
});
斯维尔特.. @testing-library/svelte
import { render } from "@testing-library/svelte";
import LoginForm from "./LoginForm.svelte";
test("LoginForm is accessible", () => {
const { container } = render(LoginForm);
expect(container).toBeAccessible();
});
角 -- -- @testing-library/angular
import { render } from "@testing-library/angular";
import { LoginFormComponent } from "./login-form.component";
test("LoginForm is accessible", async () => {
const { container } = await render(LoginFormComponent);
expect(container).toBeAccessible();
});
选手接受一切 Element —— 说 container, (中文(简体) ), screen.getByRole('form'),一个平地 document.createElement(...),或 document.body 进行整页审计.
选项
expect(container).toBeAccessible({
/** Rule IDs to disable for this assertion. */
disabledRules: ["distinguishable/color-contrast"],
/** Additional rules to run on top of the built-in set. */
additionalRules: [myCompiledDeclarativeRule],
/** Include AAA-level rules (excluded by default). */
includeAAA: true,
/** Skip page-level rules — defaults to true for non-root elements. */
componentMode: true,
/** Translated rule messages and guidance (e.g. "en", "es"). */
locale: "es",
/** Minimum impact that causes failure. "minor" (default) fails on anything. */
failOn: "serious",
/** Compare against a baseline instead of asserting zero violations. */
snapshot: "login-form",
/** Where to store snapshot files. Defaults to {cwd}/accessibility-snapshots/. */
snapshotDir: "./test/a11y-snapshots",
});
失败消息
失败包括影响、世界保护理事会的标准、水平、选择者、可选上下文、建议固定办法和补救指导:
Expected element to have no accessibility violations, but found 2:
[critical] text-alternatives/img-alt (WCAG 1.1.1, A) — Images must have alternate text
selector: img
fix: add-attribute alt=""
guidance: Decorative images should have alt=""; informative images should describe content.
[serious] distinguishable/color-contrast (WCAG 1.4.3, AA) — Text must have sufficient color contrast
selector: p.subtitle
即时基线
在组件当前可访问状态下锁定, 并且仅失败于 新设 违反情况。 在遗留的代码库中采用 AccessLint 有用 .
expect(container).toBeAccessible({ snapshot: "login-form" });
- 首发 创建
accessibility-snapshots/login-form.json和通过. - 随后运行 如果有任何新的违规行为出现于基线之外,则无法执行.
- 向下旋转 ——当仅发现有固定违规情况(无新增)时,基准自动更新.
- 强制刷新 基线
ACCESSLINT_UPDATE=1或维特的-u编号 :--update旗帜.
违规身份开始于 ruleId + selector 然后通过一个多信号匹配器倒下 @accesslint/heal-diff数字 :
- 精确选择器匹配( 快速路径) .
- 锁定属性( A)
data-testid, (中文(简体) ),id, (中文(简体) ),name, (中文(简体) ),href, (中文(简体) ),for, (中文(简体) ),aria-label) (中文(简体) ). - 计算出ARIA角色+可访问名.
- HTML指纹(正态外HTML hash).
- 相对位置(靠近地标线索),独有性格.
当一个非精确的级别将基准选择器的自动愈合到当前时,快照会被重写,而 a "healed" 已登录为 .history.ndjson测试还是通过了 当没有级别匹配但信号较弱重叠时,故障信息附加一个 likely moved from: 提示,这样你就可以从"真正的新一期"看一看"同样的问题,不同的选择者".
趋势报告
每个创建 / Ratch- down / 强制更新事件 附加记录到 accessibility-snapshots/.history.ndjson 与基线 JSON 文件并列 。 从历史中产生一个趋势报告 @accesslint/report数字 :
npx @accesslint/report --format md > a11y-report.md
npx @accesslint/report --format html --out a11y-report.html
报告显示一个叠加的图表,显示每个快照的违反总数,加上加入WCAG元数据的每个规则移动表 @accesslint/core。侧车文件是仅附件且安全可执行的;合并其上的冲突通过调和双方解决.
审计备忘录(选择中固定)
默认时间 : toBeAccessible() 呼叫运行一个新的审计。 对于将多个断言与同一DOM状态连在一起的组件测试,输入固定值以重复一次断言:
import { test } from "@accesslint/vitest/fixture";
import { expect } from "vitest";
test("Form", ({ a11y }) => {
render(<Form />);
a11y.refresh(); // snapshot current DOM state
// both assertions reuse one runAudit() call
expect(screen.getByRole("form")).toBeAccessible();
expect(screen.getByRole("button")).toBeAccessible();
});
打电话 a11y.refresh() 在DOM突变后,应当重新审计.
类型脚本
包括类型。 导入软件包会增加 Vitest 的 expect 与 toBeAccessible() 自动.
它检查什么
WCAG 2.2 A级和AA级规则通过 @accesslint/core,覆盖图像,形式,ARIA属性,颜色对比,地标,链接,表格,文档语言等等. 见 核心规则表 完整名单.
许可证
麻省理工学院