chrome/common/extensions/api/devtools/experimental_audits.json

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 [
   6   {
   7     "namespace": "experimental.devtools.audits",
   8     "description": "Use the <code>chrome.experimental.devtools.audits</code> API to add new audit categories to the Developer Tools' Audit panel.",
   9     "nocompile": true,
  10     "functions": [
  11       {
  12         "name": "addCategory",
  13         "type": "function",
  14         "description": "Adds an audit category.",
  15         "parameters": [
  16           { "name": "displayName", "type": "string", "description": "A display name for the category." },
  17           { "name": "resultCount", "type": "number", "description": "The expected number of audit results in the category." }
  18         ],
  19         "returns": {
  20           "$ref": "AuditCategory"
  21         }
  22       }
  23     ],
  24     "types": [
  25       {
  26         "id": "AuditCategory",
  27         "type": "object",
  28         "description": "A group of logically related audit checks.",
  29         "events": [
  30           {
  31             "name": "onAuditStarted",
  32             "type": "function",
  33             "description": "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 <code>results</code> collection.",
  34             "parameters": [
  35               { "name": "results", "$ref": "AuditResults" }
  36             ]
  37           }
  38         ]
  39       },
  40       {
  41         "id": "FormattedValue",
  42         "type": "object",
  43         "additionalProperties": { "type": "any" },
  44         "description": "A value returned from one of the formatters (a URL, code snippet etc), to be passed to <code>createResult()</code> or <code>addChild()</code>. See $(ref:AuditResults.createSnippet) and $(ref:AuditResults.createURL)."
  45       },
  46       {
  47         "id": "AuditResults",
  48         "type": "object",
  49         "description": "A collection of audit results for the current run of the audit category.",
  50         "functions": [
  51           {
  52             "name": "addResult",
  53             "type": "function",
  54             "description": "Adds an audit result. The results are rendered as bulleted items under the audit category assoicated with the <code>AuditResults</code> object.",
  55             "parameters": [
  56               {
  57                 "name": "displayName",
  58                 "type": "string",
  59                 "description": "A concise, high-level description of the result."
  60               },
  61               {
  62                 "name": "description",
  63                 "type": "string",
  64                 "description": "A detailed description of what the displayName means."
  65               },
  66               {
  67                 "name": "severity",
  68                 "$ref": "AuditResultSeverity"
  69               },
  70               {
  71                 "name": "details",
  72                 "$ref": "AuditResultNode",
  73                 "optional": true,
  74                 "description": "A subtree that appears under the added result that may provide additional details on the violations found."
  75               }
  76             ]
  77           },
  78           {
  79             "name": "createResult",
  80             "type": "function",
  81             "description": "Creates a result node that may be used as the <code>details</code> parameters to the <code>addResult()</code> method.",
  82             "parameters": [
  83               {
  84                 "name": "content",
  85                 "choices": [
  86                   { "type": "string" },
  87                   { "$ref": "FormattedValue" }
  88                 ],
  89                 "description": "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."
  90               }
  91             ],
  92             "returns": {
  93               "$ref": "AuditResultNode"
  94             }
  95           },
  96           {
  97             "name": "done",
  98             "type": "function",
  99             "description": "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."
 100           },
 101           {
 102             "name": "createURL",
 103             "type": "function",
 104             "description": "Render passed value as a URL in the Audits panel.",
 105             "parameters": [
 106               { "name": "href", "type": "string", "description": "A URL that appears as the href value on the resulting link." },
 107               { "name": "displayText", "type": "string", "description": "Text that appears to the user.", "optional": true }
 108             ],
 109             "returns": { "$ref": "FormattedValue" }
 110           },
 111           {
 112             "name": "createSnippet",
 113             "type": "function",
 114             "description": "Render passed text as a code snippet in the Audits panel.",
 115             "parameters": [
 116               { "name": "text", "type": "string", "description": "Snippet text." }
 117             ],
 118             "returns": { "$ref": "FormattedValue" }
 119           }
 120         ],
 121         "properties": {
 122           "Severity": {
 123             "$ref": "AuditResultSeverity",
 124             "description": "A class that contains possible values for the audit result severities."
 125           },
 126           "text": {
 127             "type": "string",
 128             "description": "The contents of the node."
 129           },
 130           "children": {
 131             "optional": true,
 132             "type": "array",
 133             "items": { "$ref": "AuditResultNode" },
 134             "description": "Children of this node."
 135           },
 136           "expanded": {
 137             "optional": true,
 138             "type": "boolean",
 139             "description": "Whether the node is expanded by default."
 140           }
 141         }
 142       },
 143       {
 144         "id": "AuditResultNode",
 145         "type": "object",
 146         "description": "A node in the audit result tree. Displays content and may optionally have children nodes.",
 147         "functions": [
 148           {
 149             "name": "addChild",
 150             "description": "Adds a child node to this node.",
 151             "parameters": [
 152               {
 153                 "name": "content",
 154                 "choices": [
 155                   { "type": "string" },
 156                   { "$ref": "FormattedValue" }
 157                 ],
 158                 "description": "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."
 159               }
 160             ],
 161             "returns": {
 162               "$ref": "AuditResultNode"
 163             }
 164           }
 165         ],
 166         "properties": {
 167           "expanded": {
 168             "type": "boolean",
 169             "description": "If set, the subtree will always be expanded."
 170           }
 171         }
 172       },
 173       {
 174         "id": "AuditResultSeverity",
 175         "type": "object",
 176         "description": "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.",
 177         "properties": {
 178           "Info": {
 179             "type": "string"
 180           },
 181           "Warning": {
 182             "type": "string"
 183           },
 184           "Severe": {
 185             "type": "string"
 186           }
 187         }
 188       }
 189     ]
 190   }
 191 ]