@ code- pushup/ axe- 插件

🕵️ 用Axe进行自动化无障碍测试的代码PushUp插件. 🌐

该插件使用 轴核 通过 Playwright. 它确定 西非咨询组 最佳做法建议 100+无障碍度量衡 详细指导解决问题.

为什么无障碍测试很重要: 这个 欧洲无障碍法(EAA) 要求欧盟的数字产品和服务达到与《网络内容无障碍准则》紧密相通的无障碍标准。 这个插件提供全面的自动化测试,以帮助满足合规要求并积累包容性的经验.

开始

1. 如果还没有安装 @ code- pushup/ cli (英语) 并创建配置文件.

2. 用您的软件包管理器安装为 dev 依赖 :

   npm install --save-dev @code-pushup/axe-plugin
   

   yarn add --dev @code-pushup/axe-plugin
   

   pnpm add --save-dev @code-pushup/axe-plugin
   

3. 将此插件添加到 plugins 在代码 PushUp CLI 配置文件中的数组(例如 . code-pushup.config.ts) (中文(简体) ).

   通过您要测试的 URL :

   import axePlugin from '@code-pushup/axe-plugin';
   
   export default {
     // ...
     plugins: [
       // ...
       axePlugin('https://example.com'),
     ],
   };
   

   默认情况下,插件运行 2.1 AA级 审计。 您可以使用 预设。 。 。 .

4. 用 CLI 运行 CLI npx code-pushup collect 并查看或上传报告(参见 CLI 文档) (中文(简体) ).

   说明: 该插件使用Playwright在Chrimium运行测试. 浏览器如果尚未安装, 将自动安装 .

配置

axePlugin(urls: PluginUrls, options?: AxePluginOptions)

参数:

• urls - 要测试的 URL。 见 多个 URL 或 PluginUrls 参考文献
• options - 可选配置对象

选项 :

见 预设 财务报告和审定财务报表 认证 下节.

多个 URL

该插件支持测试单个或多个 URL :

// Single URL (string)
axePlugin('https://example.com');

// Multiple URLs (array)
axePlugin(['https://example.com', 'https://example.com/about']);

// Weighted URLs (record)
axePlugin({
  'https://example.com': 3, // homepage has 3x weight
  'https://example.com/about': 1, // about page has 1x weight
});

权重较高的URL对总体分数的贡献更大. 例如,有重3的URL具有有重1的URL的三倍影响.

认证

要测试登录保护的页面,请提供 setupScript 分析前的认证:

axePlugin('https://example.com/dashboard', {
  setupScript: './axe-setup.ts',
});

设置脚本必须导出接收 Playwright 的默认async 函数 Page 实例:

// axe-setup.ts
import type { Page } from 'playwright-core';

export default async function (page: Page): Promise<void> {
  await page.goto('https://example.com/login');
  await page.fill('#username', process.env.USERNAME);
  await page.fill('#password', process.env.PASSWORD);
  await page.click('button[type="submit"]');
  await page.waitForURL('**/dashboard');
}

脚本在分析 URL 之前运行过一次. 认证状态(cookies, localStorage)在所有 URL 分析中自动共享.

// axe-setup.ts
import type { Page } from 'playwright-core';

export default async function (page: Page): Promise<void> {
  await page.context().addCookies([
    {
      name: 'session_token',
      value: process.env.SESSION_TOKEN,
      domain: 'example.com',
      path: '/',
    },
  ]);
}

预设

选择用于测试的可访问性规则 preset 选项 :

axePlugin('https://example.com', {
  preset: 'wcag22aa',
});

可用的预设 :

预设细节

wcag21aa (默认)

• 测试遵守情况 2.1 A级和AA级
• 所需经费 欧洲无障碍法(EAA) 遵守情况
• 封面基本内容:键盘导航,相色对比,形式标签,备选案文等.

wcag22aa

• 测试遵守情况 WCAG 2.2 A级和AA级
• 包括所有WCAG 2.1规则和新的成功标准
• 为即将出台的条例提供未来保护

best-practice

• Deque Systems的非WCAG建议
• 超越法律要求
• 有助于创造更具包容性的经验

all

• 运行轴核中可用的每个规则
• 包括WCAG 2.0、2.1、2.2、实验规则和最佳做法
• 最全面的测试

说明: 不同的页面可能会根据内容触发不同的套规则. 例如,没有视频的一页不会进行视频相关审计.

组

该插件根据轴-核心的可访问性类别将审计组织成类别:

• aria -亚里雅
• color - 颜色对比度( C)
• forms - 表单
• keyboard - 键盘
• language - 语言
• name-role-value - 名称和标签
• parsing - 剖析
• semantics - 语义学
• sensory-and-visual-cues - 视觉库斯
• structure - 结构
• tables - 表单
• text-alternatives - 替代文本
• time-and-media - 媒体

使用 npx code-pushup print-config --onlyPlugins=axe 为您的配置列出所有审计和组.

类别整合

该插件提供了帮助将 Axe 结果整合到您的分类中 .

配备参考助手的建筑类别

使用 axeGroupRefs 财务报告和审定财务报表 axeAuditRefs 用于构建类别。 这些帮助者自动处理多URL扩展 :

import axePlugin, { axeGroupRefs } from '@code-pushup/axe-plugin';

const axe = axePlugin('https://example.com');

export default {
  plugins: [axe],
  categories: [
    {
      slug: 'a11y',
      title: 'Accessibility',
      refs: axeGroupRefs(axe),
    },
  ],
};

对于多URL设置,每个URL的参考器会自动扩展,并附带适当的权重:

import axePlugin, { axeGroupRefs } from '@code-pushup/axe-plugin';

const axe = axePlugin({
  'https://example.com': 2,
  'https://example.com/about': 1,
});

export default {
  plugins: [axe],
  categories: [
    {
      slug: 'a11y',
      title: 'Accessibility',
      refs: axeGroupRefs(axe),
    },
  ],
};

自定义带有特定组的类别

对于精细控制,请指定哪些组包括:

import axePlugin, { axeGroupRefs } from '@code-pushup/axe-plugin';

const axe = axePlugin('https://example.com');

export default {
  plugins: [axe],
  categories: [
    {
      slug: 'a11y',
      title: 'Accessibility',
      refs: [...axeGroupRefs(axe, 'aria', 2), ...axeGroupRefs(axe, 'color'), ...axeGroupRefs(axe, 'keyboard')],
    },
  ],
};

与灯塔结合

为全面无障碍测试,将Axe和Lighthouse的无障碍组合并成一个单一类别:

import axePlugin, { axeGroupRefs } from '@code-pushup/axe-plugin';
import lighthousePlugin, { lighthouseGroupRefs } from '@code-pushup/lighthouse-plugin';

const urls = ['https://example.com', 'https://example.com/about'];
const axe = axePlugin(urls);
const lighthouse = await lighthousePlugin(urls);

export default {
  plugins: [axe, lighthouse],
  categories: [
    {
      slug: 'a11y',
      title: 'Accessibility',
      refs: [...lighthouseGroupRefs(lighthouse, 'accessibility'), ...axeGroupRefs(axe)],
    },
  ],
};

这给了你们两个灯塔的注重性能的无障碍审计和Axe的WCAG全面覆盖一个类别分数.

辅助功能

[TIP] 重量决定每个裁判对类别分数的影响. 使用重量 0 在不影响分数的情况下,只将一个参考者列为信息.

类型安全

这个 AxeGroupSlug 类型导出以发现有效的组 satters :

import type { AxeGroupSlug } from '@code-pushup/axe-plugin';

const group: AxeGroupSlug = 'aria';

贬值的帮助者

下列帮助者被贬值,并将在未来版本被删除:

资源

• 轴心规则 - 无障碍规则完整清单
• 德克大学 详细解释和补救指南
• WCAG 准则 - 网络内容无障碍准则