[SPIKE] Check all pages' accessibility

__tests__/accessibility-audit.test.js

@@ -1,64 +1,129 @@
 const { AxePuppeteer } = require('@axe-core/puppeteer')
+const { globSync } = require('glob')
+const slash = require('slash')
 
+const { paths } = require('../config')
 const { goTo } = require('../lib/puppeteer-helpers.js')
 
-async function analyze(page, path) {
-  await goTo(page, path)
-
-  const axe = new AxePuppeteer(page)
+/**
+ * Axe Puppeteer reporter
+ *
+ * @param {import('puppeteer').Page} page - Puppeteer page object
+ * @returns {Promise<import('axe-core').AxeResults>} Axe Puppeteer instance
+ */
+async function axe(page) {
+  const reporter = new AxePuppeteer(page)
     .include('body')
-    // axe reports there is "no label associated with the text field", when there is one.
-    .exclude('#app-site-search__input')
-    // axe reports that the phase banner is not inside a landmark, which is intentional.
-    .exclude('.app-phase-banner')
-    // axe reports that the skip link is not inside a landmark, which is intentional.
-    // https://design-system.service.gov.uk/components/skip-link/#when-to-use-this-component
-    .exclude('.govuk-skip-link')
-    // axe reports that the back to top button is not inside a landmark, which is intentional.
-    .exclude('.app-back-to-top')
-    // axe reports that the Browsersync banner is not inside a landmark, which is intentional.
-    .exclude('#__bs_notify__')
-    // axe reports that the frame "does not have a main landmark" and example <h1> headings
-    // violate "Heading levels should only increase by one", which is intentional.
-    // https://github.com/alphagov/govuk-design-system/pull/2442#issuecomment-1326600528
-    .exclude('.app-example__frame')
-
-  return axe.analyze()
-}
+    .exclude(
+      // Axe reports that the phase banner is not inside a landmark, which is intentional.
+      '.app-phase-banner'
+    )
+    .exclude(
+      // Axe reports that the skip link is not inside a landmark, which is intentional.
+      // https://design-system.service.gov.uk/components/skip-link/#when-to-use-this-component
+      '.govuk-skip-link'
+    )
+    .exclude(
+      // Axe reports that the back to top button is not inside a landmark, which is intentional.
+      '.app-back-to-top'
+    )
+    .exclude(
+      // Axe reports that the Browsersync banner is not inside a landmark, which is intentional.
+      '#__bs_notify__'
+    )
+    .exclude(
+      // Axe reports that the frame "does not have a main landmark" and example <h1> headings
+      // violate "Heading levels should only increase by one", which is intentional.
+      // https://github.com/alphagov/govuk-design-system/pull/2442#issuecomment-1326600528
+      // Additionally, we are relying on accessibility testing in govuk-frontend to cover these.
+      '.app-example__frame'
+    )
 
-describe('Accessibility Audit', () => {
-  describe('Home page - layout.njk', () => {
-    it('validates', async () => {
-      const results = await analyze(page, '/')
-      expect(results).toHaveNoViolations()
-    })
-  })
+    // TODO: govuk-breadcrumbs sets off the "must be contained in landmarks" rule. Needs investigation.
+    .exclude('.govuk-breadcrumbs')
 
-  describe('Component page - layout-pane.njk', () => {
-    it('validates', async () => {
-      const results = await analyze(page, '/components/radios/')
-      expect(results).toHaveNoViolations()
-    })
-  })
+    // TODO: figure out how and whether to re-enable these rules, or target them better
+    .disableRules([
+      'region',
+      'color-contrast-enhanced',
+      'aria-allowed-attr',
+      'target-size'
+    ])
 
-  describe('Patterns page - layout-pane.njk', () => {
-    it('validates', async () => {
-      const results = await analyze(page, '/patterns/gender-or-sex/')
-      expect(results).toHaveNoViolations()
-    })
-  })
+    .withTags([
+      'best-practice',
+
+      // WCAG 2.x
+      'wcag2a',
+      'wcag2aa',
+      'wcag2aaa',
+
+      // WCAG 2.1
+      'wcag21a',
+      'wcag21aa',
+
+      // WCAG 2.2
+      'wcag22aa'
+    ])
+
+  // Create report
+  const report = await reporter.analyze()
 
-  describe('Get in touch page - layout-single-page.njk', () => {
-    it('validates', async () => {
-      const results = await analyze(page, '/get-in-touch/')
-      expect(results).toHaveNoViolations()
-    })
+  // Add preview URL to report violations
+  report.violations.forEach((violation) => {
+    violation.helpUrl = `${violation.helpUrl}\n${page.url()}`
   })
 
-  describe('Site Map page - layout-sitemap.njk', () => {
-    it('validates', async () => {
-      const results = await analyze(page, '/sitemap/')
-      expect(results).toHaveNoViolations()
-    })
+  return report
+}
+
+// TODO: Didn't feel like spending ages working out the perfect glob, so have split these out.
+//
+// The idea here is to reduce the time taken by only checking the main index of the component pages,
+// rather than checking each example as well, since they're present on the main index in iframes.
+//
+// This assumes that the examples are well checked for accessibility since they're basically just
+// govuk-frontend components.
+//
+// Even then, though, some of them feature custom html and such from the site itself, so we might
+// decide to suck it up and audit EVERYTHING, and have to decide how to fix the issues that come up
+// here.
+//
+// Possibly the ideal solution is to split the components and "other" pages, and set up a
+// few different checks (with different rules due to the different nature of the content):
+// - Check everything
+// - Check component pages
+// - Check content pages
+// - Github script that only checks files that have been edited and flags 'em in a comment
+//
+// So you can choose to run the full, lengthy check, but it wouldn't run on Github, so our
+// deploy times wouldn't be seriously affected.
+function getFilesToCheck() {
+  const componentIndexes = globSync('components/*{,/*}.html', {
+    cwd: paths.public
+  })
+  const patternIndexes = globSync('patterns/*{,/*}.html', {
+    cwd: paths.public
   })
+  const pageIndexes = globSync('**/index.html', {
+    cwd: paths.public,
+    ignore: ['components/**/index.html', 'patterns/*{,/*}.html']
+  })
+
+  return [...componentIndexes, ...patternIndexes, ...pageIndexes]
+}
+
+describe('Accessibility audit', () => {
+  it.each(getFilesToCheck())(
+    'validates %s',
+    async (path) => {
+      const page = await browser.newPage()
+
+      await goTo(page, `/${slash(path)}`)
+      await expect(axe(page)).resolves.toHaveNoViolations()
+
+      await page.close()
+    },
+    10000
+  )
 })

jest-puppeteer.config.js

@@ -10,12 +10,23 @@ module.exports = {
    * Puppeteer launch options
    */
   launch: {
+    args: [
+      /**
+       * Prevent empty Chrome startup window
+       * Tests use their own `browser.newPage()` instead
+       */
+      '--no-startup-window'
+    ],
+
     /**
      * Allow headless mode switching using `HEADLESS=false`
      *
      * {@link https://developer.chrome.com/articles/new-headless/}
      */
-    headless: process.env.HEADLESS !== 'false'
+    headless: process.env.HEADLESS !== 'false',
+
+    // See launch arg '--no-startup-window'
+    waitForInitialPage: false
   },
 
   /**
@@ -25,6 +36,9 @@ module.exports = {
     command: 'npm run serve',
     port: ports.preview,
 
+    // Allow 30 seconds to start server
+    launchTimeout: 30000,
+
     // Skip when already running
     usedPortAction: 'ignore'
   }

src/accessibility/index.md

@@ -9,10 +9,10 @@ Our work to make the GOV.UK Design System meet public sector accessibility regul
 
 Using the GOV.UK Design System in a service does not immediately make that service accessible. You’ll need additional research, design, development and testing work to make sure your service is accessible, even when using accessible styles, components and patterns.
 
-### Accessibility changes to the Design System to meet WCAG 2.2
+## Accessibility changes to the Design System to meet WCAG 2.2
 
 [Read our guidance on the Web Content Accessibility Guidelines (WCAG) 2.2](/accessibility/wcag-2.2) to make sure teams using the Design System are aware of the changes and can make the necessary adjustments to their services.
 
-### Accessibility strategy
+## Accessibility strategy
 
 [Read our accessibility strategy](/accessibility/accessibility-strategy/) for more information on our current principles and work needed to improve the accessibility of the GOV.UK Design System.

src/accessibility/wcag-2.2/index.md

@@ -15,11 +15,11 @@ In 2023, the Design System team assessed and updated the GOV.UK Design System to
 
 We [included code changes in GOV.UK Frontend v5.0.0](https://frontend.design-system.service.gov.uk/changes-to-govuk-frontend-v5/) to make it easier for services to make changes to comply with WCAG 2.2. We also added guidance to make teams aware of the changes and help them make necessary adjustments to their services.
 
-### Make sure your service meets the new WCAG 2.2 criteria
+## Make sure your service meets the new WCAG 2.2 criteria
 
 WCAG 2.2 was published in October 2023. You’ll need to comply with the new criteria no later than October 2024. See more about [Meeting government accessibility requirements](https://www.gov.uk/service-manual/helping-people-to-use-your-service/understanding-wcag) in the GOV.UK Service Manual.
 
-### What you need to do
+## What you need to do
 
 1. Revisit the [Government Digital Service (GDS) guidance](https://www.gov.uk/guidance/accessibility-requirements-for-public-sector-websites-and-apps) on what accessibility is and why your service needs to invest in it
 2. Read [What’s new in WCAG 2.2](https://www.w3.org/WAI/standards-guidelines/wcag/new-in-22/) to understand the new criteria your service will need to comply with
@@ -31,7 +31,7 @@ WCAG 2.2 was published in October 2023. You’ll need to comply with the new cri
 
 Make sure there's expertise within your organisation by advocating for people to receive training in accessibility. To provide some help with this, the Design System team is [organising community events](/community/) to help service teams share information with each other.
 
-### Components and patterns affected in the Design System
+## Components and patterns affected in the Design System
 
 We've made changes to these components and patterns to comply with WCAG 2.2 level AA. You must check if your service needs amending to align with these changes.
 

src/components/accordion/index.md

@@ -123,7 +123,7 @@ We updated this component in December 2021 to solve an accessibility issue where
 
 The team made sure the component is accessible, for example that users can interact with it using just the keyboard.
 
-#### Users that navigate using ‘elements lists’
+### Users that navigate using ‘elements lists’
 
 We need to find out more about users that navigate using ‘elements lists’ of headings, buttons, links and other elements – such as users of speech recognition software and partially-sighted users of screen readers.
 

src/components/back-link/index.md

@@ -20,7 +20,7 @@ Use the back link component to help users go back to the previous page in a mult
   classes: "app-tag"
 }) }}
 
-### New WCAG 2.2 criteria affect this component
+## New WCAG 2.2 criteria affect this component
 
 To use the ‘Back link’ and comply with new success criteria introduced in Web Content Accessibility Guidelines (WCAG) 2.2, make sure that users can successfully:
 

src/components/breadcrumbs/index.md

@@ -20,7 +20,7 @@ The breadcrumbs component helps users to understand where they are within a webs
   classes: "app-tag"
 }) }}
 
-### New WCAG 2.2 criteria affect this component
+## New WCAG 2.2 criteria affect this component
 
 To use ‘Breadcrumbs' and meet the new Web Content Accessibility Guidelines (WCAG) 2.2 criteria, make sure that users can successfully:
 

src/components/button/index.md

@@ -18,7 +18,7 @@ layout: layout-pane.njk
   classes: "app-tag"
 }) }}
 
-### New WCAG 2.2 criteria affect this component
+## New WCAG 2.2 criteria affect this component
 
 To use the ‘Button' and meet the new Web Content Accessibility Guidelines (WCAG) 2.2 criteria, make sure that users can successfully:
 

src/components/cookie-banner/index.md

@@ -20,7 +20,7 @@ Allow users to accept or reject cookies which are not essential to making your s
   classes: "app-tag"
 }) }}
 
-### New WCAG 2.2 criteria affect this component
+## New WCAG 2.2 criteria affect this component
 
 To use the ‘Cookie banner' and meet the new Web Content Accessibility Guidelines (WCAG) 2.2 criteria, make sure that users can successfully:
 

src/components/error-message/index.md

@@ -20,7 +20,7 @@ This guidance is for government teams that build online services. [To find infor
   classes: "app-tag"
 }) }}
 
-### New WCAG 2.2 criteria affect this component
+## New WCAG 2.2 criteria affect this component
 
 To use the ‘Error message' and meet the new Web Content Accessibility Guidelines (WCAG) 2.2 criteria, make sure that users can successfully:
 

src/components/file-upload/index.md

@@ -20,7 +20,7 @@ This guidance is for government teams that build online services. [To find infor
   classes: "app-tag"
 }) }}
 
-### New WCAG 2.2 criteria affect this component
+## New WCAG 2.2 criteria affect this component
 
 To use the ‘File upload' and meet the new Web Content Accessibility Guidelines (WCAG) 2.2 criteria, make sure that users can successfully:
 

src/components/footer/index.md

@@ -20,7 +20,7 @@ The footer provides copyright, licensing and other information about your servic
   classes: "app-tag"
 }) }}
 
-### New WCAG 2.2 criteria affect this component
+## New WCAG 2.2 criteria affect this component
 
 To use the ‘Footer' and meet the new Web Content Accessibility Guidelines (WCAG) 2.2 criteria, make sure that users can successfully:
 

src/components/header/index.md

@@ -19,7 +19,7 @@ The GOV.UK header shows users that they are on GOV.UK and which service they are
   classes: "app-tag"
 }) }}
 
-### New WCAG 2.2 criteria affect this component
+## New WCAG 2.2 criteria affect this component
 
 To use the ‘Header' and meet the new Web Content Accessibility Guidelines (WCAG) 2.2 criteria, make sure that users can successfully:
 

src/components/password-input/index.md

@@ -20,7 +20,7 @@ Help users to create and enter passwords.
   classes: "app-tag"
 }) }}
 
-### New WCAG 2.2 criteria affect this component
+## New WCAG 2.2 criteria affect this component
 
 To use the ‘Password input’ and meet the new Web Content Accessibility Guidelines (WCAG) 2.2 criteria, make sure that users can successfully:
 

src/components/phase-banner/index.md

@@ -20,7 +20,7 @@ Use the phase banner component to show users your service is still being worked
   classes: "app-tag"
 }) }}
 
-### New WCAG 2.2 criteria affect this component
+## New WCAG 2.2 criteria affect this component
 
 To use the ‘Phase banner' and meet the new Web Content Accessibility Guidelines (WCAG) 2.2 criteria, make sure that users can successfully:
 

src/components/select/index.md

@@ -18,7 +18,7 @@ layout: layout-pane.njk
   classes: "app-tag"
 }) }}
 
-### New WCAG 2.2 criteria affect this component
+## New WCAG 2.2 criteria affect this component
 
 To use the ‘Select' and meet the new Web Content Accessibility Guidelines (WCAG) 2.2 criteria, make sure that users can successfully:
 

src/components/summary-list/index.md

@@ -20,7 +20,7 @@ Use a summary list to summarise information, for example, a user’s responses a
   classes: "app-tag"
 }) }}
 
-### WCAG 2.2 criteria might affect this component
+## WCAG 2.2 criteria might affect this component
 
 To use ‘Summary list’ and comply with new success criteria introduced in Web Content Accessibility Guidelines (WCAG) 2.2, make sure that users can successfully:
 

src/components/tag/index.md

@@ -20,7 +20,7 @@ Use the tag component to show users the status of something.
   classes: "app-tag"
 }) }}
 
-### New WCAG 2.2 criteria affect this component
+## New WCAG 2.2 criteria affect this component
 
 To use the ‘Tag' and meet the new Web Content Accessibility Guidelines (WCAG) 2.2 criteria, make sure that users can successfully:
 

src/design-system-team.md

@@ -12,15 +12,15 @@ The GOV.UK Design System at the [Government Digital Service](https://www.gov.uk/
 
 If you want to contact the team you can [get in touch via email or Slack](/get-in-touch/).
 
-### Team leads
+## Team leads
 
 - Charlotte Downs – Senior Interaction Designer
 - Kelly Lee – Senior Delivery Manager
 - Oliver Byford – Lead Frontend Developer
 - Romaric Pascal – Senior Frontend Developer
 - Trang Erskine – Senior Product Manager
 
-### Design System team
+## Design System team
 
 - Anika Henke – Senior Accessibility Specialist
 - Brett Kyle – Senior Frontend Developer