Running the checks

Page content:

postdoc test checks your site the way you check your code. It builds the site, opens every page in a real browser, runs accessibility checks on it and tries it the way people with different needs use it, with no test files to write. Your own Nightwatch tests run first, and the page checks after them, and the command fails when a check or a test fails, so it fits straight into CI.

Set up

postdoc test runs Nightwatch from your project, along with the Nightwatch plugin for Postdoc, which runs your page tests. Projects created with postdoc init already have both; otherwise install them:

sh
npm install --save-dev nightwatch nightwatch-plugin-postdoc

Nightwatch has to be version 3.15 or newer. Another package can bring in Nightwatch 2, which postdoc test won't run: install version 3 in the project.

You also need the browser itself, Chrome by default. Nightwatch downloads the matching driver on the first run.

Run the checks

sh
npx postdoc test

The command:

  1. builds the site into the output folder, as postdoc build does
  2. serves the build on a free port
  3. opens each page, waits until it has finished rendering, and checks it with axe against the WCAG 2.0, 2.1 and 2.2 level A and AA rules, also in dark mode
  4. presses Tab through each page, in the keyboard check, and opens its menus and dialogs with the keyboard
  5. checks that no text gets cut off with larger text or more spacing
  6. follows a link to check navigation without reloads
  7. runs your own tests from the tests folder against the same build
  8. exits with an error code if anything failed

Each page is a test case of its own. A failed check names the rule, the elements that break it and a link that explains the fix:

txt
  Running /guide/install.html:
  ✖ NightwatchAssertError
   aXe rule button-name (critical): Buttons must have discernible text
	In 1 element(s): .menu-button

    Read More :
    https://dequeuniversity.com/rules/axe/4.8/button-name?application=axeAPI

Check some of the pages

While you work on a few pages, check only those, at the widths you want:

sh
npx postdoc test --pages '/guide/**,/index.html' --widths 1280,390

--pages takes glob patterns of page URLs, separated by commas, and --widths the window widths in CSS pixels, in place of the configured ones.

After the checks, the command prints each problem once, with the pages and widths it was found at, so a problem in a header or a footer is one line and not one for every page. --report checks.json writes them to a file as well, as JSON, for a script or an AI agent to read.

Choose the browser

postdoc.config.jsjs
export default {
  nightwatch: {
    browser: 'firefox',
    headless: true
  }
};

The bundled Nightwatch configuration has environments for chrome, firefox, edge and safari. A list, such as ['chrome', 'firefox'], runs the tests in each. Options you add to postdoc test go to Nightwatch, so npx postdoc test --env firefox works too.

More about testing

Edit this page on GitHub