Logging with axe-DevTools Node APIs

There are virtually limitless ways to leverage the results of an axe DevTools scan

All axe-core driven accessibility scans can be set up to return their as a JSON object. This format means it's easy to consume for web accessibility newcomers, contains the depth of information seasoned subject matter experts need, and allows for automated report generation and custom tests even outside of a standard assertion based test format.

Axe DevTools Logger

If you don't want to generate reports in one of the offered formats, but you do want to save your results to file, Deque offers a component to handle this for you called the axe DevTools Logger. With this module, you can write your test results to file inline with running your tests.

To install, it requires the same authentication information setup as any other axe DevTools nodeJS based component. Refer to the installation guide for the method you used to install axe DevTools originally for more information.

To install the logger, run the command npm install @axe-devtools/logger for npm or yarn add @axe-devtools/logger for yarn.

Using the axe DevTools Logger

The logger is imported as follows:

const AxeDevToolsLogger = require('@axe-devtools/logger').default;

Additionally, you can import the package using ES6 modules:

import AxeDevToolsLogger from '@axe-devtools/logger';

Once it's imported, you can instantiate it like this

const logger = new AxeDevToolsLogger('Report Name', '/path/to/a/directory');

After you run a scan and generate a results object, you can log the result to file with this command

logger.logTestResult('\<test-name>', results-object);

The logged file will appear in the directory you specified when instantiated the logger with a filename of Test-Reports-<test-name>.json.

Results Overview

The following sections describe the objects contained in the results JSON file.

Meta

The results object begins with some useful meta information. This includes the name of the test, the web address of the tested page, the date and time the test was run, the axe-core ruleset used, and more.

Findings

The beginning of the results are demarcated by the "findings" heading. There are four types of result, each with their own array. These result types are inapplicable, incomplete, pass, and violation. In addition, there is some test specific data located immediately before the violations array.

Inapplicable

Inapplicable means there was no page content relevant to that particular test, such as form related tests on a page with no forms.

Incomplete

Incompletes are tests which ran, but the results require further review to determine what category the results should ultimately fall into. A common incomplete occupance is color contrast checks on elements with variable color backgrounds where it's not always clear if sufficient contrast is met. Issues in this category should not be treated automatically as violations, as they may or may not be. For users with more accessibility knowledge, deeper examination of these results can help find additional violations that aren't able to be automatically tested for.

Passes

This group of results enumerates the rules that were checked did not find any related accessibility violations. Associated with each passed rule there will be an array of page elements which were checked against the rule and passed.

Violations

The violations array contains all the accessibility violations found in the scan. Thanks to Deque's zero false positives policy, any result found here is guaranteed to be genuine. Each violation contains further info on what the violation is, where it is on the page, suggestions on how to fix it, and more. See the field reference below for more information.

Field Reference - Passes and Violations

The fields contained in the passes and violations objects are enumerated below:

• description — Text string that describes what the rule does
• help — Help text that describes the test performed
• helpUrl — URL that provides more information about the specifics of the violation. Links to a page on the Deque University site.
• id — Unique identifier for the rule; see the list of rules.
• impact — How serious the violation is. Can be one of minor, moderate, serious, or critical if the test failed or null if the check passed
• tags — Array of tags that this rule is assigned. These tags can be used in the option structure to select which rules are run (see attest.a11yCheck parameters).
• nodes — Array of all elements the Rule tested
  • html — Snippet of HTML of the Element
  • impact — How serious the violation is. Can be one of minor, moderate, serious, or critical if the test failed or null if the check passed
  • target — Array of selectors that has each element correspond to one level of iframe or frame. If there is one iframe or frame, there should be two entries in target. If there are three iframe levels, there should be four entries in target.
  • any — Array of checks that were made where at least one must have passed. Each entry in the array contains:
  • id — Unique identifier for this check. Check ids may be the same as Rule ids
  • impact — How serious this particular check is. Can be one of minor, moderate, serious, or critical. Each check that is part of a rule can have different impacts. The highest impact of all the checks that fail is reported for the rule
  • message — Description of why this check passed or failed
  • data — Additional information that is specific to the type of Check which is optional. For example, a color contrast check would include the foreground color, background color, contrast ratio, etc.
  • relatedNodes — Optional array of information about other nodes that are related to this check. For example, a duplicate id check violation would list the other selectors that had this same duplicate id. Each entry in the array contains the following information:
    • target — Array of selectors for the related node
    • html — HTML source of the related node
  • all — Array of checks that were made where all must have passed. Each entry in the array contains the same information as the any array
  • none — Array of checks that were made where all must have not passed. Each entry in the array contains the same information as the any array

Additionally, the JSON results object makes it easy to write your own custom tests. Beyond the standard accessibility violation assertions, you can slice the results object by violations, their severity, their impact, their associated ruleset, or any one of the parameters in the results object. Any data laid out in the results object can therefore be tested against.

Next Steps

Deque makes it easy to share and digest the results of your scans with our reporter. It's configurable to produce HTML, JUnit XML, or CSV reports and once set up, returns reports automatically. See the reporter guide for info on how to set up and use the reporter.