feat: integrate accessibility testing with pa11y-ci

eleventy.config.js

@@ -112,6 +112,11 @@ export default async function (eleventyConfig) {
     'node_modules/lite-youtube-embed/src/lite-yt-embed.{css,js}': `assets/components/`
   });
 
+  // ----------------------  ignore test files
+  if (process.env.ELEVENTY_ENV != 'test') {
+    eleventyConfig.ignores.add('src/common/pa11y.njk');
+  }
+
   // --------------------- general config
   return {
     markdownTemplateEngine: 'njk',

package.json

@@ -17,7 +17,11 @@
     "dev:11ty": "cross-env ELEVENTY_ENV=development eleventy --serve",
     "build:11ty": "cross-env ELEVENTY_ENV=production eleventy",
     "start": "npm run dev:11ty",
-    "build": "npm run clean && npm run build:11ty"
+    "build": "npm run clean && npm run build:11ty",
+    "pa11y:build": "npm run clean && cross-env ELEVENTY_ENV=test eleventy",
+    "pa11y:test": "sleep 3 && pa11y-ci --config ./dist/pa11y.json",
+    "pa11y:serve": "ELEVENTY_ENV=test eleventy --serve --ignore-initial",
+    "test:a11y": "npm run pa11y:build && (npm run pa11y:serve &) && sleep 5 && npm run pa11y:test"
   },
   "keywords": [],
   "repository": {
@@ -57,6 +61,7 @@
     "markdown-it-mark": "^4.0.0",
     "markdown-it-prism": "^3.0.0",
     "netlify-plugin-cache": "^1.0.3",
+    "pa11y-ci": "^4.0.1",
     "postcss": "^8.5.6",
     "postcss-cli": "^11.0.1",
     "postcss-import": "^16.1.1",

src/_data/meta.js

@@ -89,6 +89,13 @@ export const greenweb = {
   ],
   services: [{domain: 'netlify.com', serviceType: 'cdn'}]
 };
+export const tests = {
+  pa11y: {
+    // keep customPaths empty if you want to test all pages
+    customPaths: ['/', '/about/', '/blog/', '/styleguide/'],
+    globalIgnore: []
+  }
+};
 export const viewRepo = {
   // this is for the view/edit on github link. The value in the package.json will be pulled in.
   allow: true,

src/common/pa11y.njk

@@ -0,0 +1,52 @@
+---
+eleventyExcludeFromCollections: true
+layout: false
+permalink: "pa11y.json"
+---
+
+{#
+  Generates pa11y accessibility test config in test environment.
+  Tests all pages by default, or custom paths if defined in meta.tests.pa11y.customPaths
+#}
+{%- set useCustomPaths = meta.tests.pa11y.customPaths and meta.tests.pa11y.customPaths.length > 0 -%}
+
+{%- if useCustomPaths -%}
+  {%- set urls = [] -%}
+  {%- for path in meta.tests.pa11y.customPaths -%}
+    {%- set url = 'http://localhost:8080' + path -%}
+    {%- set pageData = null -%}
+    {%- for page in collections.all -%}
+      {%- if page.url == path -%}
+        {%- set pageData = page.data -%}
+      {%- endif -%}
+    {%- endfor -%}
+    {%- set urls = (urls.push({
+      url: url,
+      ignore: pageData.pa11yIgnore or []
+    }), urls) -%}
+  {%- endfor -%}
+{%- else -%}
+  {%- set urls = [] -%}
+  {%- for page in collections.showInSitemap -%}
+    {%- if page.url and page.data.excludeFromSitemap != true and page.url.startsWith('/') -%}
+      {%- set url = 'http://localhost:8080' + page.url -%}
+      {%- set urls = (urls.push({
+        url: url,
+        ignore: page.data.pa11yIgnore or []
+      }), urls) -%}
+    {%- endif -%}
+  {%- endfor -%}
+{%- endif -%}
+
+{%- set config = {
+  defaults: {
+    standard: "WCAG2AA",
+    timeout: 10000,
+    ignore: meta.tests.pa11y.globalIgnore or [],
+    chromeLaunchConfig: {
+      args: ["--no-sandbox", "--disable-setuid-sandbox"]
+    }
+  },
+  urls: urls
+} -%}
+{{- config | dump(2) | safe }}

src/docs/tests.md

@@ -0,0 +1,30 @@
+---
+title: Tests
+---
+
+You can run local automated accessibility tests with [pa11y-ci](https://github.com/pa11y/pa11y-ci).
+
+`src/common/pa11y.njk` generates a _pa11y-ci_ config file for all pages in the sitemap by default. You can also define custom paths to test in `src/_data/meta.js`, whithin `tests.pa11y.customPaths`.
+
+To run the tests, use the following command:
+
+```bash
+npm run test:a11y
+```
+
+This command will:
+1. Build the site in test environment
+2. Start a preview server on `localhost:8080`
+3. Run `pa11y-ci` accessibility tests against all pages in the sitemap, or the custom paths.
+
+### Ignoring Rules
+
+To ignore specific rules, you can add them to the front matter of a template:
+
+```yaml
+pa11yIgnore:
+  - "WCAG2AA.Principle1.Guideline1_4.1_4_3.G145.Fail"
+  - "WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail"
+```
+
+or globally in `src/_data/meta.js`, within `tests.pa11y.globalIgnore`.