pa11y_ua

pa11y_ua is your automated accessibility testing pal. It runs HTML CodeSniffer for programmatic accessibility reporting.

In JavaScript:

const pa11y_ua = require('pa11y_ua');

pa11y_ua('http://example.com/').then((results) => {
    // Do something with the results
});

Table Of Contents

• Requirements
• JavaScript Interface
• Configuration
• Actions
• Common Questions and Troubleshooting
• Tutorials and articles
• License

Requirements

pa11y_ua requires Node.js 8+ to run.

OS X

On a Mac, you can install the required dependency with Homebrew:

$ brew install node

Alternatively download pre-built packages from the Node.js website.

Linux

Depending on your flavour of Linux, you should be able to use a package manager to install the required dependency. Alternatively download pre-built packages from the Node.js website.

Windows

On Windows 10, download a pre-built package from the Node.js website. pa11y_ua will be usable via the bundled Node.js application as well as the Windows command prompt.

Windows 7 and below users approach with caution – we've been able to get pa11y_ua running but only after installing Visual Studio and the Windows SDK (as well as Git, and Python). The Windows installation instructions for node-gyp are a good place to start. If you have had a better experience than this then please do share!

JavaScript Interface

Install pa11y_ua with npm or add to your package.json:

npm install pa11y_ua

Require pa11y_ua:

const pa11y_ua = require('pa11y_ua');

Run pa11y_ua against a URL, the pa11y_ua function returns a Promise:

pa11y_ua('http://example.com/').then((results) => {
    // Do something with the results
});

pa11y_ua can also be run with some options:

pa11y_ua('http://example.com/', {
    // Options go here
}).then((results) => {
    // Do something with the results
});

pa11y_ua resolves with a results object, containing details about the page and accessibility issues from HTML CodeSniffer. It looks like this:

{
    documentTitle: 'The title of the page that was tested',
    pageUrl: 'The URL that pa11y_ua was run against',
    issues: [
        {
            code: 'WCAG2AA.Principle1.Guideline1_1.1_1_1.H30.2',
            context: '<a href="http://example.com/"><img src="example.jpg" alt=""/></a>',
            message: 'Img element is the only content of the link, but is missing alt text. The alt text should describe the purpose of the link.',
            selector: 'html > body > p:nth-child(1) > a',
            type: 'error',
            typeCode: 1
        }
        // more issues appear here
    ]
}

Async/Await

Because pa11y_ua is promise based, you can use async functions and the await keyword:

async function runpa11y_ua() {
    try {
        const results = await pa11y_ua('http://example.com/');
        // Do something with the results
    } catch (error) {
        // Handle the error
    }
}

run pa11y_ua();

Callback Interface

If you would rather use callbacks than promises or async/await, then pa11y_ua supports this. This interface should be considered legacy, however, and may not appear in the next major version of pa11y_ua:

pa11y_ua('http://example.com/', (error, results) => {
    // Do something with the results or handle the error
});

Validating Actions

pa11y_ua exposes a function which allows you to validate action strings before attempting to use them.

This function accepts an action string and returns a boolean indicating whether it matches one of the actions that pa11y_ua supports:

pa11y_ua.isValidAction('click element #submit');  // true
pa11y_ua.isValidAction('open the pod bay doors'); // false

Configuration

pa11y_ua has lots of options you can use to change the way Headless Chrome runs, or the way your page is loaded. Options can be set either as a parameter on the pa11y_ua function or in a JSON configuration file. Some are also available directly as command-line options.

Below is a reference of all the options that are available:

actions (array) BETA

Actions to be run before pa11y_ua tests the page. There are quite a few different actions available in pa11y_ua, the Actions documentation outlines each of them.

Note: actions are currently in a beta state and the API may change while we gather feedback.

pa11y_ua('http://example.com/', {
    actions: [
        'set field #username to exampleUser',
        'set field #password to password1234',
        'click element #submit',
        'wait for path to be /myaccount'
    ]
});

Defaults to an empty array.

browser (Browser) and page (Page)

A Puppeteer Browser instance which will be used in the test run. Optionally you may also supply a Puppeteer Page instance, but this cannot be used between test runs as event listeners would be bound multiple times.

If either of these options are provided then there are several things you need to consider:

1. pa11y_ua's chromeLaunchConfig option will be ignored, you'll need to pass this configuration in when you create your Browser instance
2. pa11y_ua will not automatically close the Browser when the tests have finished running, you will need to do this yourself if you need the Node.js process to exit
3. It's important that you use a version of Puppeteer that meets the range specified in pa11y_ua's package.json
4. You cannot reuse page instances between multiple test runs, doing so will result in an error. The page option allows you to do things like take screen-shots on a pa11y_ua failure or execute your own JavaScript before pa11y_ua

Note: This is an advanced option. If you're using this, please mention in any issues you open on pa11y_ua and double-check that the Puppeteer version you're using matches pa11y_ua's.

const browser = await puppeteer.launch({
    ignoreHTTPSErrors: true
});

pa11y_ua('http://example.com/', {
    browser: browser
});

browser.close();

A more full example can be found in the examples.

Defaults to null.

chromeLaunchConfig (object)

Launch options for the Headless Chrome instance. See the Puppeteer documentation for more information.

pa11y_ua('http://example.com/', {
    chromeLaunchConfig: {
        executablePath: '/path/to/Chrome',
        ignoreHTTPSErrors: false
    }
});

Defaults to:

{
    ignoreHTTPSErrors: true
}

headers (object)

A key-value map of request headers to send when testing a web page.

pa11y_ua('http://example.com/', {
    headers: {
        Cookie: 'foo=bar'
    }
});

Defaults to an empty object.

hideElements (string)

A CSS selector to hide elements from testing, selectors can be comma separated. Elements matching this selector will be hidden from testing by styling them with visibility: hidden.

pa11y_ua('http://example.com/', {
    hideElements: '.advert, #modal, div[aria-role=presentation]'
});

ignore (array)

An array of result codes and types that you'd like to ignore. You can find the codes for each rule in the console output and the types are error, warning, and notice. Note: warning and notice messages are ignored by default.

pa11y_ua('http://example.com/', {
    ignore: [
        'WCAG2AA.Principle3.Guideline3_1.3_1_1.H57.2'
    ]
});

Defaults to an empty array.

includeNotices (boolean)

Whether to include results with a type of notice in the pa11y_ua report. Issues with a type of notice are not directly actionable and so they are excluded by default. You can include them by using this option:

pa11y_ua('http://example.com/', {
    includeNotices: true
});

Defaults to false.

includeWarnings (boolean)

Whether to include results with a type of warning in the pa11y_ua report. Issues with a type of warning are not directly actionable and so they are excluded by default. You can include them by using this option:

pa11y_ua('http://example.com/', {
    includeWarnings: true
});

Defaults to false.

level (string)

The level of issue which can fail the test (and cause it to exit with code 2) when running via the CLI. This should be one of error (the default), warning, or notice.

{
    "level": "warning"
}

Defaults to error. Note this configuration is only available when using pa11y_ua on the command line, not via the JavaScript Interface.

log (object)

An object which implements the methods debug, error, and info which will be used to report errors and test information.

pa11y_ua('http://example.com/', {
    log: {
        debug: console.log,
        error: console.error,
        info: console.info
    }
});

Each of these defaults to an empty function.

method (string)

The HTTP method to use when running pa11y_ua.

pa11y_ua('http://example.com/', {
    method: 'POST'
});

Defaults to GET.

postData (string)

The HTTP POST data to send when running pa11y_ua. This should be combined with a Content-Type header. E.g to send form data:

pa11y_ua('http://example.com/', {
    headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
    },
    method: 'POST',
    postData: 'foo=bar&bar=baz'
});

Or to send JSON data:

pa11y_ua('http://example.com/', {
    headers: {
        'Content-Type': 'application/json'
    },
    method: 'POST',
    postData: '{"foo": "bar", "bar": "baz"}'
});

Defaults to null.

rootElement (element)

The root element for testing a subset of the page opposed to the full document.

pa11y_ua('http://example.com/', {
    rootElement: '#main'
});

Defaults to null, meaning the full document will be tested.

rules (array)

An array of WCAG 2.0 guidelines that you'd like to include to the current standard. Note: These won't be applied to Section508 standard. You can find the codes for each guideline in the [HTML Code Sniffer WCAG2AAA ruleset][htmlcs-wcag2aaa-ruleset].

pa11y_ua('http://example.com/', {
    rules: [
        'Principle1.Guideline1_3.1_3_1_AAA'
    ]
});

screenCapture (string)

A file path to save a screen capture of the tested page to. The screen will be captured immediately after the pa11y_ua tests have run so that you can verify that the expected page was tested.

pa11y_ua('http://example.com/', {
    screenCapture: `${__dirname}/my-screen-capture.png`
});

Defaults to null, meaning the screen will not be captured.

standard (string)

The accessibility standard to use when testing pages. This should be one of Section508, WCAG2A, WCAG2AA, or WCAG2AAA.

pa11y_ua('http://example.com/', {
    standard: 'Section508'
});

Defaults to WCAG2AA.

threshold (number)

The number of errors, warnings, or notices to permit before the test is considered to have failed (with exit code 2) when running via the CLI.

{
    "threshold": 9
}

Defaults to 0. Note this configuration is only available when using pa11y_ua on the command line, not via the JavaScript Interface.

timeout (number)

The time in milliseconds that a test should be allowed to run before calling back with a timeout error.

Please note that this is the timeout for the entire test run (including time to initialise Chrome, load the page, and run the tests).

pa11y_ua('http://example.com/', {
    timeout: 500
});

Defaults to 30000.

userAgent (string)

The User-Agent header to send with pa11y_ua requests. This is helpful to identify pa11y_ua in your logs.

pa11y_ua('http://example.com/', {
    userAgent: 'A11Y TESTS'
});

Defaults to pa11y_ua/<version>.

viewport (object)

The viewport configuration. This can have any of the properties supported by the puppeteer setViewport method.

pa11y_ua('http://example.com/', {
    viewport: {
        width: 320,
        height: 480,
        deviceScaleFactor: 2,
        isMobile: true
    }
});

Defaults to:

{
    width: 1280,
    height: 1024
}

wait (number)

The time in milliseconds to wait before running HTML CodeSniffer on the page.

pa11y_ua('http://example.com/', {
    wait: 500
});

Defaults to 0.

Actions

Actions are additional interactions that you can make pa11y_ua perform before the tests are run. They allow you to do things like click on a button, enter a value in a form, wait for a redirect, or wait for the URL fragment to change:

pa11y_ua('http://example.com/', {
    actions: [
        'click element #tab-1',
        'wait for element #tab-1-content to be visible',
        'set field #fullname to John Doe',
        'check field #terms-and-conditions',
        'uncheck field #subscribe-to-marketing',
        'screen capture example.png',
        'wait for fragment to be #page-2',
        'wait for path to not be /login',
        'wait for url to be https://example.com/',
        'wait for #my-image to emit load',
        'navigate to https://another-example.com/'
    ]
});

Below is a reference of all the available actions and what they do on the page. Some of these take time to complete so you may need to increase the timeout option if you have a large set of actions.

Click Element

This allows you to click an element by passing in a CSS selector. This action takes the form click element <selector>. E.g.

pa11y_ua('http://example.com/', {
    actions: [
        'click element #tab-1'
    ]
});

You can use any valid query selector, including classes and types.

Set Field Value

This allows you to set the value of a text-based input or select box by passing in a CSS selector and value. This action takes the form set field <selector> to <value>. E.g.

pa11y_ua('http://example.com/', {
    actions: [
        'set field #fullname to John Doe'
    ]
});

Check/Uncheck Field

This allows you to check or uncheck checkbox and radio inputs by passing in a CSS selector. This action takes the form check field <selector> or uncheck field <selector>. E.g.

pa11y_ua('http://example.com/', {
    actions: [
        'check field #terms-and-conditions',
        'uncheck field #subscribe-to-marketing'
    ]
});

Screen Capture

This allows you to capture the screen between other actions, useful to verify that the page looks as you expect before the pa11y_ua test runs. This action takes the form screen capture <file-path>. E.g.

pa11y_ua('http://example.com/', {
    actions: [
        'screen capture example.png'
    ]
});

Wait For Fragment/Path/URL

This allows you to pause the test until a condition is met, and the page has either a given fragment, path, or URL. This will wait until pa11y_ua times out so it should be used after another action that would trigger the change in state. You can also wait until the page does not have a given fragment, path, or URL using the to not be syntax. This action takes one of the forms:

• wait for fragment to be <fragment> (including the preceding #)
• wait for fragment to not be <fragment> (including the preceding #)
• wait for path to be <path> (including the preceding /)
• wait for path to not be <path> (including the preceding /)
• wait for url to be <url>
• wait for url to not be <url>

E.g.

pa11y_ua('http://example.com/', {
    actions: [
        'click element #login-link',
        'wait for path to be /login'
    ]
});

Wait For Element State

This allows you to pause the test until an element on the page (matching a CSS selector) is either added, removed, visible, or hidden. This will wait until pa11y_ua times out so it should be used after another action that would trigger the change in state. This action takes one of the forms:

• wait for element <selector> to be added
• wait for element <selector> to be removed
• wait for element <selector> to be visible
• wait for element <selector> to be hidden

E.g.

pa11y_ua('http://example.com/', {
    actions: [
        'click element #tab-2',
        'wait for element #tab-1 to be hidden'
    ]
});

Wait For Element Event

This allows you to pause the test until an element on the page (matching a CSS selector) emits an event. This will wait until pa11y_ua times out so it should be used after another action that would trigger the event. This action takes the form wait for element <selector> to emit <event-type>. E.g.

pa11y_ua('http://example.com/', {
    actions: [
        'click element #tab-2',
        'wait for element #tab-panel-to to emit content-loaded'
    ]
});

Navigate To URL

This action allows you to navigate to a new URL if, for example, the URL is inaccessible using other methods. This action takes the form navigate to <url>. E.g.

pa11y_ua('http://example.com/', {
    actions: [
        'navigate to http://another-example.com'
    ]
});

License

pa11y_ua is licensed under the Lesser General Public License (LGPL-3.0). Copyright © 2013–2017, Team pa11y and contributors