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.
paramName
( optional enumerated Type array of paramType )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
Parameters

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 and rules to Developer Tools' Audit panel.

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

Notes

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 chrome.experimental.devtools.audits.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 createResult() and addChild() methods. The child node may include specially formatted fragments created by auditResults.createSnippet() or auditResults.createURL().

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

Examples

You can find 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
( Type array of string )
A display name for the category.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
resultCount
( Type array of number )
The expected number of audit results in the category.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

paramName
( AuditCategory array of paramType )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Callback function

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

If you specify the callback parameter, it should specify a function that looks like this:

function(Type param1, Type param2) {...};

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Types

AuditCategory

paramName
( Type array of object )
A set of audit rules
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Events of AuditCategory

onAuditStarted

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

Fired when the audit is started, if the category is enabled -- the extension is expected to begin executing audit rules.

Listener parameters

results
( AuditResults array of paramType )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Extra parameters to addListener

Listener returns

FormattedValue

paramName
( Type array of object )
A value returned from one of the formatters (a URL, code snippet etc), to be passed to createResult or addChild.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

AuditResults

paramName
( Type array of object )
A collection of audit results for current run of the audit category.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
Severity
( AuditResultSeverity array of paramType )
A class that contains possible values for audit result severities.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
text
( Type array of string )
The contents of the node.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
children
( optional Type array of AuditResultNode array of paramType paramType )
Children of this node.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
expanded
( optional Type array of boolean )
Whether the node is expanded by default.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Methods of AuditResults

addResult

AuditCategory auditResults.addResult(, string displayName, string description, AuditResultSeverety severity, AuditResultNode details)

Adds an audit category.

Parameters

displayName
( Type array of string )
A concise, high-level description of audit rule result.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
description
( Type array of string )
A detailed description of what the displayName means.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
severity
( AuditResultSeverety array of number )
Undocumented.
The expected number of audit results in the category.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
details
( optional AuditResultNode array of number )
A subtree that appears under added result that may provide additional details on the violations found.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

paramName
( AuditCategory array of paramType )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Callback function

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

If you specify the callback parameter, it should specify a function that looks like this:

function(Type param1, Type param2) {...};

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

createResult

AuditResultNode auditResults.createResult(, string or FormattedValue content ...)

Creates a result node that may be user as details parameters to addResult.

Parameters

content ...
( Type array of 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.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

paramName
( AuditResultNode array of paramType )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Callback function

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

If you specify the callback parameter, it should specify a function that looks like this:

function(Type param1, Type param2) {...};

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

createSnippet

FormattedValue auditResults.createSnippet(, string text)

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

Parameters

text
( Type array of string )
Snippet text.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

paramName
( FormattedValue array of paramType )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Callback function

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

If you specify the callback parameter, it should specify a function that looks like this:

function(Type param1, Type param2) {...};

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

createURL

FormattedValue auditResults.createURL(, string href, string displayText)

Render passed value as a URL in the Audits panel

Parameters

href
( Type array of string )
A URL that will appear as the href value on the resulting link.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
displayText
( optional Type array of string )
A text that will appear to the user.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

paramName
( FormattedValue array of paramType )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Callback function

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

If you specify the callback parameter, it should specify a function that looks like this:

function(Type param1, Type param2) {...};

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

done

AuditCategory auditResults.done()

Signals the WebInspector Audits panel that the run of this category is over. Normally the run completes automatically when a number of added top-level results is equal to that declared when AuditCategory was created.

Parameters

displayName
( Type array of string )
A display name for the category.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
resultCount
( Type array of number )
The expected number of audit results in the category.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

paramName
( AuditCategory array of paramType )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Callback function

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

If you specify the callback parameter, it should specify a function that looks like this:

function(Type param1, Type param2) {...};

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

AuditResultNode

paramName
( Type array of object )
A node in the audit result tree. Displays some content and optionally has children node.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
expanded
( Type array of boolean )
If set, the subtree will always be expanded.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Methods of AuditResultNode

addChild

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

Adds another child node to this node.

Parameters

content ...
( Type array of 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.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Returns

paramName
( AuditResultNode array of paramType )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

Callback function

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

If you specify the callback parameter, it should specify a function that looks like this:

function(Type param1, Type param2) {...};

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.

AuditResultSeverity

paramName
( Type array of object )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
Info
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
Warning
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.
Severe
( Type array of string )
Undocumented.
Description of this parameter from the json schema.
This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won't be run in an earlier browser version.