chrome.experimental.devtools.audits

Description: Use the chrome.experimental.devtools.audits API to add new audit categories to the Developer Tools' Audit panel.
Availability: Warning: This is experimental. You must run Chrome with a special flag to use this API. Learn more.

See DevTools APIs summary for general introduction to using Developer Tools APIs.

Overview

Each audit category is represented by a line on Select audits to run screen in the Audits panel. The following example adds a category named Readability:

      var category = chrome.experimental.devtools.audits.addCategory("Readability", 2);
      
Extension audit category on the launch screen of Audits panel

If the category's checkbox is checked, the onAuditStarted event of that category will be fired when user clicks the Run button.

The event handler in your extension receives AuditResults as an argument and should add one or more results using addResult() method. This may be done asynchronously, i.e. after the handler returns. The run of the category is considered to be complete once the extension adds the number of results declared when adding the category with addCategory() or calls AuditResult's done() method.

The results may include additional details visualized as an expandable tree by the Audits panel. You may build the details tree using the createResult() and addChild() methods. The child node may include specially formatted fragments created by the auditResults.createSnippet() and auditResults.createURL() methods.

Examples

The following example adds a handler for onAuditStarted event that creates two audit results and populates one of them with the additional details:

      category.onAuditStarted.addListener(function(results) {
        var details = results.createResult("Details...");
        var styles = details.addChild("2 styles with small font");
        var elements = details.addChild("3 elements with small font");
      
        results.addResult("Font Size (5)",
            "5 elements use font size below 10pt",
            results.Severity.Severe,
            details);
        results.addResult("Contrast",
                          "Text should stand out from background",
                          results.Severity.Info);
      });
      

The audit result tree produced by the snippet above will look like this:

Audit results example

You can find more examples that use this API in Samples.

Summary

Types
AuditCategory
FormattedValue
AuditResults
AuditResultNode
AuditResultSeverity
Methods
addCategory AuditCategory chrome.experimental.devtools.audits.addCategory(string displayName, double resultCount)

Types

AuditCategory

A group of logically related audit checks.

onAuditStarted

If the category is enabled, this event is fired when the audit is started. The event handler is expected to initiate execution of the audit logic that will populate the results collection.

events

addListener

onAuditStarted.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function( AuditResults results) {...};
AuditResults results

FormattedValue

A value returned from one of the formatters (a URL, code snippet etc), to be passed to createResult() or addChild(). See AuditResults.createSnippet and AuditResults.createURL.

AuditResults

A collection of audit results for the current run of the audit category.
properties
AuditResultSeverity Severity

A class that contains possible values for the audit result severities.

string text

The contents of the node.

array of AuditResultNode (optional) children

Children of this node.

boolean (optional) expanded

Whether the node is expanded by default.

methods

addResult

AuditResults.addResult(string displayName, string description, AuditResultSeverity severity, AuditResultNode details)

Adds an audit result. The results are rendered as bulleted items under the audit category assoicated with the AuditResults object.

Parameters
string displayName

A concise, high-level description of the result.

string description

A detailed description of what the displayName means.

AuditResultSeverity severity
AuditResultNode (optional) details

A subtree that appears under the added result that may provide additional details on the violations found.

createResult

AuditResultNode AuditResults.createResult(string or FormattedValue content)

Creates a result node that may be used as the details parameters to the addResult() method.

Parameters
string or FormattedValue content

Since Chrome 26.

Either string or formatted values returned by one of the AuditResult formatters (a URL, a snippet etc). If multiple arguments are passed, these will be concatenated into a single node.

done

AuditResults.done()

Signals the DevTools Audits panel that the run of this category is over. The audit run also completes automatically when the number of added top-level results is equal to that declared when AuditCategory was created.

createURL

FormattedValue AuditResults.createURL(string href, string displayText)

Render passed value as a URL in the Audits panel.

Parameters
string href

A URL that appears as the href value on the resulting link.

string (optional) displayText

Text that appears to the user.

createSnippet

FormattedValue AuditResults.createSnippet(string text)

Render passed text as a code snippet in the Audits panel.

Parameters
string text

Snippet text.

AuditResultNode

A node in the audit result tree. Displays content and may optionally have children nodes.
properties
boolean expanded

If set, the subtree will always be expanded.

methods

addChild

AuditResultNode AuditResultNode.addChild(string or FormattedValue content)

Adds a child node to this node.

Parameters
string or FormattedValue content

Since Chrome 26.

Either string or formatted values returned by one of the AuditResult formatters (URL, snippet etc). If multiple arguments are passed, these will be concatenated into a single node.

AuditResultSeverity

This type contains possible values for a result severity. The results of different severities are distinguished by colored bullets near the result's display name.
properties
string Info
string Warning
string Severe

Methods

addCategory

AuditCategory chrome.experimental.devtools.audits.addCategory(string displayName, double resultCount)

Adds an audit category.

Parameters
string displayName

A display name for the category.

double resultCount

The expected number of audit results in the category.