chrome/common/extensions/docs/templates/intros/experimental_devtools_audits.html

<p>
See <a href="experimental.devtools.html">DevTools APIs summary</a> for
general introduction to using Developer Tools APIs.
</p>

<h2 id="overview">Overview</h2>

<p>
Each audit category is represented by a line on <em>Select audits to run</em>
screen in the Audits panel. The following example adds a category named
<em>Readability</em>:</p>
<pre>
var category = chrome.experimental.devtools.audits.addCategory("Readability", 2);
</pre>
<img src="{{static}}/images/devtools-audits-category.png"
     style="margin-left: 20px"
     width="489" height="342"
     alt="Extension audit category on the launch screen of Audits panel" />
<p>
If the category's checkbox is checked, the <code>onAuditStarted</code> event of
that category will be fired when user clicks the <em>Run</em> button.
</p>
<p>The event handler in your extension receives <code>AuditResults</code>
as an argument and should add one or more results using <code>addResult()</code>
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
<code>addCategory()</code> or
calls AuditResult's <code>done()</code> method.
</p>
<p>The results may include additional details visualized as an expandable
tree by the Audits panel. You may build the details tree using the
<code>createResult()</code> and <code>addChild()</code> methods. The child node
may include specially formatted fragments created by the
<code>auditResults.createSnippet()</code>
and <code>auditResults.createURL()</code> methods.
</p>

<h2 id="examples">Examples</h2>
<p>The following example adds a handler for onAuditStarted event that creates
two audit results and populates one of them with the additional details:
</p>

<pre>
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);
});
</pre>
<p>The audit result tree produced by the snippet above will look like this:
</p>
<img src="{{static}}/images/devtools-audits-results.png"
     style="margin-left: 20px"
     width="330" height="169"
     alt="Audit results example" />

<p>
You can find more examples that use this API in
<a href="samples.html#devtools.audits">Samples</a>.
</p>