Web Inspector ReferenceAudit Tab

Contents

• Running Audits
• Audit Results
• Sharing Audits
• Default Audits
• Editing Audits
• Creating Audits

The Audit Tab contains collections of audits, each of which can be run against the inspected page to check for incorrect DOM structure, missing accessibility attributes, correct design system rules, and much more. An audit can be either a group of other audits (e.g. a test group), or an individual test case, which is essentially a snippet of JavaScript that will be executed in the inspected page when run.

Running Audits

When the Start button is clicked, all enabled audits are run one by one in the order they appear in the Navigation Sidebar. Individual audits can be run by clicking the [Start] button that appears on hover. Pressing space will also run the selected audit.

Once an audit finishes running, results are shown inline, replacing any results from any previous results. Additionally, results are saved in separate Run 1, Run 2, …, Run N folders underneath a top-level Results folder in the Navigation Sidebar.

Audit Results

Each test case can have one of five different results.

• Pass represents a result where no issues were identified.
• Warning is a “pass with issues” in that there was nothing critically wrong, but there were things that should be changed.
• Failed means that critical issues were found.
• Error occurs if the test function threw an error while running.
• Unsupported is a special case that can be used to indicate when the data being tested isn’t supported by the current page (e.g. missing some API).

In addition to the result level, the start and elapsed time are shown for each individual test case. For imported test case results, the URL of the page the test case was run against is also shown.

Sharing Audits

All audits can be exported by clicking Export, pressing ⌘ S, or right-clicking and selecting Save Test (or Save Result). Previously exported audits can later be imported by clicking Import or via drag-and-drop, regardless of whether that particular audit is able to be run on the current page. Imported audits are also preserved across Web Inspector sessions.

Audit results are similarly exportable or importable, and although they are preserved across inspected page navigations, they are not preserved across Web Inspector sessions. If an test case result includes DOM nodes and was run on a page with the same URL as the inspected page, Web Inspector will attempt to find nodes in the inspected page that have the same CSS path, showing previews as if they were logged to the console for any matching nodes.

Default Audits

Web Inspector also provides a few audits by default:

• Demo Audit is a comprehensive tour of the functionality and interface of audits, and can be used as a starter template for writing custom audits.
• Accessibility includes a handful of test cases that check for DOM accessibility best practices on the inspected page in accordance with the WAI-ARIA specification, such ensuring that a title or alt is set on all <img>.

These default audits cannot be modified or removed, only disabled.

Editing Audits

Clicking the Edit button at the bottom of the Navigation Sidebar will enter Edit Mode where audits can be created, modified, enabled/disabled, and even entirely removed (NOTE: this cannot be undone). This is true for both individual test cases and entire groups, allowing for more control over which tests run and what they do. Disabled audits are hidden when not in Edit Mode.

Audits can be deleted when in Edit Mode by pressing delete.

Creating Audits

In addition to the default audits provided by Web Inspector and any new audits created in Web Inspector when in Edit Mode, it’s also possible to import custom audits into Web Inspector from a file. Audits use a simple and highly flexible JSON structure, of which there are two main types:

• groups

{
    "type": "test-group",
    "name": "...",
    "tests": [<audit 1>, <audit 2>, ..., <audit N>]
}

• test cases

{
    "type": "test-case",
    "name": "...",
    "test": "function() { ... }"
}

Each field of these structures has a specific input in Web Inspector when in Edit Mode.

async functions are allowed, as well as non-async functions that return a Promise. The only requirement is that the return value of the function or resolved Promise value conforms to the following rules:

• Returning true/false will translate to a Pass/Fail result with no additional data.
• Returning a string will translate to the corresponding result (e.g. "pass" is a Pass result) with no additional data.
• Returning an object gives the most flexibility, as it allows for additional data other than the audit’s result to be displayed in the Audit Tab. Result levels are first retrieved from the "level" property (if it exists), and are translated in the same way as if a string was returned (e.g. "level": "pass" is a Pass result). Alternatively, using any level as a key with a value of true will have the same effect (e.g. "pass": true). Additionally, there are three pieces of data that can be returned as part of the result object that have dedicated specialized interfaces:
  • domNodes is an array of DOM nodes that will be displayed in the Audit Tab much the same as if they were logged to the console.
  • domAttributes is an array of strings, each of which will be highlighted (if present) on any DOM nodes within domNodes.
  • errors is an array of Error and can be used as a way of exposing errors encountered while running the audit.
    • If this array has any values, the result of the audit is automatically changed to Error.
    • If an error is thrown while running an audit, it will automatically be added to this list.

Other custom data added to the result object will be displayed in the Audit Tab. Version 3

The audit JSON structure also support the following optional properties:

• description is a basic string that is displayed in the Audit Tab as a way of providing more information about that specific audit, such as what it does or what it’s trying to test.
• supports can be used as an alternative to feature checking, in that it prevents the audit from even being run unless the number value matches Web Inspector’s audit version number, which can be found at the bottom of the Main Content Area in the Audit Tab when in Edit Mode. The current version is 4.
• setup is a string similar to a test case’s test function, except that it is allowed on groups and only has an effect when supplied for a top-level audit (i.e. audits that are not inside a group). setup is evaluated before the rest of the audit runs, allowing for an easy way for code to be shared between all audits in a group without having to worry about which audits in that group are enabled/disabled. Version 2

Special Audit Functions

Since audits are run from Web Inspector, additional information is exposed to each test function being executed. This data available in Web Inspector is not accessible via JavaScript in any way.

The information is exposed via a WebInspectorAudit object that is exposed to each test function. Note that WebInspectorAudit is shared between all test functions under a given top-level audit. As such, attaching data to WebInspectorAudit to be shared between multiple test functions is accepted and encouraged, so long as that data doesn’t override any of the properties below.

Version

Accessing Web Inspector’s audit version number from within a test function is as simple as getting the value of WebInspectorAudit.Version. This number is also shown at the bottom of the Main Content Area in the Audit Tab when in Edit Mode. The current version is 4.

Resources

The following all relate to dealing with resources loaded by the page, and are held by WebInspectorAudit.Resources.

• getResources() returns a list of objects, each corresponding to a specific resource loaded by the inspected page, identified by a string url, string mimeType, and audit-specific id.
• getResourceContent(id) returns an object with the string data and boolean base64Encoded contents of the resource with the given audit-specific id.

DOM

The following all relate to dealing with the DOM, and are held by WebInspectorAudit.Resources.

• hasEventListeners(node[, type]) returns true/false depending on whether the given DOM node has any event listeners, or has an event listener for the given type (if specified).
• simulateUserInteraction(callback) will execute the given callback as though it was triggered by the user. Version 4

Accessibility

The following all relate to dealing with the accessibility tree, and are held by WebInspectorAudit.Accessibility. Further information can be found in the WAI-ARIA specification.

• getElementsByComputedRole(role[, container]) returns an array of DOM nodes that match the given role that are children of the container DOM node (if specified) or the main document.
• getActiveDescendant(node) returns the active descendant of the given DOM node.
• getMouseEventNode(node) returns the DOM node that would handle mouse events which is or is a child of the given DOM node.
• getParentNode(node) returns the parent DOM node of the given DOM node in the accessibility tree.
• getChildNodes(node) returns an array of DOM nodes that are children of the given DOM node in the accessibility tree.
• getSelectedChildNodes(node) returns an array of currently selected DOM nodes that are children of the given DOM node in the accessibility tree.
• getControlledNodes(node) returns an array of DOM nodes that are controlled by the given DOM node.
• getFlowedNodes(node) returns an array of DOM nodes that are flowed to from the given DOM node.
• getOwnedNodes(node) returns an array of DOM nodes that are owned by the given DOM node.
• getComputedProperties(node) returns an object that contains various accessibility properties for the given DOM node. Since HTML allows for “incorrect” values in markup (e.g. an invalid value for an attribute), the following properties use the computed value determined by WebKit:
  • busy is a boolean related to the aria-busy attribute.
  • checked is a string related to the aria-checked attribute.
  • currentState is a string related to the aria-current attribute.
  • disabled is a boolean related to the aria-disabled attribute.
  • expanded is a boolean related to the aria-expanded attribute.
  • focused is a boolean that indicates whether the given node is focused.
  • headingLevel is a number related to the aria-level attribute and the various HTML heading elements.
  • hidden is a boolean related to the aria-hidden attribute.
  • hierarchicalLevel is a number related to the aria-level attribute.
  • ignored is a boolean that indicates whether the given node is currently being ignored in the accessibility tree.
  • ignoredByDefault is a boolean that indicates whether the given node is always ignored by the accessibility tree.
  • invalidStatus is a string related to the aria-invalid attribute.
  • isPopUpButton is a boolean related to the aria-haspopup attribute.
  • label is a string related to the aria-label attribute
  • liveRegionAtomic is a boolean related to the aria-atomic attribute.
  • liveRegionRelevant is an array of strings related to the aria-relevant attribute.
  • liveRegionStatus is a string related to the aria-live attribute.
  • pressed is a boolean related to the aria-pressed attribute.
  • readonly is a boolean related to the aria-readonly attribute.
  • required is a boolean related to the aria-required attribute.
  • role is a string related to the role attribute.
  • selected is a boolean related to the aria-selected attribute.