Skip to content

Commit 066a1f5

Browse files
hanna-skrylhanna-skryl
committed
docs(plugin-axe): add README and plugin metadata
1 parent ecf9e21 commit 066a1f5

File tree

2 files changed

+173
-4
lines changed

2 files changed

+173
-4
lines changed

‎packages/plugin-axe/README.md‎

Lines changed: 170 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,173 @@
1-
# plugin-axe
1+
# @code-pushup/plugin-axe
22

3-
This library was generated with [Nx](https://nx.dev).
3+
🕵️ **Code PushUp plugin for automated accessibility testing with Axe.** 🌐
44

5-
## Running unit tests
5+
---
66

7-
Run `nx test plugin-axe` to execute the unit tests via [Vitest](https://vitest.dev/).
7+
The plugin runs accessibility audits on web pages using [axe-core](https://github.com/dequelabs/axe-core) via Playwright. It identifies [WCAG](https://www.w3.org/WAI/standards-guidelines/wcag/) violations and best practice recommendations, providing **100+ accessibility metrics** with detailed guidance for fixing problems.
8+
9+
**Why accessibility testing matters:** The [European Accessibility Act (EAA)](https://ec.europa.eu/social/main.jsp?catId=1202) requires digital products and services in the EU to meet accessibility standards closely aligned with the Web Content Accessibility Guidelines (WCAG). This plugin provides comprehensive automated testing to help meet compliance requirements and build inclusive experiences.
10+
11+
## Getting started
12+
13+
1. If you haven't already, install [@code-pushup/cli](../cli/README.md) and create a configuration file.
14+
15+
2. Install as a dev dependency with your package manager:
16+
17+
```sh
18+
npm install --save-dev @code-pushup/plugin-axe
19+
```
20+
21+
```sh
22+
yarn add --dev @code-pushup/plugin-axe
23+
```
24+
25+
```sh
26+
pnpm add --save-dev @code-pushup/plugin-axe
27+
```
28+
29+
3. Add this plugin to the `plugins` array in your Code PushUp CLI config file (e.g. `code-pushup.config.ts`).
30+
31+
Pass in the URL you want to test:
32+
33+
```ts
34+
import axePlugin from '@code-pushup/plugin-axe';
35+
36+
export default {
37+
// ...
38+
plugins: [
39+
// ...
40+
axePlugin('https://example.com'),
41+
],
42+
};
43+
```
44+
45+
By default, the plugin runs **WCAG 2.1 Level AA** audits. You can customize this using [presets](#presets).
46+
47+
4. Run the CLI with `npx code-pushup collect` and view or upload the report (refer to [CLI docs](../cli/README.md)).
48+
49+
## Configuration
50+
51+
```ts
52+
axePlugin(urls: PluginUrls, options?: AxePluginOptions)
53+
```
54+
55+
**Parameters:**
56+
57+
- `urls` - URL(s) to test. See [Multiple URLs](#multiple-urls) section below, or [`PluginUrls`](../../packages/models/docs/models-reference.md#pluginurls) reference
58+
- `options` - Optional configuration object
59+
60+
**Options:**
61+
62+
| Property | Type | Default | Description |
63+
| -------------- | ----------- | ------------ | ----------------------------------------- |
64+
| `preset` | `AxePreset` | `'wcag21aa'` | Accessibility ruleset preset |
65+
| `scoreTargets` | `object` | `undefined` | Pass/fail thresholds for audits or groups |
66+
67+
See [Presets](#presets) section for available preset values and details.
68+
69+
## Multiple URLs
70+
71+
The plugin supports testing single or multiple URLs:
72+
73+
```ts
74+
// Single URL (string)
75+
axePlugin('https://example.com');
76+
77+
// Multiple URLs (array)
78+
axePlugin(['https://example.com', 'https://example.com/about']);
79+
80+
// Weighted URLs (record)
81+
axePlugin({
82+
'https://example.com': 3, // homepage has 3x weight
83+
'https://example.com/about': 1, // about page has 1x weight
84+
});
85+
```
86+
87+
URLs with higher weights contribute more to overall scores. For example, a URL with weight 3 has three times the influence of a URL with weight 1.
88+
89+
## Presets
90+
91+
Choose which accessibility ruleset to test against using the `preset` option:
92+
93+
```ts
94+
axePlugin('https://example.com', {
95+
preset: 'wcag22aa',
96+
});
97+
```
98+
99+
Available presets:
100+
101+
| Preset | Description | Use case |
102+
| --------------- | --------------------------------------------- | ------------------------------------- |
103+
| `wcag21aa` | **WCAG 2.1 Level A and AA** (default) | Standard web accessibility compliance |
104+
| `wcag22aa` | **WCAG 2.2 Level A and AA** | Latest WCAG standard |
105+
| `best-practice` | **Best practices** (non-WCAG recommendations) | Deque's additional recommendations |
106+
| `all` | **All available rules** | Comprehensive testing |
107+
108+
### Preset details
109+
110+
**`wcag21aa`** (default)
111+
112+
- Tests compliance with [WCAG 2.1 Level A and Level AA](https://www.w3.org/WAI/WCAG21/quickref/?currentsidebar=%23col_overview&levels=a%2Caaa)
113+
- Required for [European Accessibility Act (EAA)](https://ec.europa.eu/social/main.jsp?catId=1202) compliance
114+
- Covers fundamentals: keyboard navigation, color contrast, form labels, alt text, etc.
115+
116+
**`wcag22aa`**
117+
118+
- Tests compliance with [WCAG 2.2 Level A and Level AA](https://www.w3.org/WAI/WCAG22/quickref/?currentsidebar=%23col_overview&levels=a%2Caaa)
119+
- Includes all WCAG 2.1 rules plus new success criteria
120+
- Future-proof for upcoming regulations
121+
122+
**`best-practice`**
123+
124+
- Non-WCAG recommendations from Deque Systems
125+
- Goes beyond legal requirements
126+
- Helps create more inclusive experiences
127+
128+
**`all`**
129+
130+
- Runs every rule available in axe-core
131+
- Includes WCAG 2.0, 2.1, 2.2, experimental rules, and best practices
132+
- Most comprehensive testing
133+
134+
> **Note:** Different pages may trigger different sets of rules depending on their content. For example, a page without video won't run video-related audits.
135+
136+
### Groups
137+
138+
The plugin automatically creates groups to organize audits:
139+
140+
**WCAG presets** (`wcag21aa`, `wcag22aa`):
141+
142+
- `wcag21-level-a` - WCAG 2.1 Level A audits
143+
- `wcag21-level-aa` - WCAG 2.1 Level AA audits
144+
- `wcag22-level-a` - WCAG 2.2 Level A audits (wcag22aa only)
145+
- `wcag22-level-aa` - WCAG 2.2 Level AA audits (wcag22aa only)
146+
147+
**Best practice preset** (`best-practice`):
148+
149+
- `aria` - ARIA
150+
- `color` - Color & Contrast
151+
- `forms` - Forms
152+
- `keyboard` - Keyboard
153+
- `language` - Language
154+
- `name-role-value` - Names & Labels
155+
- `parsing` - Parsing
156+
- `semantics` - Semantics
157+
- `sensory-and-visual-cues` - Visual Cues
158+
- `structure` - Structure
159+
- `tables` - Tables
160+
- `text-alternatives` - Text Alternatives
161+
- `time-and-media` - Media
162+
163+
**All preset** (`all`):
164+
165+
- Combines all WCAG groups and best practice category groups
166+
167+
Use `npx code-pushup print-config --onlyPlugins=axe` to list all audits and groups for your configuration.
168+
169+
## Resources
170+
171+
- **[Axe-core rules](https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md)** - Complete list of accessibility rules
172+
- **[Deque University](https://dequeuniversity.com/rules/axe/)** - Detailed explanations and remediation guidance
173+
- **[WCAG Guidelines](https://www.w3.org/WAI/standards-guidelines/wcag/)** - Web Content Accessibility Guidelines

‎packages/plugin-axe/src/lib/axe-plugin.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,9 @@ export function axePlugin(
3838
version: packageJson.version,
3939
title: 'Axe Accessibility',
4040
icon: 'folder-syntax',
41+
description:
42+
'Official Code PushUp Axe plugin for automated accessibility testing',
43+
docsUrl: 'https://www.npmjs.com/package/@code-pushup/axe-plugin',
4144
audits,
4245
groups,
4346
runner: createRunnerFunction(normalizedUrls, ruleIds),

0 commit comments

Comments
 (0)