aXe runs a series of tests to check for accessibility of content and functionality on a website. A test is made up of a series of Rules which are, themselves, made up of Checks. aXe executes these Rules asynchronously and, when the Rules are finished running, runs a callback function which is passed a Result structure. Since some Rules run on the page level while others do not, tests will also run in one of two ways. If a document is specified, the page level rules will run, otherwise they will not.
aXe 3.0 supports open Shadow DOM: see our virtual DOM APIs and test utilities for developing axe-core moving forward. Note: we do not and cannot support closed Shadow DOM.
- You must have NodeJS installed.
- Grunt must be installed globally.
npm install -g grunt-cli(You may need to do this assudo npm install -g grunt-cli) - Install npm development dependencies. In the root folder of your axe-core repository, run
npm install
To build axe.js, simply run grunt build in the root folder of the axe-core repository. axe.js and axe.min.js are placed into the dist folder.
To run all tests from the command line you can run grunt test, which will run all unit and integration tests using PhantomJS and Selenium Webdriver.
You can also load tests in any supported browser, which is helpful for debugging. Tests require a local server to run, you must first start a local server to serve files. You can use Grunt to start one by running grunt dev. Once your local server is running you can load the following pages in any browser to run tests:
- Core Tests
- Commons Tests
- Check Tests
- Integration Tests
- There are additional tests located in test/integration/full/ for tests that need to be run against their own document.
aXe tests for accessibility using objects called Rules. Each Rule tests for a high-level aspect of accessibility, such as color contrast, button labels, and alternate text for images. Each rule is made up of a series of Checks. Depending on the rule; all, some, or none of these checks must pass in order for the rule to pass.
Upon execution, a Rule runs each of its Checks against all relevant nodes. Which nodes are relevant is determined by the Rule's selector property and matches function. If a Rule has no Checks that apply to a given node, the Rule will result in an inapplicable result.
After execution, a Check will return true or false depending on whether or not the tested condition was satisfied. The result, as well as more information on what caused the Check to pass or fail, will be stored in either the passes array or the violations array.
Rules are defined by JSON files in the lib/rules directory. The JSON object is used to seed the Rule object. A valid Rule JSON consists of the following:
id-StringA unique name of the Rule.selector- optionalStringwhich is a CSS selector that specifies the elements of the page on which the Rule runs. aXe-core will look inside of the light DOM and open Shadow DOM trees for elements matching the provided selector. If omitted, the rule will run against every node.excludeHidden- optionalBooleanWhether the rule should exclude hidden elements. Defaults totrue.enabled- optionalBooleanWhether the rule is enabled by default. Defaults totrue.pageLevel- optionalBooleanWhether the rule is page level. Page level rules will only run if given an entiredocumentas context.matches- optionalStringRelative path to the JavaScript file of a custom matching function. See matches function for more information.tags- optionalArrayStrings of the accessibility guidelines of which the Rule applies.metadata-ObjectConsisting of:description-StringText string that describes what the rule does.helpUrl-Stringoptional URL that provides more information about the specifics of the violation. Links to a page on the Deque University site.help-StringHelp text that describes the test that was performed.
any-ArrayChecks that make up this Rule; one of these checks must returntruefor a Rule to pass.all-ArrayChecks that make up this Rule; all these checks must returntruefor a Rule to pass.none-ArrayChecks that make up this Rule; none of these checks must returntruefor a Rule to pass.
The any, all and none arrays must contain either a String which references the id of the Check; or an object of the following format:
id-StringThe unique ID of the Check.options-MixedAny options the Check requires that are specific to the Rule.
There is a Grunt target which will ensure each Rule has a valid format, which can be run with grunt validate.
Custom matches functions are executed against each node which matches the Rule's selector and receive two parameters:
node– node, the DOM Node to testvirtualNode– object, the virtual DOM representation of the node. See virtualNode documentation for more.
The matches function must return either true or false. Common functions are provided as commons. See the data-table matches function for an example.
Similar to Rules, Checks are defined by JSON files in the lib/checks directory. The JSON object is used to seed the Check object. A valid Check JSON consists of the following:
id-StringA unique name of the Checkevaluate-StringRelative path to the JavaScript file which contains the function body of the Check itselfafter- optionalStringRelative path to the JavaScript file which contains the function body of a Check's after (or post-processing) function.foptions- optionalMixedAny information the Check needs that you might need to customize and/or is locale specific. Options can be overridden at runtime (with the options parameter) or config-time. For example, the valid-lang Check defines what ISO 639-1 language codes it should accept as valid. Options do not need to follow any specific format or type; it is up to the author of a Check to determine the most appropriate format.metadata-ObjectConsisting of:impact-String(one ofminor,moderate,serious, orcritical)messages-ObjectThese messages are displayed when the Check passes or failspass-StringdoT.js template string displayed when the Check passesfail-StringdoT.js template string displayed when the Check failsincomplete–String|Object– doT.js template string displayed when the Check is incomplete OR an object withmissingDataon why it returned incomplete. Refer to rules.md.
A Check's evaluate function is run a special context in order to give access to APIs which provide more information. Checks will run against a single node and do not have access to other frames. A Check must either return true or false.
The following variables are defined for Check#evaluate:
node-HTMLElementThe element that the Check is run againstoptions-MixedAny options specific to this Check that may be necessary. If not specified by the user at run-time or configure-time; it will useoptionsas defined by the Check's JSON file.virtualNode–ObjectThe virtualNode object for use with Shadow DOM. See virtualNode documentation.this.data()-FunctionFree-form data that either the Check message requires or is presented asdatain the CheckResult object. Subsequent calls tothis.data()will overwrite previous. See aria-valid-attr for example usage.this.relatedNodes()-FunctionArray or NodeList of elements that are related to this Check. For example the duplicate-id Check will add all Elements which share the same ID.commons- Common functions that may be used across multiple Checks. See Common Functions for more information.
You can use the after function to evaluate nodes that might be in other frames or to filter the number of violations or passes produced. The after function runs once for each Rule in the top-most (or originating) frame. Due to this, you should not perform DOM operations in after functions, but instead operate on data defined by the Check.
For example, the duplicate-id Check include an after function which reduces the number of violations so that only one violation per instance of a duplicate ID is found.
The following variables are defined for Check#after:
results-ArrayContains CheckResults for every matching node.commons- Common functions that may be used across multiple Checks. See Common Functions for more information.
The after function must return an Array of CheckResults, due to this, it is a very common pattern to just use Array#filter to filter results:
var uniqueIds = [];
return results.filter(function (r) {
if (uniqueIds.indexOf(r.data) === -1) {
uniqueIds.push(r.data);
return true;
}
return false;
});Occasionally, you may want to add additional information about why a Check passed, failed or returned undefined into its message. For example, the aria-valid-attr will add information about any invalid ARIA attributes to its fail message. The message uses the doT.js and is compiled to a JavaScript function at build-time. In the Check message, you have access to the CheckResult as it.
// aria-valid-attr check
"messages": {
"pass": "ARIA attributes are used correctly for the defined role",
"fail": "ARIA attribute{{=it.data && it.data.length > 1 ? 's are' : ' is'}} not allowed:{{~it.data:value}} {{=value}}{{~}}",
"incomplete": "axe-core couldn't tell because of {{it.data.missingData}}"
}See Developing Axe-core Rules for more information on writing rules and checks, including incomplete results.
When a Check is executed, its result is then added to a CheckResult object. Much like the RuleResult object, the CheckResult object only contains information that is required to determine whether a Check, and its parent Rule passed or failed. metadata from the originating Check is combined later and will not be available until aXe reaches the reporting stage.
A CheckResult has the following properties:
id-StringThe ID of the Check this CheckResult belongs to.data-MixedAny data the Check's evaluate function added withthis.data(). Typically used to insert data from analysis into a message or to perform further tests in the post-processing function.relatedNodes-ArrayNodes that are related to the current Check as defined by check.evaluate.result-BooleanThe return value of check.evaluate.
Common functions are an internal library used by the rules and checks. If you have code repeated across rules and checks, you can use these functions and contribute to them. They are made available to every function as commons. Documentation is available in source code.
To support open Shadow DOM while maintaining backwards compatibility, commons functions that query DOM nodes must operate on an in-memory representation of the DOM using aXe-core’s built-in API methods and utility functions.
Commons functions should do the virtual tree lookup and call a virtual function
including the rest of the commons code. The naming of this special function
should contain the original commons function name with Virtual added to signify
it expects to operate on a virtual DOM tree.
Let’s look at an example:
axe.commons.text.accessibleText = function (element, inLabelledbyContext) {
let virtualNode = axe.utils.getNodeFromTree(axe._tree[0], element); // throws an exception on purpose if axe._tree not correct
return axe.commons.text.accessibleTextVirtual(virtualNode, inLabelledbyContext);
}
axe.commons.text.accessibleTextVirtual = function (element, inLabelledbyContext) {
// rest of the commons code minus the virtual tree lookup, since it’s passed in
}accessibleTextVirtual would only be called directly if you’ve got a virtual node
you can use. If you don’t already have one, call the accessibleText lookup function,
which passes on a virtual DOM node with both the light DOM and Shadow DOM (if applicable).
To support open Shadow DOM, aXe-core has the ability to handle virtual nodes in rule matches and check evaluate functions. The full set of API methods for Shadow DOM can be found in the API documentation, but the general structure for a virtualNode is as follows:
{
actualNode: <HTMLElement>,
children: <Array>,
shadowId: <String>
}- A virtualNode is an object containing an HTML DOM element (
actualNode). - Children contains an array of child virtualNodes.
- The shadowID indicates whether the node is in an open shadow root and if it is, which one it is inside the boundary.
Core Utilities are an internal library that provides aXe with functionality used throughout its core processes. Most notably among these are the queue function and the DqElement constructor.
axe.commons.aria provides a namespace for ARIA-related utilities, including a lookupTable for attributes and roles.
axe.commons.aria.lookupTable.attributesaxe.commons.aria.lookupTable.globalAttributesaxe.commons.aria.lookupTable.role
In addition to the ARIA lookupTable, there are also utility functions on the axe.commons.aria and axe.commons.dom namespaces:
axe.commons.aria.implicitRole- Get the implicit role for a given nodeaxe.commons.aria.label- Gets the accessible ARIA label text of a given elementaxe.commons.dom.isVisible- Determine whether an element is visible
The queue function creates an asynchronous "queue", list of functions to be invoked in parallel, but not necessarily returned in order. The queue function returns an object with the following methods:
defer(func)Defer a function that may or may not run asynchronouslythen(callback)The callback to execute once all "deferred" functions have completed. Will only be invoked once.abort()Abort the "queue" and preventthenfunction from firing
The DqElement is a "serialized" HTMLElement. It will calculate the CSS selector, grab the source outerHTML and offer an array for storing frame paths. The DqElement class takes the following parameters:
Element-HTMLElementThe element to serializeSpec-ObjectProperties to use in place of the element when instantiated on Elements from other frames
var firstH1 = document.getElementByTagName('h1')[0];
var dqH1 = new axe.utils.DqElement(firstH1);Elements returned by the DqElement class have the following methods and properties:
selector-stringA unique CSS selector for the elementsource-stringThe generated HTML source code of the elementelement-DOMNodeThe element which this object is based off or the containing frame, used for sorting.toJSON()- Returns an object containing the selector and source properties
Note: You shouldn’t need the Shadow DOM APIs below unless you’re working on the axe-core
engine, as rules and checks already have virtualNode objects passed in. However, these APIs
will make it easier to work with the virtual DOM.
Recursvely return an array containing the virtual DOM tree for the node specified, excluding comment nodes
and shadow DOM nodes <content> and <slot>. This method will return a flattened tree containing both
light and shadow DOM, if applicable.
var element = document.body;
axe.utils.getFlattenedTree(element, shadowId)node– HTMLElement. The current HTML node for which you want a flattened DOM tree.shadowId– string(optional). ID of the shadow DOM that is the closest shadow ancestor of the node
An array of objects, where each object is a virtualNode:
[{
actualNode: body,
children: [virtualNodes],
shadowId: undefined
}]Recursively return a single node from a virtual DOM tree. This is commonly used in rules and checks where the node is readily available without querying the DOM.
axe.utils.getNodeFromTree(axe._tree[0], node);vNode– object. The flattened DOM tree to fetch a virtual node fromnode– HTMLElement. The HTML DOM node for which you need a virtual representation
A virtualNode object:
{
actualNode: div,
children: [virtualNodes],
shadowId: undefined
}All tests must support open Shadow DOM, so we created some test utilities to make this easier.
Create a check context for mocking and resetting data and relatedNodes in tests.
describe('region', function () {
var fixture = document.getElementById('fixture');
var checkContext = new axe.testUtils.MockCheckContext();
afterEach(function () {
fixture.innerHTML = '';
checkContext.reset();
});
it('should return true when all content is inside the region', function () {
assert.isTrue(checks.region.evaluate.apply(checkContext, checkArgs));
assert.equal(checkContext._relatedNodes.length, 0);
});
});None
An object containg the data, relatedNodes, and a way to reset them.
{
data: (){},
relatedNodes: (){},
reset: (){}
}Provides an API for determining Shadow DOM v0 and v1 support in tests. For example: PhantomJS doesn't have Shadow DOM support, while some browsers do.
(axe.testUtils.shadowSupport.v1 ? it : xit)('should test Shadow tree content', function () {
// The rest of the shadow DOM test
});None
An object containing booleans for the following Shadow DOM supports: v0, v1, or undefined.
Method for injecting content into a fixture and caching the flattened DOM tree (light and Shadow DOM together).
it('should return true if there is only one ' + type + ' element with the same name', function () {
axe.testUtils.fixtureSetup('<input type="' + type + '" id="target" name="uniqueyname">' +
'<input type="' + type + '" name="differentname">');
var node = fixture.querySelector('#target');
assert.isTrue(check.evaluate.call(checkContext, node));
});content– Node|String. Stuff to go into the fixture (html or DOM node)
An HTML Element for the fixture
Create check arguments.
it('should return true when all content is inside the region', function () {
var checkArgs = checkSetup('<div id="target"><div role="main"><a href="a.html#mainheader">Click Here</a><div><h1 id="mainheader" tabindex="0">Introduction</h1></div></div></div>');
assert.isTrue(checks.region.evaluate.apply(checkContext, checkArgs));
assert.equal(checkContext._relatedNodes.length, 0);
});content– String|Node. Stuff to go into the fixture (html or node)options– Object. Options argument for the check (optional, default: {})target– String. Target for the check, CSS selector (default: '#target')
An array with the DOM Node, options and virtualNode
[node, options, virtualNode]