Quick Start: Running an Audit with Web Puppeteer

Web Puppeteer is a testing framework for testing web applications with JavaScript. It has the advantage of being easy to set up, so you can use it to quickly get started running accessibility audits on your web pages.

Web Puppeteer Initial Setup

If you have write access to the web server that hosts the application you want to test:

• Follow the Web Puppeteer Quick Start Guide to set up an initial puppeteer test.

If you don't have write access to the web server that hosts your application:

• Follow the Web Puppeteer Proxy Configuration Guide to set up a puppeteer test using a proxy.

Running an Accessibility Audit

Include the library

Include the generated Accessibility Developer Tools axs_testing.js library in your puppet test.

<script src="./puppet.js"></script>  
<script src="./axs_testing.js"></script>

Create a new run method that will queue some commands to be executed. This run method will run the accessibility audit. If you're using the example puppeteer tests, you can put the run method inside the window.onload method.

window.onload = function() {
  ...
  // Run accessibility audit!
  run(function() {
    // Audit API calls will go here.
  }
}

Set up an Audit Configuration

An Audit Configuration lets you restrict the scope of the audit. This is necessary because Web Puppeteer loads the content to be tested in an iframe.

Set up the audit configuration by using an axs.AuditConfiguration object. You need to tell the audit:

• how to find the iframe (using the #content query selector)
• that the scope of the audit should be restricted to that iframe (setting the auditConfig.scope)

Like this:

run(function() {
  var auditConfig = new axs.AuditConfiguration();
  auditConfig.scope = document.querySelector('#content').contentWindow.document;
}

Run the Audit and Interpret the Results

Call axs.Audit.run() to run the audit.

   var results = axs.Audit.run(auditConfig);

axs.Audit.run() returns an object that can be used with axs.Audit.createReport(results, opt_url) to create an error message suitable for output.

var auditResults = axs.Audit.auditResults(results);
var report = axs.Audit.createReport(results);

For this example, we'll fail and display the error message if the audit found any errors (you could adjust the assertion to fail on warnings if you prefer).

We also want to substitute <br> for the newline character \n because Web Puppeteer uses HTML for output.

puppet.debug('<br />' + report.replace(/\n/g, "<br />"));
puppet.assert(auditResults.numErrors() == 0);

So the full audit run looks like this:

window.onload = function() {
  ...
  // Run accessibility audit!
  run(function() {
    var auditConfig = new axs.AuditConfiguration();
    auditConfig.scope = document.querySelector('#content').contentWindow.document;
    var results = axs.Audit.run(auditConfig);
    var auditResults = axs.Audit.auditResults(results);
    var report = axs.Audit.createReport(results);

    puppet.debug('<br />' + report.replace(/\n/g, "<br />"));
    puppet.assert(auditResults.numErrors() == 0);
  });
}