# @chanzuckerberg/axe-storybook-testing 中文文档 规范地址：https://npmcn.com/package/%40chanzuckerberg/axe-storybook-testing/ 版本：10\.0\.0 npm 元数据更新时间：2025-11-25T16:31:35.879Z 中文译文更新时间：2026-11-09T10:28:19.176Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40chanzuckerberg/axe-storybook-testing 原文对照：https://npmcn.com/package/%40chanzuckerberg/axe-storybook-testing/?lang=original 项目主页：https://github.com/chanzuckerberg/axe-storybook-testing 源码仓库：https://github.com/chanzuckerberg/axe-storybook-testing ## 关键信息（来自 npm 元数据） - 包体积（解压后）：42.3 kB，15 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - 运行依赖：11 个 - peer 依赖：axe-core ^4\.0\.0，storybook ^10\.0\.1 - 首次发布：2020-09-23T18:15:44.020Z - 最新版本发布：2025-11-25T16:31:35.621Z - 近 30 天下载量：19170（2026-10-10 至 2026-11-08，npm 官方下载统计） - 已发布版本数：47（近 12 个月 1 个） ## 中文简介 [![Package Status](https://img.shields.io/npm/v/@chanzuckerberg/axe-storybook-testing.svg)](https://www.npmjs.com/package/@chanzuckerberg/axe-storybook-testing) ![Tests](https://github.com/chanzuckerberg/axe-storybook-testing/workflows/Tests/badge.svg) \[! ## 安装 ```sh npm install @chanzuckerberg/axe-storybook-testing ``` 也可以使用：`pnpm add @chanzuckerberg/axe-storybook-testing`、`yarn add @chanzuckerberg/axe-storybook-testing`、`bun add @chanzuckerberg/axe-storybook-testing` ## README # @chanzuckerberg/xe-故事书测试 [![Package Status](https://img.shields.io/npm/v/@chanzuckerberg/axe-storybook-testing.svg)](https://www.npmjs.com/package/@chanzuckerberg/axe-storybook-testing) ![Tests](https://github.com/chanzuckerberg/axe-storybook-testing/workflows/Tests/badge.svg) [![Release](https://github.com/chanzuckerberg/axe-storybook-testing/actions/workflows/release.yml/badge.svg)](https://github.com/chanzuckerberg/axe-storybook-testing/actions/workflows/release.yml) 运行的命令行接口 [轴核](https://github.com/dequelabs/axe-core) 您的无障碍测试 [故事书故事](https://storybook.js.org/docs/react/api/csf)。 。 。 . 如有违规情况,会将相关信息打印出,命令会以非零出站代码退出. 这样,你就可以在CI上用这个作为自动化的无障碍测试. ## 目录 - [行为守则](https://npmcn.com/package/%40chanzuckerberg/axe-storybook-testing/#readme-code-of-conduct) - [最低要求](https://npmcn.com/package/%40chanzuckerberg/axe-storybook-testing/#readme-minimum-requirements) - [安装](https://npmcn.com/package/%40chanzuckerberg/axe-storybook-testing/#readme-installation) - [使用量](https://npmcn.com/package/%40chanzuckerberg/axe-storybook-testing/#readme-usage) - [选项](https://npmcn.com/package/%40chanzuckerberg/axe-storybook-testing/#readme-options) - [故事参数](https://npmcn.com/package/%40chanzuckerberg/axe-storybook-testing/#readme-story-parameters) - [禁用规则](https://npmcn.com/package/%40chanzuckerberg/axe-storybook-testing/#readme-disabledrules) - [模式](https://npmcn.com/package/%40chanzuckerberg/axe-storybook-testing/#readme-mode) - [运行选项](https://npmcn.com/package/%40chanzuckerberg/axe-storybook-testing/#readme-runoptions) - [上下文](https://npmcn.com/package/%40chanzuckerberg/axe-storybook-testing/#readme-context) - [配置](https://npmcn.com/package/%40chanzuckerberg/axe-storybook-testing/#readme-config) - [跳过](https://npmcn.com/package/%40chanzuckerberg/axe-storybook-testing/#readme-skip) - [超时](https://npmcn.com/package/%40chanzuckerberg/axe-storybook-testing/#readme-timeout) - [等待选择器](https://npmcn.com/package/%40chanzuckerberg/axe-storybook-testing/#readme-waitforselector) (折旧) - [类型脚本](https://npmcn.com/package/%40chanzuckerberg/axe-storybook-testing/#readme-typescript) - [发展中国家](https://npmcn.com/package/%40chanzuckerberg/axe-storybook-testing/#readme-developing) - [警卫](https://npmcn.com/package/%40chanzuckerberg/axe-storybook-testing/#readme-security) - [灵感](https://npmcn.com/package/%40chanzuckerberg/axe-storybook-testing/#readme-inspiration) ## 行为守则 本项目遵循 [《公约》的行为守则](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). 通过参与,你应该维护这个守则。 请报告不可接受的行为 [开源代码@ chanzuckerberg.com](mailto:opensource@chanzuckerberg.com)。 。 。 . ## 最低要求 - 节点 18 - 故事集 10 - 用于"故事本"9,使用轴-故事本测试 v9 - 对于"故事集"7或8,使用轴-故事集-测试v8.2.3 - 出自"史记" 第6卷 使用轴-史记-测试 v6.3.1 - 轴-核心 4.0 ## 安装 ```sh # via npm npm install --save-dev @chanzuckerberg/axe-storybook-testing # or with Yarn yarn add --dev @chanzuckerberg/axe-storybook-testing ``` ## 使用量 用于: 1. 添加创建故事本的脚本, 然后执行轴- 故事本命令 ```jsonc // In package.json "scripts": { "test:axe": "storybook build && axe-storybook" }, ``` 2. 通过调用前一步的脚本来运行测试 ```sh npm run test:axe ``` 3. (可选)安装更多浏览器. 默认安装了铬. 如果你想同时使用Firefox和/或Safari,请安装它们: ```sh npx playwright install ``` 您也可以配置您的脚本以运行 `storybook build --test` 相反,和 [配置故事书](https://storybook.js.org/docs/api/main-config/main-config-build) 以禁用用于测试的无关附加件/特性. ## 选项 命令行界面有以下选项: | 选项 | 默认 | 数值 | 说明 | | --- | --- | --- | --- | | `--browser` | `chromium` | 铬、火花、网基 | 运行测试的浏览器 | | `--build-dir` | `storybook-static` | 路径 | 故事书静态构建目录 | | `--failing-impact` | `all` | 所有,小,中,严重,关键 | 最低影响水平应被视为失败 | | `--headless` | `true` | 布尔 | 是否无头运行 | | `--pattern` | `.*` | 正则图案 | 只运行匹配组件名称模式的测试 | | `--port` | | 编号 | 在测试时运行故事本的端口 。 如果缺少, 将自动选择一个空端口 。 如果提供故事本- URL 则忽略 | | `--reporter` | `spec` | spec, dot, nyan, 有水龙头, 降落, 列表, 进步, json, json- stream, min, doc, mark down, xunit | 如何显示测试运行. 有可能是任何东西 [内置的 Mocha 记者](https://mochajs.org/#reporters)。 。 。 . | | `--reporter-options` | | 字符串 | 给摩卡记者的选项。 对xunit记者特别有用——例如. `--reporter-options output=./filename.xml` | | `--storybook-address` | | url 密码 | **_堕落了!_** 使用 `--storybook-url` 换句话说. | | `--storybook-url` | | url 密码 | 厄尔到运行的故事书 测试对抗。 备选案文 `--build-dir`,如果设置此选项,则该选项将被忽略. | | `--timeout` | 联合国 | 编号 | **_堕落了!_** 使用 `timeout` 故事参数代替. | 比如说,在Firefox中无头跑,你会跑 ```sh # If using npm npm run storybook:axe -- --headless false --browser firefox # or, if using Yarn yarn storybook:axe --headless false --browser firefox ``` ## 故事参数 故事可以使用参数来配置轴-故事本测试如何处理它们. 你可以在故事书所接受的地方提供这些 [参数](https://storybook.js.org/docs/writing-stories/parameters) (故事、组件或全球). ### 禁用规则 防止轴-故事本测试通过使用 `disabledRules` 参数. ```jsx // SomeComponent.stories.jsx export const SomeStory = { parameters: { axe: { disabledRules: ['select-name'], }, }. }; ``` 规则也可以在全球范围内通过 [设置此参数 **所有的故事** 在.故事本/评论.js中](https://storybook.js.org/docs/react/writing-stories/parameters#global-parameters)。 。 。 . ```jsx // .storybook/preview.js export const parameters = { axe: { disabledRules: ['select-name'], }, }; ``` ### 模式 设定一个故事的错误是否会失败测试套件 . 有效的选项有: - `off` - 故事会被跳过 斧头不会运行它。 这和设定一样 `skip: true`。 。 。 . - `warn` - 轴出错会被打印,但不会失败测试套房。 与此设定有关的故事将显示为未决. - `error` (默认) - 轴出错会让一个故事的测试套件失效 . ```jsx // .storybook/preview.js export const parameters = { axe: { mode: 'warn', }, }; ``` ### 运行选项 允许使用任何可用的 [`axe.run`](https://www.deque.com/axe/core-documentation/api-documentation/#options-parameter) 选项。 详见链接. 使用时 `runOptions.rules` 结合 `disabledRules`, (中文(简体) ), **`disabledRules` 永远是先例.** ```jsx export const SomeStory = { parameters: { axe: { runOptions: { preload: true, selectors: true, ... } } } } ``` ### 上下文 [轴上下文](https://www.deque.com/axe/core-documentation/api-documentation/#context-parameter),然后转至 `axe.run`用于将元素纳入或排除于试验之外. ```jsx export const SomeStory = { parameters: { axe: { context: { exclude: '.foo', }, } } } ``` ### 配置 轴配置, 将传递到 [轴. 配置](https://www.deque.com/axe/core-documentation/api-documentation/#api-name-axeconfigure)。 。 。 . ```jsx export const SomeStory = { parameters: { axe: { config: { checks: [...], ... } } } } ``` ### 跳过 通过使用 `skip` 参数。 这是设置的缩写 `mode: 'off'`。 。 。 . ```jsx // SomeComponent.stories.jsx export const SomeStory = { parameters: { axe: { skip: true, }, }, }; ``` ### 超时 覆盖全球 `--timeout` 用于此特定测试 ```jsx // SomeComponent.stories.jsx export const SomeStory = { parameters: { axe: { timeout: 5000, }, }, }; ``` ### 等待选择器 **堕落了!** 在运行Axe之前等待选手的遗产方式. 现在我们建议用一本故事书 [播放函数](https://storybook.js.org/docs/react/writing-stories/play-function) 做同样的事情. ```jsx // SomeComponent.stories.jsx // Old, deprecated way. export const SomeStory = { parameters: { axe: { waitForSelector: '#some-component-selector', }, }, }; // New, better way using a play function - https://storybook.js.org/docs/react/writing-stories/play-function SomeStory.play = async () => { await screen.findByText('some string'); }; ``` ## 类型脚本 轴-故事本-测试为上述故事参数提供了TypeScript类型. 通过扩充"故事本"可以检查故事参数 `Parameter` 类型 : ```ts // overrides.d.ts import type { AxeParams } from '@chanzuckerberg/axe-storybook-testing'; declare module '@storybook/react' { // Augment Storybook's definition of Parameters so it contains valid options for axe-storybook-testing interface Parameters { axe?: AxeParams; } } ``` 记下你的故事 `StoryObj` 类型,您的参数将被选中 ! ```ts // SomeComponent.stories.ts export const SomeStory: StoryObj = { parameters: { axe: { timeout: 5000, }, }, }; ``` ## 发展中国家 如果你想在这个项目上工作 或为此作出贡献,请看我们 [维基百科中的相关条目: 开发设置](https://github.com/chanzuckerberg/axe-storybook-testing/wiki/Development-setup)。 。 。 . ## 警卫 要报告安全问题,请看 [/安全.md](https://npmcn.com/package/%40chanzuckerberg/axe-storybook-testing/SECURITY.md)。 。 。 . ## 灵感 这个项目最初的基础是: [@percy/故事书](https://github.com/percy/percy-storybook)。 。 。 . ## 常见问题 ### @chanzuckerberg/axe-storybook-testing 是什么？ \[\! ### 如何安装 @chanzuckerberg/axe-storybook-testing？ 在项目目录运行 npm install @chanzuckerberg/axe-storybook-testing，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：axe-core（^4\.0\.0）、storybook（^10\.0\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 axe-storybook，可以用 npx axe-storybook 直接运行。 ### @chanzuckerberg/axe-storybook-testing 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/chanzuckerberg\_\_axe-storybook-testing 是否存在。 ### @chanzuckerberg/axe-storybook-testing 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @chanzuckerberg/axe-storybook-testing 可以商用吗？ @chanzuckerberg/axe-storybook-testing 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @chanzuckerberg/axe-storybook-testing 的下载量有多少？ 根据 npm 官方下载统计，@chanzuckerberg/axe-storybook-testing 在 2026/10/10 – 2026/11/08 这 30 天内被下载 19,170 次，日均约 639 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @chanzuckerberg/axe-storybook-testing 还在维护吗？ 最新版本 10\.0\.0 发布于 2025/11/26（11 个月前）；至今共发布 47 个版本，其中过去 12 个月发布了 1 个；首次发布于 2020/09/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。