Accessibility checks
postdoc test checks every page with axe against the WCAG 2.0, 2.1 and 2.2 level A and AA rules. axe looks at a page as it is when it loads. These checks go further: they look at the page in its dark colours, use it with the keyboard, open what's closed, and make its text larger.
- 1 As it loads axe checks it against the WCAG rules
- 2 Dark mode The contrast rules run again
- 3 Keyboard Tab goes from the top to the bottom
- 4 Menus Each menu and dialog is opened and closed
- 5 Larger text More spacing, then twice the size
Dark mode
axe checks contrast in the colours the page has when it runs. So after the WCAG rules, Postdoc switches the page to its dark colours and runs the contrast rules again. Problems that only show in dark mode are reported as such:
In dark mode: aXe rule color-contrast (serious): Elements must meet minimum color contrast ratio thresholds
In 1 element(s): .article figcaptionPostdoc switches the page the way its default theme does, by setting data-theme="dark" on <html>. In Chrome and Edge, it also makes prefers-color-scheme: dark media queries match. If your theme uses something else, such as a dark class, set it under a11y.darkMode:
export default {
nightwatch: {
pageChecks: {
a11y: {
darkMode: {
// Adds the class to <html>. Any other attribute is set to the value.
attribute: 'class',
value: 'dark'
}
}
}
}
};A page that has the same colours in dark mode isn't checked again. Set darkMode to false to turn this off.
The keyboard check
axe looks at each page as it is, without using it, so it can't tell whether a keyboard user can get around. The keyboard check does that part. It presses Tab from the top of the page to the bottom and fails the page when:
- a Tab stop can't be seen when it has the focus: it is hidden, outside the window, cut off by a container or covered by another element, such as a sticky header
- a Tab stop looks the same with and without the focus
- a Tab stop has no accessible name
- the focus gets trapped, so Tab keeps going round the same elements
- a link goes nowhere, with
href="#" - an element looks or acts like a control but can't take the focus: it has a role such as
role="button", anonclickattribute or a pointer cursor - the first Tab stop isn't a skip link to the main content
Running /guide/install.html:
✖ NightwatchAssertError
Keyboard: Tab stops that look the same with and without the keyboard focus (1)
header > div.header-inner > button.menuButton ("Menu")
Read More :
https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.htmlConfigure it under keyboard, or set keyboard to false to turn it off:
export default {
nightwatch: {
pageChecks: {
keyboard: {
// Don't require a skip link.
skipLink: false,
// Elements to leave out of the report, as CSS selectors.
ignore: ['.carousel']
}
}
}
};The keyboard check, and the menus and dialogs check below, don't run in Safari, where Tab skips links unless a setting that WebDriver can't change is on. In Firefox on macOS, Tab skips links too unless the accessibility.tabfocus preference is 7. The bundled Nightwatch configuration sets it; if you use your own, set it there.
Menus and dialogs
Menus, dialogs and panels that a button opens are hidden when the page loads, so the checks above don't see them. This check opens each one with the keyboard, checks it and closes it again. It fails when:
- pressing Enter doesn't open it, or
aria-expandeddoesn't say that it's open - the focus doesn't move into a modal dialog, or Tab moves it out to the page behind
- Tab can't reach what opened
- axe or the keyboard check finds a problem in what opened
- Escape doesn't close a dialog, a menu or an overlay that covers the page, or the focus doesn't go back to the button after it
- pressing Enter again doesn't close anything else, such as an accordion panel
Toggle header > button.menuButton ("Menu"): after Escape closes it, the focus is lost instead of going back to the button.
Read More :
https://www.w3.org/WAI/WCAG22/Understanding/focus-order.htmlThe check finds the buttons by their attributes: aria-expanded="false", aria-haspopup, popovertarget or commandfor, and the <summary> of a closed <details>. A button that opens a dialog should have aria-haspopup="dialog", and one that shows an element should name it with aria-controls, which also tells the check what to look at.
A button that's on every page, such as a menu button, is checked once per window width. Configure the check under toggles, or set toggles to false to turn it off:
export default {
nightwatch: {
pageChecks: {
toggles: {
// The most buttons to open on a page.
maxToggles: 10,
// Buttons to leave out, as CSS selectors.
ignore: ['.carousel button']
}
}
}
};Larger text and spacing
People who need larger text, or more space between lines and letters, set it in their browser. This check does the same and fails when a box cuts off text that fit before. It tries:
- the text spacing of WCAG 1.4.12: a line height of 1.5, paragraphs 2em apart, letter spacing of 0.12em and word spacing of 0.16em
- text twice as large, as a browser's text-only zoom makes it (WCAG 1.4.4)
Text: Text that gets cut off when it is twice as large (1)
main > div.card ("Install with npm…"): cuts off 24px at the bottomA box cuts off text when it has a fixed height or width and hides what overflows. Content that scrolls doesn't count, and neither does a box that already hides its content, such as a closed panel. Configure the check under text, or set text to false to turn it off:
export default {
nightwatch: {
pageChecks: {
text: {
// Only check text spacing.
resize: false,
// Elements to leave out, as CSS selectors.
ignore: ['.logo']
}
}
}
};Navigation without reloads
When Postdoc shows the next page in place, it tells assistive technology what a page load would: it announces the new page's title, and moves the focus to the top of the page, so the next Tab starts there. This check makes sure that still works with your layouts and scripts. It follows a link with the keyboard and fails when the new page isn't announced, when its title differs from the one it has after a page load, or when Tab goes somewhere else than after a page load.
It runs once, after the page checks. It's skipped when session.disable_spa turns off navigation without reloads. Set navigation to false to turn it off yourself.
What the checks can't find
Automated checks find many accessibility problems, but not all of them. Whether the focus order makes sense, and how the site works with a screen reader, still need a person to try.