1# Axe Javascript Accessibility API 2 3## Table of Contents 4 51. [Section 1: Introduction](#section-1-introduction) 6 1. [Get Started](#getting-started) 71. [Section 2: API Reference](#section-2-api-reference) 8 1. [Overview](#overview) 9 1. [API Notes](#api-notes) 10 1. [API Name: axe.getRules](#api-name-axegetrules) 11 1. [API Name: axe.configure](#api-name-axeconfigure) 12 1. [API Name: axe.reset](#api-name-axereset) 13 1. [API Name: axe.run](#api-name-axerun) 14 1. [Parameters axe.run](#parameters-axerun) 15 1. [Context Parameter](#context-parameter) 16 2. [Options Parameter](#options-parameter) 17 3. [Callback Parameter](#callback-parameter) 18 1. [Return Promise](#return-promise) 19 1. [Error result](#error-result) 20 1. [Results Object](#results-object) 21 1. [API Name: axe.registerPlugin](#api-name-axeregisterplugin) 22 1. [API Name: axe.cleanup](#api-name-axecleanup) 23 1. [Virtual DOM Utilities](#virtual-dom-utilities) 24 1. [API Name: axe.utils.querySelectorAll](#api-name-axeutilsqueryselectorall) 25 1. [Common Functions](#common-functions) 261. [Section 3: Example Reference](#section-3-example-reference) 271. [Section 4: Performance](#section-4-performance) 28 29## Section 1: Introduction 30 31The axe API is designed to be an improvement over the previous generation of accessibility APIs. It provides the following benefits: 32 33- Runs in any modern browser 34- Designed to work with existing testing infrastructure 35- Runs locally, no connection to a third-party server is necessary 36- Performs violation checking on multiple levels of nested iframes 37- Provides list of rules and elements that passed accessibility checking, ensuring rules have been run against entire document 38- Only checks rendered content to minimize false positives (that includes visually-hidden content) 39 40### Getting Started 41 42This section gives a quick description of how to use the axe APIs to analyze web page content and return a JSON object that lists any accessibility violations found. 43 44The axe API can be used as part of a broader process that is performed on many, if not all, pages of a website. The API is used to analyze web page content and return a JSON object that lists any accessibility violations found. Here is how to get started: 45 461. Load page in testing system 472. Optionally, set configuration options for the javascript API (`axe.configure`) 483. Call analyze javascript API (`axe.run`) 494. Either assert against results or save them for later processing 505. Repeat for any inactive or non-rendered content after making it visible 51 52## Section 2: API Reference 53 54### Overview 55 56The axe APIs are provided in the javascript file axe.js. It must be included in the web page under test, as well as each `iframe` under test. Parameters are sent as javascript function parameters. Results are returned in JSON format. 57 58### Full API Reference for Developers 59 60For a full listing of API offered by axe, clone the repository and run `npm run api-docs`. This generates `jsdoc` documentation under `doc/api` which can be viewed using the browser. 61 62### API Notes 63 64- A Rule test is made up of sub-tests. Each sub-test is returned in an array of 'checks' 65- The `"helpUrl"` in the results object is a link to a broader description of the accessibility issue and suggested remediation. These links point to Deque University help pages, which do not require a login. 66- Axe does not test hidden regions, such as inactive menus or modal windows. To test those for accessibility, write tests that activate or render the regions visible and run the analysis again. 67 68### Axe-core Tags 69 70Each rule in axe-core has a number of tags. These provide metadata about the rule. Each rule has one tag that indicates which WCAG version / level it belongs to, or if it doesn't it have the `best-practice` tag. If the rule is required by WCAG, there is a tag that references the success criterion number. For example, the `wcag111` tag means a rule is required for WCAG 2 success criterion 1.1.1. 71 72The `experimental`, `ACT` and `section508` tags are only added to some rules. Each rule with a `section508` tag also has a tag to indicate what requirement in old Section 508 the rule is required by. For example `section508.22.a`. 73 74| Tag Name | Accessibility Standard / Purpose | 75| ---------------- | ---------------------------------------------------- | 76| `wcag2a` | WCAG 2.0 Level A | 77| `wcag2aa` | WCAG 2.0 Level AA | 78| `wcag21a` | WCAG 2.1 Level A | 79| `wcag21aa` | WCAG 2.1 Level AA | 80| `best-practice` | Common accessibility best practices | 81| `wcag***` | WCAG success criterion e.g. wcag111 maps to SC 1.1.1 | 82| `ACT` | W3C approved Accessibility Conformance Testing rules | 83| `section508` | Old Section 508 rules | 84| `section508.*.*` | Requirement in old Section 508 | 85| `experimental` | Cutting-edge rules, disabled by default | 86| `cat.*` | Category mappings used by Deque (see below) | 87 88All rules have a `cat.*` tag, which indicates what type of content it is part of. The following `cat.*` tags exist in axe-core: 89 90| Category name | 91| ----------------------------- | 92| `cat.aria` | 93| `cat.color` | 94| `cat.forms` | 95| `cat.keyboard` | 96| `cat.language` | 97| `cat.name-role-value` | 98| `cat.parsing` | 99| `cat.semantics` | 100| `cat.sensory-and-visual-cues` | 101| `cat.structure` | 102| `cat.tables` | 103| `cat.text-alternatives` | 104| `cat.time-and-media` | 105 106### API Name: axe.getRules 107 108#### Purpose 109 110To get information on all the rules in the system. 111 112#### Description 113 114Returns a list of all rules with their ID and description 115 116#### Synopsis 117 118`axe.getRules([Tag Name 1, Tag Name 2...]);` 119 120#### Parameters 121 122- `tags` - **optional** Array of tags used to filter returned rules. If omitted, it will return all rules. See [axe-core tags](#axe-core-tags). 123 124**Returns:** Array of rules that match the input filter with each entry having a format of `{ruleId: <id>, description: <desc>, helpUrl: <url>, help: <help>, tags: <tags>}` 125 126#### Example 1 127 128In this example, we pass in the WCAG 2 A and AA tags into `axe.getRules` to retrieve only those rules. The function call returns an array of rules. 129 130**Call:** `axe.getRules(['wcag2aa', 'wcag2a']);` 131 132**Returned Data:** 133 134```js 135[ 136 { 137 description: "Ensures <area> elements of image maps have alternate text", 138 help: "Active <area> elements must have alternate text", 139 helpUrl: "https://dequeuniversity.com/rules/axe/3.5/area-alt?application=axeAPI", 140 ruleId: "area-alt", 141 tags: [ 142 "cat.text-alternatives", 143 "wcag2a", 144 "wcag111", 145 "wcag244", 146 "wcag412", 147 "section508", 148 "section508.22.a" 149 ] 150 }, 151 { 152 description: "Ensures ARIA attributes are allowed for an element's role", 153 help: "Elements must only use allowed ARIA attributes", 154 helpUrl: "https://dequeuniversity.com/rules/axe/3.5/aria-allowed-attr?application=axeAPI", 155 ruleId: "aria-allowed-attr", 156 tags: [ 157 "cat.aria", 158 "wcag2a", 159 "wcag412" 160 ] 161 } 162 … 163] 164``` 165 166### API Name: axe.configure 167 168#### Purpose 169 170To configure the format of the data used by axe. This can be used to add new rules, which must be registered with the library to execute. 171 172**important**: `axe.configure()` does not communicate configuration calls into iframes. Instead `axe.configure()` must be called with the same argument in each `frame` / `iframe` individually. 173 174#### Description 175 176User specifies the format of the JSON structure passed to the callback of `axe.run` 177 178#### Synopsis 179 180```js 181axe.configure({ 182 branding: { 183 brand: String, 184 application: String 185 }, 186 reporter: 'option' | Function, 187 checks: [Object], 188 rules: [Object], 189 standards: Object, 190 locale: Object, 191 axeVersion: String, 192 disableOtherRules: Boolean 193}); 194``` 195 196#### Parameters 197 198- `configurationOptions` - Options object; where the valid name, value pairs are: 199 - `branding` - mixed(optional) Used to set the branding of the helpUrls 200 - `brand` - string(optional) sets the brand string - default "axe" 201 - `application` - string(optional) sets the application string - default "axeAPI" 202 - `reporter` - Used to set the output format that the axe.run function will pass to the callback function. Can pass a reporter name or a custom reporter function. Valid names are: 203 - `v1` to use the previous version's format: `axe.configure({ reporter: "v1" });` 204 - `v2` to use the current version's format: `axe.configure({ reporter: "v2" });` 205 - `raw` to return the raw result data without formating: `axe.configure({ reporter: "raw" });` 206 - `raw-env` to return the raw result data with environment data: `axe.configure({ reporter: "raw-env" });` 207 - `no-passes` to return only violation results: `axe.configure({ reporter: "no-passes" });` 208 - `checks` - Used to add checks to the list of checks used by rules, or to override the properties of existing checks 209 - The checks attribute is an array of check objects 210 - Each check object can contain the following attributes 211 - `id` - string(required). This uniquely identifies the check. If the check already exists, this will result in any supplied check properties being overridden. The properties below that are marked required if new are optional when the check is being overridden. 212 - `evaluate` - string(required for new). The ID of the function that implements the check's functionality. See the [`metadata-function-map`](../lib/core/base/metadata-function-map.js) file for all defined IDs. 213 - `after` - string(optional). The ID of the function that gets called for checks that operate on a page-level basis, to process the results from the iframes. 214 - `options` - mixed(optional). This is the options structure that is passed to the evaluate function and is intended to be used to configure checks. It is the most common property that is intended to be overridden for existing checks. 215 - `enabled` - boolean(optional, default `true`). This is used to indicate whether the check is on or off by default. Checks that are off are not evaluated, even when included in a rule. Overriding this is a common way to disable a particular check across multiple rules. 216 - `rules` - Used to add rules to the existing set of rules, or to override the properties of existing rules 217 - The rules attribute is an Array of rule objects 218 - each rule object can contain the following attributes 219 - `id` - string(required). This uniquely identifies the rule. If the rule already exists, it will be overridden with any of the attributes supplied. The attributes below that are marked required, are only required for new rules. 220 - `impact` - string(optional). Override the impact defined by checks 221 - `reviewOnFail` - boolean(option, default `false`). Override the result of a rule to return "Needs Review" rather than "Violation" if the rule fails. 222 - `selector` - string(optional, default `*`). A [CSS selector](./developer-guide.md#supported-css-selectors) used to identify the elements that are passed into the rule for evaluation. 223 - `excludeHidden` - boolean(optional, default `true`). This indicates whether elements that are hidden from all users are to be passed into the rule for evaluation. 224 - `enabled` - boolean(optional, default `true`). Whether the rule is turned on. This is a common attribute for overriding. 225 - `pageLevel` - boolean(optional, default `false`). When set to true, this rule is only applied when the entire page is tested. Results from nodes on different frames are combined into a single result. See [page level rules](#page-level-rules). 226 - `any` - array(optional, default `[]`). This is a list of checks that, if none "pass", will generate a violation. 227 - `all` - array(optional, default `[]`). This is a list of checks that, if any "fails", will generate a violation. 228 - `none` - array(optional, default `[]`). This is a list of checks that, if any "pass", will generate a violation. 229 - `tags` - array(optional, default `[]`). A list if the tags that "classify" the rule. See [axe-core tags](#axe-core-tags). 230 - `matches` - string(optional). The ID of the filtering function that will exclude elements that match the `selector` property. See the [`metadata-function-map`](../lib/core/base/metadata-function-map.js) file for all defined IDs. 231 - `standards` - object(optional). Used to configure the standards object. See the [Standards Object docs](./standards-object.md) for the structure of each standards object. 232 - `disableOtherRules` - Disables all rules not included in the `rules` property. 233 - `locale` - A locale object to apply (at runtime) to all rules and checks, in the same shape as `/locales/*.json`. 234 - `axeVersion` - Set the compatible version of a custom rule with the current axe version. Compatible versions are all patch and minor updates that are the same as, or newer than those of the `axeVersion` property. 235 236**Returns:** Nothing 237 238##### Page level rules 239 240Page level rules split their evaluation into two phases. A 'data collection' phase which is done inside the 'evaluate' function and an assessment phase which is done inside the 'after' function. The evaluate function executes inside each individual frame and is responsible for collection data that is passed into the after function which inspects that data and makes a decision. 241 242Page level rules raise violations on the entire document and not on individual nodes or frames from which the data was collected. For an example of how this works, see the heading order check: 243 244- [lib/checks/navigation/heading-order.json](https://github.com/dequelabs/axe-core/blob/master/lib/checks/navigation/heading-order.json) 245- [lib/checks/navigation/heading-order-evaluate.js](https://github.com/dequelabs/axe-core/blob/master/lib/checks/navigation/heading-order-evaluate.js) 246- [lib/checks/navigation/heading-order-after.js](https://github.com/dequelabs/axe-core/blob/master/lib/checks/navigation/heading-order-after.js) 247 248### API Name: axe.reset 249 250#### Purpose 251 252Reset the configuration to the default configuration. 253 254#### Description 255 256Override any previous calls to `axe.configure` and restore the configuration to the default configuration. Note: this will NOT unregister any new rules or checks that were registered but will reset the configuration back to the default configuration for everything else. 257 258#### Synopsis 259 260```js 261axe.reset(); 262``` 263 264#### Parameters 265 266None 267 268### API Name: axe.run 269 270#### Purpose 271 272Analyze rendered content on the currently loaded page 273 274#### Description 275 276Runs a number of rules against the provided HTML page and returns the resulting issue list 277 278#### Synopsis 279 280```js 281axe.run(context, options, (err, results) => { 282 // ... 283}); 284``` 285 286#### Parameters axe.run 287 288- [`context`](#context-parameter): (optional) Defines the scope of the analysis - the part of the DOM that you would like to analyze. This will typically be the `document` or a specific selector such as class name, ID, selector, etc. 289- [`options`](#options-parameter): (optional) Set of options passed into rules or checks, temporarily modifying them. This contrasts with `axe.configure`, which is more permanent. 290- [`callback`](#callback-parameter): (optional) The callback function which receives either null or an [error result](#error-result) as the first parameter, and the [results object](#results-object) when analysis is completed successfully, or undefined if it did not. 291 292##### Context Parameter 293 294By default, `axe.run` will test the entire document. The context object is an optional parameter that can be used to specify which element should and which should not be tested. It can be passed one of the following: 295 2961. An element reference that represents the portion of the document that must be analyzed 297 - Example: To limit analysis to the `<div id="content">` element: `document.getElementById("content")` 2981. A NodeList such as returned by `document.querySelectorAll`. 2991. A [CSS selector](./developer-guide.md#supported-css-selectors) that selects the portion(s) of the document that must be analyzed. 3001. An include-exclude object (see below) 301 302###### Include-Exclude Object 303 304The include exclude object is a JSON object with two attributes: include and exclude. Either include or exclude is required. If only `exclude` is specified; include will default to the entire `document`. 305 306- A node, or 307- An array of arrays of [CSS selectors](./developer-guide.md#supported-css-selectors) 308 - If the nested array contains a single string, that string is the CSS selector 309 - If the nested array contains multiple strings 310 - The last string is the final CSS selector 311 - All other's are the nested structure of iframes inside the document 312 313In most cases, the component arrays will contain only one CSS selector. Multiple CSS selectors are only required if you want to include or exclude regions of a page that are inside iframes (or iframes within iframes within iframes). In this case, the first n-1 selectors are selectors that select the iframe(s) and the nth selector, selects the region(s) within the iframe. 314 315###### Context Parameter Examples 316 3171. Include the first item in the `$fixture` NodeList but exclude its first child 318 319```js 320axe.run( 321 { 322 include: $fixture[0], 323 exclude: $fixture[0].firstChild 324 }, 325 (err, results) => { 326 // ... 327 } 328); 329``` 330 3312. Include the element with the ID of `fix` but exclude any `div`s within it 332 333```js 334axe.run( 335 { 336 include: [['#fix']], 337 exclude: [['#fix div']] 338 }, 339 (err, results) => { 340 // ... 341 } 342); 343``` 344 3453. Include the whole document except any structures whose parent contains the class `exclude1` or `exclude2` 346 347```js 348axe.run( 349 { 350 exclude: [['.exclude1'], ['.exclude2']] 351 }, 352 (err, results) => { 353 // ... 354 } 355); 356``` 357 3584. Include the element with the ID of `fix`, within the iframe with id `frame` 359 360```js 361axe.run( 362 { 363 include: [['#frame', '#fix']] 364 }, 365 (err, results) => { 366 // ... 367 } 368); 369``` 370 3715. Include the element with the ID of `fix`, within the iframe with id `frame2`, within the iframe with id `frame1` 372 373```js 374axe.run( 375 { 376 include: [['#frame1', '#frame2', '#fix']] 377 }, 378 (err, results) => { 379 // ... 380 } 381); 382``` 383 3846. Include the following: 385 386- The element with the ID of `fix`, within the iframe with id `frame2`, within the iframe with id `frame1` 387- The element with id `header` 388- All links 389 390```js 391axe.run( 392 { 393 include: [['#header'], ['a'], ['#frame1', '#frame2', '#fix']] 394 }, 395 (err, results) => { 396 // ... 397 } 398); 399``` 400 401##### Options Parameter 402 403The options parameter is flexible way to configure how `axe.run` operates. The different modes of operation are: 404 405- Run all rules corresponding to one of the accessibility standards 406- Run all rules defined in the system, except for the list of rules specified 407- Run a specific set of rules provided as a list of rule ids 408 409Additionally, there are a number or properties that allow configuration of different options: 410 411| Property | Default | Description | 412| ------------------ | :------ | :-------------------------------------------------------------------------------------------------------------------------------------- | 413| `runOnly` | n/a | Limit which rules are executed, based on names or tags | 414| `rules` | n/a | Enable or disable rules using the `enabled` property | 415| `reporter` | `v1` | Which reporter to use (see [Configuration](#api-name-axeconfigure)) | 416| `resultTypes` | n/a | Limit which result types are processed and aggregated | 417| `selectors` | `true` | Return CSS selector for elements, optimised for readability | 418| `ancestry` | `false` | Return CSS selector for elements, with all the element's ancestors | 419| `xpath` | `false` | Return xpath selectors for elements | 420| `absolutePaths` | `false` | Use absolute paths when creating element selectors | 421| `iframes` | `true` | Tell axe to run inside iframes | 422| `elementRef` | `false` | Return element references in addition to the target | 423| `frameWaitTime` | `60000` | How long (in milliseconds) axe waits for a response from embedded frames before timing out | 424| `preload` | `true` | Any additional assets (eg: cssom) to preload before running rules. [See here for configuration details](#preload-configuration-details) | 425| `performanceTimer` | `false` | Log rule performance metrics to the console | 426 427###### Options Parameter Examples 428 4291. Run only Rules for an accessibility standard. See [axe-core tags](#axe-core-tags). 430 431To run only WCAG 2.0 Level A rules, specify `options` as: 432 433```js 434axe.run( 435 { 436 runOnly: { 437 type: 'tag', 438 values: ['wcag2a'] 439 } 440 }, 441 (err, results) => { 442 // ... 443 } 444); 445``` 446 447To run both WCAG 2.0 Level A and Level AA rules, you must specify both `wcag2a` and `wcag2aa`: 448 449```js 450axe.run( 451 { 452 runOnly: { 453 type: 'tag', 454 values: ['wcag2a', 'wcag2aa'] 455 } 456 }, 457 (err, results) => { 458 // ... 459 } 460); 461``` 462 463Alternatively, runOnly can be passed an array of tags: 464 465```js 466axe.run({ 467 runOnly: ['wcag2a', 'wcag2aa']; 468}, (err, results) => { 469 // ... 470}) 471``` 472 4732. Run only a specified list of Rules 474 475If you only want to run certain rules, specify options as: 476 477```js 478axe.run( 479 { 480 runOnly: { 481 type: 'rule', 482 values: ['ruleId1', 'ruleId2', 'ruleId3'] 483 } 484 }, 485 (err, results) => { 486 // ... 487 } 488); 489``` 490 491This example will only run the rules with the id of `ruleId1`, `ruleId2`, and `ruleId3`. No other rule will run. 492 493Alternatively, runOnly can be passed an array of rules: 494 495```js 496axe.run({ 497 runOnly: ['ruleId1', 'ruleId2', 'ruleId3']; 498}, (err, results) => { 499 // ... 500}) 501``` 502 5033. Run all enabled Rules except for a list of rules 504 505The default operation for axe.run is to run all rules except for rules with the "experimental" tag. If certain rules should be disabled from being run, specify `options` as: 506 507```js 508axe.run( 509 { 510 rules: { 511 'color-contrast': { enabled: false }, 512 'valid-lang': { enabled: false } 513 } 514 }, 515 (err, results) => { 516 // ... 517 } 518); 519``` 520 521This example will disable the rules with the id of `color-contrast` and `valid-lang`. All other rules will run. The list of valid rule IDs is specified in the section below. 522 5234. Run a modified set or rules using tags and rule enable 524 525By combining runOnly with type: tags and the rules option, a modified set can be defined. This lets you include rules with unspecified tags, and exclude rules that do have the specified tag(s). 526 527```js 528axe.run( 529 { 530 runOnly: { 531 type: 'tag', 532 values: ['wcag2a'] 533 }, 534 rules: { 535 'color-contrast': { enabled: true }, 536 'valid-lang': { enabled: false } 537 } 538 }, 539 (err, results) => { 540 // ... 541 } 542); 543``` 544 545This example includes all level A rules except for valid-lang, and in addition will include the level AA color-contrast rule. 546 5476. Only process certain types of results 548 549The `resultTypes` option can be used to limit the number of nodes for a rule to a maximum of one. This can be useful for improving performance on very large or complicated pages when you are only interested in certain types of results. 550 551After axe has processed all rules normally, it generates a unique selector for all nodes in all rules. This process can be time consuming, especially for pages with lots of nodes. By limiting the nodes to a maximum of one for result types you are not interested in, you can greatly speed up the tail end performance of axe. 552 553Types listed in this option will cause rules that fall under those types to show all nodes. Types _not_ listed will causes rules that fall under one of the missing types to show a maximum of one node. This allows you to still see those results and inform the user of them if appropriate. 554 555```js 556axe.run( 557 { 558 resultTypes: ['violations', 'incomplete', 'inapplicable'] 559 }, 560 (err, results) => { 561 // ... 562 } 563); 564``` 565 566This example will return all the nodes for all rules that fall under the "violations", "incomplete", and "inapplicable" result types. Since the "passes" type was not specified, it will return at most one node for each rule that passes. 567 568###### <a id='preload-configuration-details'></a> Preload Configuration in Options Parameter 569 570The `preload` attribute (defaults to `true`) in options parameter, accepts a `boolean` or an `object` where an array of assets can be specified. 571 5721. Specifying a `boolean` 573 574```js 575axe.run( 576 { 577 preload: true 578 }, 579 (err, results) => { 580 // ... 581 } 582); 583``` 584 5852. Specifying an `object` 586 587```js 588axe.run( 589 { 590 preload: { assets: ['cssom'], timeout: 50000 } 591 }, 592 (err, results) => { 593 // ... 594 } 595); 596``` 597 598The `assets` attribute expects an array of preload(able) constraints to be fetched. The current set of values supported for `assets` is listed in the following table: 599 600| Asset Type | Description | 601| :--------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | 602| `cssom` | This asset type preloads all CSS Stylesheets rulesets specified in the page. The stylesheets can be an external cross-domain resource, a relative stylesheet or an inline style with in the head tag of the document. If the stylesheet is an external cross-domain a network request is made. An object representing the CSS Rules from each stylesheet is made available to the checks evaluate function as `preloadedAssets` at run-time | 603| `media` | This asset type preloads metadata information of any HTMLMediaElement in the specified document | 604 605The `timeout` attribute in the object configuration is `optional` and has a fallback default value (10000ms). The `timeout` is essential for any network dependent assets that are preloaded, where-in if a given request takes longer than the specified/ default value, the operation is aborted. 606 607##### Callback Parameter 608 609The callback parameter is a function that will be called when the asynchronous `axe.run` function completes. The callback function is passed two parameters. The first parameter will be an error thrown inside of axe if axe.run could not complete. If axe completed correctly the first parameter will be null, and the second parameter will be the results object. 610 611#### Return Promise 612 613If the callback was not defined, axe will return a Promise instead. Axe does not polyfill a Promise library however. So on systems without support for Promises this feature is not available. If you are unsure if the systems you will need axe on has Promise support we suggest you use the callback provided by axe.run instead. 614 615#### Error Result 616 617This will either be null or an object which is an instance of Error. If you are consistently receiving errors, please report this issue on the [Github issues list of Axe](https://github.com/dequelabs/axe-core/issues). 618 619#### Results Object 620 621The callback function passed in as the third parameter of `axe.run` runs on the results object. This object has four components – a `passes` array, a `violations` array, an `incomplete` array and an `inapplicable` array. 622 623The `passes` array keeps track of all the passed tests, along with detailed information on each one. This leads to more efficient testing, especially when used in conjunction with manual testing, as the user can easily find out what tests have already been passed. 624 625Similarly, the `violations` array keeps track of all the failed tests, along with detailed information on each one. 626 627The `incomplete` array (also referred to as the "review items") indicates which nodes could neither be determined to definitively pass or definitively fail. They are separated out in order that a user interface can display these to the user for manual review (hence the term "review items"). 628 629The `inapplicable` array lists all the rules for which no matching elements were found on the page. 630 631###### `url` 632 633The URL of the page that was tested. 634 635###### `timestamp` 636 637The date and time that analysis was completed. 638 639###### `testEngine` 640 641The application and version that ran the audit. 642 643###### `testEnvironment` 644 645Information about the current browser or node application that ran the audit. 646 647###### result arrays 648 649The results of axe are grouped according to their outcome into the following arrays: 650 651- `passes`: These results indicate what elements passed the rules 652- `violations`: These results indicate what elements failed the rules 653- `inapplicable`: These results indicate which rules did not run because no matching content was found on the page. For example, with no video, those rules won't run. 654- `incomplete`: These results were aborted and require further testing. This can happen either because of technical restrictions to what the rule can test, or because a javascript error occurred. 655 656Each object returned in these arrays have the following properties: 657 658- `description` - Text string that describes what the rule does 659- `help` - Help text that describes the test that was performed 660- `helpUrl` - URL that provides more information about the specifics of the violation. Links to a page on the Deque University site. 661- `id` - Unique identifier for the rule; [see the list of rules](rule-descriptions.md) 662- `impact` - How serious the violation is. Can be one of "minor", "moderate", "serious", or "critical" if the Rule failed or `null` if the check passed 663- `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 `axe.run` parameters for more information](#parameters-axerun)). 664- `nodes` - Array of all elements the Rule tested 665 - `html` - Snippet of HTML of the Element 666 - `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 667 - `target` - Array of either strings or Arrays of strings. If the item in the array is a string, then it is a CSS selector. If there are multiple items in the array each item corresponds 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`. If the item in the Array is an Array of strings, then it points to an element in a shadow DOM and each item (except the n-1th) in this array is a selector to a DOM element with a shadow DOM. The last element in the array points to the final shadow DOM node. 668 - `any` - Array of checks that were made where at least one must have passed. Each entry in the array contains: 669 - `id` - Unique identifier for this check. Check ids may be the same as Rule ids 670 - `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 671 - `message` - Description of why this check passed or failed 672 - `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. 673 - `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: 674 - `target` - Array of selectors for the related node 675 - `html` - HTML source of the related node 676 - `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 677 - `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 678 679#### Example 2 680 681In this example, we will pass the selector for the entire document, pass no options, which means all enabled rules will be run, and have a simple callback function that logs the entire results object to the console log: 682 683```js 684axe.run(document, function(err, results) { 685 if (err) throw err; 686 console.log(results); 687}); 688``` 689 690###### `passes` 691 692- `passes[0]` 693 ... 694 695 - `help` - `"Elements must have sufficient color contrast"` 696 - `helpUrl` - `"https://dequeuniversity.com/courses/html-css/visual-layout/color-contrast"` 697 - `id` - `"color-contrast"` 698 - `nodes` 699 - `target[0]` - `"#js_off-canvas-wrap > .inner-wrap >.kinja-title.proxima.js_kinja-title-desktop"` 700 701- `passes[1]` 702 ... 703 704###### `violations` 705 706- `violations[0]` 707 708 - `help` - `"<button> elements must have alternate text"` 709 - `helpUrl` - `"https://dequeuniversity.com/courses/html-css/forms/form-labels#id84_example_button"` 710 - `id` - `"button-name"` 711 - `nodes` 712 - `target[0]` - `"post_5919997 > .row.content-wrapper > .column > span > iframe"` 713 - `target[1]` - `"#u_0_1 > .pluginConnectButton > .pluginButtonImage > button"` 714 715- `violations[1]` ... 716 717##### `passes` Results Array 718 719In the example above, the `passes` array contains two entries that correspond to the two rules tested. The first element in the array describes a color contrast check. It relays the information that a list of nodes was checked and subsequently passed. The `help`, `helpUrl`, and `id` fields are returned as expected for each of the entries in the `passes` array. The `target` array has one element in it with a value of 720 721`#js_off-canvas-wrap > .inner-wrap >.kinja-title.proxima.js_kinja-title-desktop` 722 723This indicates that the element selected by the entry in `target[0]` was checked for the color contrast rule and that it passed the test. 724 725Each subsequent entry in the passes array has the same format, but will detail the different rules that were run as part of this call to `axe.run()`. 726 727##### `violations` Results Array 728 729The array of `violations` contains one entry; this entry describes a test that check if buttons have valid alternate text (button-name). This first entry in the array has the `help`, `helpUrl` and `id` fields returned as expected. 730 731The `target` array demonstrates how we specify the selectors when the node specified is inside of an `iframe` or `frame`. The first element in the `target` array - `target[0]` - specifies the selector to the `iframe` that contains the button. The second element in the `target` array - `target[1]` - specifies the selector to the actual button, but starting from inside the iframe selected in `target[0]`. 732 733Each subsequent entry in the violations array has the same format, but will detail the different rules that were run that generated accessibility violations as part of this call to `axe.run()`. 734 735#### Example 3 736 737In this example, we pass the selector for the entire document, enable two additional experimental rules, and have a simple callback function that logs the entire results object to the console log: 738 739```js 740axe.run( 741 document, 742 { 743 rules: { 744 'link-in-text-block': { enabled: true }, 745 'p-as-heading': { enabled: true } 746 } 747 }, 748 function(err, results) { 749 if (err) throw err; 750 console.log(results); 751 } 752); 753``` 754 755#### Example 4 756 757This example shows a result object that points to an open shadow DOM element. 758 759##### `violations[0]` 760 761```json 762{ 763 "help": "Elements must have sufficient color contrast", 764 "helpUrl": "https://dequeuniversity.com/rules/axe/2.1/color-contrast?application=axeAPI", 765 "id": "color-contrast", 766 "nodes": [ 767 { 768 "target": [["header > aria-menu", "li.expanded"]] 769 } 770 ] 771} 772``` 773 774As you can see the `target` array contains one item that is an array. This array contains two items, the first is a CSS selector string that finds the custom element `<aria-menu>` in the `<header>`. The second item in this array is the selector within that custom element's shadow DOM to find the `<li>` element with a class of `expanded`. 775 776### API Name: axe.registerPlugin 777 778Register a plugin with the axe plugin system. See [implementing a plugin](plugins.md) for more information on the plugin system 779 780### API Name: axe.cleanup 781 782Call each plugin's cleanup function. See [implementing a plugin](plugins.md). 783 784The signature is: 785 786```js 787axe.cleanup(resolve, reject); 788``` 789 790`resolve` and `reject` are functions that will be invoked on success or failure respectively. 791 792`resolve` takes no arguments and `reject` takes a single argument that must be a string or have a toString() method in its prototype. 793 794### Virtual DOM Utilities 795 796Note: If you’re writing rules or checks, you’ll have both the `node` and `virtualNode` passed in. 797But if you need to query the flattened tree, the documented function below should help. See the 798[developer guide](./developer-guide.md) for more information. 799 800#### API Name: axe.utils.querySelectorAll 801 802##### Description 803 804A querySelectorAll implementation that works on the virtual DOM and open Shadow DOM by manually walking the flattened tree instead of relying on DOM API methods which don’t step into Shadow DOM. 805 806Note: while there is no `axe.utils.querySelector` method, you can reproduce that behavior by accessing the first item returned in the array. 807 808##### Synopsis 809 810```js 811axe.utils.querySelectorAll(virtualNode, 'a[href]'); 812``` 813 814##### Parameters 815 816- `virtualNode` – object, the flattened DOM tree to query against. `axe._tree` is available for this purpose during an audit; see below. 817- `selector` – string, the [CSS selector](./developer-guide.md#supported-css-selectors) to use as a filter. For the most part, this should work seamlessly with `document.querySelectorAll`. 818 819##### Returns 820 821An Array of filtered HTML nodes. 822 823### Common Functions 824 825#### axe.commons.dom.getComposedParent 826 827Get an element's parent in the flattened tree 828 829##### Synopsis 830 831```js 832axe.commons.dom.getComposedParent(node); 833``` 834 835##### Parameters 836 837- `element` – HTMLElement. The element for which you want to find a parent 838 839##### Returns 840 841A DOMNode for the parent 842 843#### axe.commons.dom.getRootNode 844 845Return the document or document fragment (open shadow DOM) 846 847##### Synopsis 848 849```js 850axe.commons.dom.getRootNode(node); 851``` 852 853##### Parameters 854 855- `element` – HTMLElement. The element for which you want to find the root node 856 857##### Returns 858 859The top-level document or shadow DOM document fragment 860 861## Section 3: Example Reference 862 863This package contains examples for [jasmine](examples/jasmine), [mocha](examples/mocha), [phantomjs](examples/phantomjs), [qunit](examples/qunit), and [generating HTML from the violations array](examples/html-handlebars.md). Each of these examples is in the [doc/examples](examples) folder. In each folder, there is a README.md file which contains specific information about each example. 864 865See [axe-webdriverjs](https://github.com/dequelabs/axe-webdriverjs#axe-webdriverjs) for selenium webdriver javascript examples. 866 867## Section 4: Performance 868 869Axe-core performs very well in general and if you are analyzing average complexity pages with the default settings, you should not need to worry about performance at all. There are some scenarios that can cause performance issues. This is the list of known issues and what you can do to mitigate and/or avoid them. 870 871### Very large pages 872 873Certain rules (like the color-contrast rule) look at almost every element on a page and some of these rules also perform somewhat expensive operations on these elements including looking up the hierarchy, looking at overlapping elements, calculating the computed styles etc. It also calculates a unique selector for each element in the results and also de-duplicates elements so that you do not get duplicate items in your results. 874 875If your page is very large (in terms of the number of Elements on the page) i.e. >50K elements on the page, then you will see analysis times that run over 10s on a relatively decent CPU. 876 877#### Use resultTypes 878 879An approach you can take to reducing the time is use the `resultTypes` option. By calling `axe.run` with the following options, axe-core will only return the full details of the `violations` array and will only return one instance of each of the `inapplicable`, `incomplete` and `pass` arrays for each rule that has at least one of those entries. This will reduce the amount of computation that axe-core does for the unique selectors. 880 881```js 882axe.run( 883 { 884 resultTypes: ['violations'] 885 }, 886 (err, results) => { 887 // ... 888 } 889); 890``` 891 892### Other strategies 893 894#### Targeted color-contrast analysis 895 896If you are analyzing multiple pages on a single Web site or application, chances are these pages all contain the same styles. It is therefore not adding any additional information to your analysis to analyze every page for color-contrast. Choose a small number of pages that represent the totality of you styles and analyze these with color-contrast and analyze all others without it. 897