CCM-5339: add acceaaibility scanner with verified commits (#37)

Author: bhansell1

.devcontainer/Dockerfile

@@ -0,0 +1,6 @@
+FROM mcr.microsoft.com/devcontainers/jekyll:2-bullseye
+
+# Add dependencies required for pa11y-ci to execute inside of the devcontainer.
+RUN apt-get update \
+    && export DEBIAN_FRONTEND=noninteractive \
+    && apt-get -y install --no-install-recommends xorg openbox libnss3 libasound2 libatk-adaptor libgtk-3-0

.devcontainer/devcontainer.json

@@ -3,7 +3,9 @@
 {
   "name": "Jekyll",
   // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
-  "image": "mcr.microsoft.com/devcontainers/jekyll:2-bullseye",
+  "build": {
+    "dockerfile": "Dockerfile"
+  },
   // Features to add to the dev container. More info: https://containers.dev/features.
   // "features": {},
   // Use 'forwardPorts' to make a list of ports inside the container available locally.

.github/workflows/stage-4-acceptance.yaml

@@ -127,12 +127,35 @@ jobs:
     steps:
       - name: "Checkout code"
         uses: actions/checkout@v4
-      - name: "Run accessibility test"
-        run: |
-          make test-accessibility
-      - name: "Save result"
-        run: |
-          echo "Nothing to save"
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+      - run: npm ci
+        working-directory: './docs'
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@8575951200e472d5f2d95c625da0c7bec8217c42 # v1.161.0
+        with:
+          ruby-version: '3.1'
+          bundler-cache: true
+          cache-version: 0
+          working-directory: './docs'
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+        with:
+          working-directory: './docs'
+      - name: Build with Jekyll
+        working-directory: ./docs
+        run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
+        env:
+          JEKYLL_ENV: production
+      - name: Run accessibility test
+        run: make test-accessibility
+      - name: Archive accessibility results
+        uses: actions/upload-artifact@v4
+        with:
+          name: accessibility
+          path: "docs/.reports/accessibility"
   test-load:
     name: "Load test"
     runs-on: ubuntu-latest

.gitignore

@@ -13,3 +13,4 @@
 # Please, add your custom content below!
 
 !nhs-notify-web-cms.code-workspace
+.reports

docs/.pa11y-ci.js

@@ -0,0 +1,34 @@
+const fs = require('fs');
+const { XMLParser } = require('fast-xml-parser');
+
+const SITEMAP_PATH = './_site/sitemap.xml';
+
+function getUrlsFromSiteMap() {
+  const file = fs.readFileSync(SITEMAP_PATH, 'utf8').toString();
+
+  const sitemap = new XMLParser().parse(file);
+
+  return sitemap.urlset.url.map(r => r.loc);
+}
+
+module.exports = {
+  defaults: {
+    reporters: [
+      'cli',
+      [
+        'pa11y-ci-reporter-html',
+        {
+            destination: './.reports/accessibility',
+            includeZeroIssues: true
+        }
+      ],
+    ],
+    chromeLaunchConfig: {
+      args: ['--no-sandbox']
+    },
+    useIncognitoBrowserContext: false,
+    standard: 'WCAG2AA',
+    userAgent: 'pa11y-ci',
+  },
+  urls: getUrlsFromSiteMap()
+};;

docs/Gemfile

@@ -34,3 +34,5 @@ gem "wdm", "~> 0.1.1", :platforms => [:mingw, :x64_mingw, :mswin]
 gem "http_parser.rb", "~> 0.6.0", :platforms => [:jruby]
 
 gem "just-the-docs"
+
+gem "jekyll-sitemap", "~> 1.4"

docs/Gemfile.lock

@@ -46,6 +46,8 @@ GEM
       sass-embedded (~> 1.54)
     jekyll-seo-tag (2.8.0)
       jekyll (>= 3.8, < 5.0)
+    jekyll-sitemap (1.4.0)
+      jekyll (>= 3.7, < 5.0)
     jekyll-watch (2.2.1)
       listen (~> 3.0)
     just-the-docs (0.8.2)
@@ -80,9 +82,8 @@ GEM
       strscan (>= 3.0.9)
     rouge (4.2.1)
     safe_yaml (1.0.5)
-    sass-embedded (1.69.5)
+    sass-embedded (1.69.5-x86_64-linux-gnu)
       google-protobuf (~> 3.23)
-      rake (>= 13.0.0)
     strscan (3.1.0)
     terminal-table (3.0.2)
       unicode-display_width (>= 1.1.1, < 3)
@@ -97,6 +98,7 @@ DEPENDENCIES
   jekyll (~> 4.3.3)
   jekyll-drawio
   jekyll-feed (~> 0.12)
+  jekyll-sitemap (~> 1.4)
   just-the-docs
   minima (~> 2.5)
   tzinfo (>= 1, < 3)

docs/README.md

@@ -2,6 +2,8 @@
 
 ## Setup
 
+> For a non-technical approach read the instructions [here](../README.md).
+
 In the `docs` directory run the following command:
 
 ```bash
@@ -77,3 +79,17 @@ We have an assets folder which is used to put files such as;
 - CSS
 
 If you have new images, favicons or other assets place them in the corresponding folder and the asset will be available via `/assets/<assert_type>/<asset_name>` for example `/assets/images/landing-main-image.svg`.
+
+## Accessibility
+
+This project uses `pa11y-ci` which is a wrapper over the `pa11y` project. It allows us to run `pa11y` in the CI/CD pipeline more easily.
+
+To run an accessibility test ensure the web application in running by following the instruction in [Running the application](#running-the-application).
+
+Run the following command:
+
+```bash
+npm run test:accessibility
+```
+
+The accessibility results are output in both the terminal and in the following location `.reports/accessibility/index.html`.

docs/_config.yml

@@ -97,3 +97,6 @@ exclude:
   - pages/examples/
   - adr/
   - '*.component.md'
+
+plugins:
+  - jekyll-sitemap

docs/_layouts/page.html

@@ -47,8 +47,8 @@
             </nav>
           </div>
           <div class="nhsnotify-pane__main-content nhsuk-grid-column-three-quarters">
-            {% if page.section != "" %}
-              <h5 style="margin-bottom: 0; color: #4c6272">{{ page.section }}</h5>
+            {% if page.section != undefined %}
+            <p class="nhsuk-heading-s" style="margin-bottom: 0; color: #4c6272">{{ page.section }}</p>
             {% endif %}
             <h1>{{ page.title }}</h1>
             {{ content }}