You are viewing extension docs in chrome via the 'file:' scheme: are you expecting to see local changes when you refresh? You'll need run chrome with --allow-file-access-from-files.
WARNING: This is the BETA documentation. It may not work with the stable release of Chrome.
WARNING: This is unofficial documentation. It may not work with the current release of Chrome.

Google Chrome Extensions (Labs)

chrome.experimental.devtools.audits

For information on how to use experimental APIs, see the chrome.experimental.* APIs page.

Use the chrome.experimental.devtools.audits module to add new audit categories to Developer Tools' Audit panel.

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.

API reference: chrome.experimental.devtools.audits

Methods

addCategory

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

Adds an audit category.

Parameters

displayName
( string )
A display name for the category.
resultCount
( number )
The expected number of audit results in the category.

Returns

Undocumented.

Types

AuditCategory

( object )
A group of logically related audit checks.

Events of AuditCategory

onAuditStarted

auditCategory.onAuditStarted.addListener(function(AuditResults results) {...});

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.

Listener parameters

results
Undocumented.

FormattedValue

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

AuditResults

( object )
A collection of audit results for the current run of the audit category.
Severity
A class that contains possible values for the audit result severities.
text
( string )
The contents of the node.
children
( optional array of AuditResultNode )
Children of this node.
expanded
( optional boolean )
Whether the node is expanded by default.

Methods of AuditResults

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

displayName
( string )
A concise, high-level description of the result.
description
( string )
A detailed description of what the displayName means.
severity
Undocumented.
details
( optional AuditResultNode )
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

content ...
( string or FormattedValue )
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.

Returns

Undocumented.

createSnippet

FormattedValue auditResults.createSnippet(string text)

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

Parameters

text
( string )
Snippet text.

Returns

Undocumented.

createURL

FormattedValue auditResults.createURL(string href, string displayText)

Render passed value as a URL in the Audits panel.

Parameters

href
( string )
A URL that appears as the href value on the resulting link.
displayText
( optional string )
Text that appears to the user.

Returns

Undocumented.

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.

AuditResultNode

( object )
A node in the audit result tree. Displays content and may optionally have children nodes.
expanded
( boolean )
If set, the subtree will always be expanded.

Methods of AuditResultNode

addChild

AuditResultNode auditResultNode.addChild(string or FormattedValue content ...)

Adds a child node to this node.

Parameters

content ...
( string or FormattedValue )
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.

Returns

Undocumented.

AuditResultSeverity

( object )
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.
Info
( string )
Undocumented.
Warning
( string )
Undocumented.
Severe
( string )
Undocumented.