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
  1. Properties
    1. propertyName
  2. Methods
    1. methodName
  3. Events
    1. eventName
  4. Types
    1. id

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
( 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 group of logically related audit checks.
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) {...});

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
( 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(). See createSnippet() and createURL().
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 the 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 the 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, 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
( Type array of string )
A concise, high-level description of the 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
( AuditResultSeverity 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 the 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 used as the details parameters to the addResult() method.

Parameters

content ...
( Type array of 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.
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 appears 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 )
Text that appears 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 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.

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 content and may optionally have children nodes.
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 a 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 )
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.
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.