# @accesslint/vitest 中文文档

规范地址：https://npmcn.com/package/%40accesslint/vitest/

版本：0\.3\.2
npm 元数据更新时间：2026-07-26T23:35:17.553Z
中文译文更新时间：2026-11-05T19:03:57.429Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40accesslint/vitest
原文对照：https://npmcn.com/package/%40accesslint/vitest/?lang=original
项目主页：https://github.com/AccessLint/accesslint#readme
源码仓库：https://github.com/AccessLint/accesslint

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：85 kB，20 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：vitest \>=2\.0\.0
- 首次发布：2026-02-17T03:04:04.729Z
- 最新版本发布：2026-07-26T23:35:17.216Z
- 近 30 天下载量：48234（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

Vitest 的可访问性断言—— 由 AccessLint 驱动的 BeAccessable( ) 匹配器

## 安装

```sh
npm install @accesslint/vitest
```

也可以使用：`pnpm add @accesslint/vitest`、`yarn add @accesslint/vitest`、`bun add @accesslint/vitest`

## README

# @ accesslint/ vitest (英语)

Vitest的无障碍断言. 添加一个 `toBeAccessible()` 火柴电源 [访问提示](https://www.accesslint.com/?ref=readme_vitest) 检查WCAG 2.2 A级和AA级的违法行为.

## 安装

```sh
npm install --save-dev @accesslint/vitest
```

`vitest` ^ 2.0 需要作为对等依赖.

## 设置

添加 `@accesslint/vitest` 作为您 Vitest 配置中的设置文件 :

```ts
// vitest.config.ts
import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    setupFiles: ["@accesslint/vitest"],
  },
});
```

此自动注册 `toBeAccessible()` 选手.

### 人工登记

```ts
import { accesslintMatchers } from "@accesslint/vitest/matchers";
import { expect } from "vitest";

expect.extend(accesslintMatchers);
```

## 使用量

通过任何 DOM `Element` 改为 `expect()` 打电话 `toBeAccessible()`数字 :

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

```tsx
import { render } from "@testing-library/react";
import { LoginForm } from "./LoginForm";

test("LoginForm is accessible", () => {
  const { container } = render(<LoginForm />);
  expect(container).toBeAccessible();
});
```

### 维- `@testing-library/vue`

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

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

```ts
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` 进行整页审计.

## 选项

```ts
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 有用 .

```ts
expect(container).toBeAccessible({ snapshot: "login-form" });
```

-   **首发** 创建 `accessibility-snapshots/login-form.json` 和通过.
-   **随后运行** 如果有任何新的违规行为出现于基线之外,则无法执行.
-   **向下旋转** ——当仅发现有固定违规情况(无新增)时,基准自动更新.
-   **强制刷新** 基线 `ACCESSLINT_UPDATE=1` 或维特的 `-u` 编号 : `--update` 旗帜.

违规身份开始于 `ruleId + selector` 然后通过一个多信号匹配器倒下 [`@accesslint/heal-diff`](https://npmcn.com/package/%40accesslint/heal-diff)数字 :

1.  精确选择器匹配( 快速路径) .
2.  锁定属性( A)`data-testid`, (中文(简体) ), `id`, (中文(简体) ), `name`, (中文(简体) ), `href`, (中文(简体) ), `for`, (中文(简体) ), `aria-label`) (中文(简体) ).
3.  计算出ARIA角色+可访问名.
4.  HTML指纹(正态外HTML hash).
5.  相对位置(靠近地标线索),独有性格.

当一个非精确的级别将基准选择器的自动愈合到当前时,快照会被重写,而 a `"healed"` 已登录为 `.history.ndjson`测试还是通过了 当没有级别匹配但信号较弱重叠时,故障信息附加一个 `likely moved from:` 提示,这样你就可以从"真正的新一期"看一看"同样的问题,不同的选择者".

### 趋势报告

每个创建 / Ratch- down / 强制更新事件 附加记录到 `accessibility-snapshots/.history.ndjson` 与基线 JSON 文件并列 。 从历史中产生一个趋势报告 [`@accesslint/report`](https://npmcn.com/package/%40accesslint/report)数字 :

```sh
npx @accesslint/report --format md > a11y-report.md
npx @accesslint/report --format html --out a11y-report.html
```

报告显示一个叠加的图表,显示每个快照的违反总数,加上加入WCAG元数据的每个规则移动表 `@accesslint/core`。侧车文件是仅附件且安全可执行的;合并其上的冲突通过调和双方解决.

## 审计备忘录(选择中固定)

默认时间 : `toBeAccessible()` 呼叫运行一个新的审计。 对于将多个断言与同一DOM状态连在一起的组件测试,输入固定值以重复一次断言:

```ts
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`](https://npmcn.com/package/%40accesslint/core),覆盖图像,形式,ARIA属性,颜色对比,地标,链接,表格,文档语言等等. 见 [核心规则表](https://npmcn.com/package/%40accesslint/core/README.md#rules) 完整名单.

## 许可证

麻省理工学院

## 常见问题

### @accesslint/vitest 是什么？

Vitest 的可访问性断言—— 由 AccessLint 驱动的 BeAccessable\( \) 匹配器

### 如何安装 @accesslint/vitest？

在项目目录运行 npm install @accesslint/vitest，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vitest（\>=2\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @accesslint/vitest 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @accesslint/vitest 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @accesslint/vitest 可以商用吗？

@accesslint/vitest 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @accesslint/vitest 的下载量有多少？

根据 npm 官方下载统计，@accesslint/vitest 在 2026/10/05 – 2026/11/03 这 30 天内被下载 48,234 次，日均约 1,608 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @accesslint/vitest 还在维护吗？

最新版本 0\.3\.2 发布于 2026/07/27（3 个月前）；至今共发布 11 个版本，其中过去 12 个月发布了 11 个；首次发布于 2026/02/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。