247be8cde220606c77207f6cd6d792ad56deff20
[WebKit-https.git] / Source / JavaScriptCore / inspector / protocol / Debugger.json
1 {
2     "domain": "Debugger",
3     "description": "Debugger domain exposes JavaScript debugging capabilities. It allows setting and removing breakpoints, stepping through execution, exploring stack traces, etc.",
4     "types": [
5         {
6             "id": "BreakpointId",
7             "type": "string",
8             "description": "Breakpoint identifier."
9         },
10         {
11             "id": "BreakpointActionIdentifier",
12             "type": "integer",
13             "description": "Breakpoint action identifier."
14         },
15         {
16             "id": "ScriptId",
17             "type": "string",
18             "description": "Unique script identifier."
19         },
20         {
21             "id": "CallFrameId",
22             "type": "string",
23             "description": "Call frame identifier."
24         },
25         {
26             "id": "Location",
27             "type": "object",
28             "properties": [
29                 { "name": "scriptId", "$ref": "ScriptId", "description": "Script identifier as reported in the <code>Debugger.scriptParsed</code>." },
30                 { "name": "lineNumber", "type": "integer", "description": "Line number in the script." },
31                 { "name": "columnNumber", "type": "integer", "optional": true, "description": "Column number in the script." }
32             ],
33             "description": "Location in the source code."
34         },
35         {
36             "id": "BreakpointAction",
37             "type": "object",
38             "properties": [
39                 { "name": "type", "type": "string", "enum": ["log", "evaluate", "sound", "probe"], "description": "Different kinds of breakpoint actions." },
40                 { "name": "data", "type": "string", "optional": true, "description": "Data associated with this breakpoint type (e.g. for type \"eval\" this is the JavaScript string to evalulate)." },
41                 { "name": "id", "$ref": "BreakpointActionIdentifier", "optional": true, "description": "A frontend-assigned identifier for this breakpoint action." }
42             ],
43             "description": "Action to perform when a breakpoint is triggered."
44         },
45         {
46             "id": "BreakpointOptions",
47             "type": "object",
48             "properties": [
49                 { "name": "condition", "type": "string", "optional": true, "description": "Expression to use as a breakpoint condition. When specified, debugger will only stop on the breakpoint if this expression evaluates to true." },
50                 { "name": "actions", "type": "array", "optional": true, "items": { "$ref": "BreakpointAction" }, "description": "Actions to perform automatically when the breakpoint is triggered." },
51                 { "name": "autoContinue", "type": "boolean", "optional": true, "description": "Automatically continue after hitting this breakpoint and running actions." }
52             ],
53             "description": "Extra options that modify breakpoint behavior."
54         },
55         {
56             "id": "FunctionDetails",
57             "type": "object",
58             "properties": [
59                 { "name": "location", "$ref": "Location", "description": "Location of the function." },
60                 { "name": "name", "type": "string", "optional": true, "description": "Name of the function. Not present for anonymous functions." },
61                 { "name": "displayName", "type": "string", "optional": true, "description": "Display name of the function(specified in 'displayName' property on the function object)." },
62                 { "name": "inferredName", "type": "string", "optional": true, "description": "Name of the function inferred from its initial assignment." },
63                 { "name": "scopeChain", "type": "array", "optional": true, "items": { "$ref": "Scope" }, "description": "Scope chain for this closure." }
64             ],
65             "description": "Information about the function."
66         },
67         {
68             "id": "CallFrame",
69             "type": "object",
70             "properties": [
71                 { "name": "callFrameId", "$ref": "CallFrameId", "description": "Call frame identifier. This identifier is only valid while the virtual machine is paused." },
72                 { "name": "functionName", "type": "string", "description": "Name of the JavaScript function called on this call frame." },
73                 { "name": "location", "$ref": "Location", "description": "Location in the source code." },
74                 { "name": "scopeChain", "type": "array", "items": { "$ref": "Scope" }, "description": "Scope chain for this call frame." },
75                 { "name": "this", "$ref": "Runtime.RemoteObject", "description": "<code>this</code> object for this call frame." }
76             ],
77             "description": "JavaScript call frame. Array of call frames form the call stack."
78         },
79         {
80             "id": "Scope",
81             "type": "object",
82             "properties": [
83                 { "name": "type", "type": "string", "enum": ["global", "local", "with", "closure", "catch", "functionName"], "description": "Scope type." },
84                 { "name": "object", "$ref": "Runtime.RemoteObject", "description": "Object representing the scope. For <code>global</code> and <code>with</code> scopes it represents the actual object; for the rest of the scopes, it is artificial transient object enumerating scope variables as its properties." }
85             ],
86             "description": "Scope description."
87         },
88         {
89             "id": "ProbeSample",
90             "description": "A sample collected by evaluating a probe breakpoint action.",
91             "type": "object",
92             "properties": [
93                 { "name": "probeId", "$ref": "BreakpointActionIdentifier", "description": "Identifier of the probe breakpoint action that created the sample." },
94                 { "name": "sampleId", "type": "integer", "description": "Unique identifier for this sample." },
95                 { "name": "batchId", "type": "integer", "description": "A batch identifier which is the same for all samples taken at the same breakpoint hit." },
96                 { "name": "timestamp", "type": "number", "description": "Timestamp of when the sample was taken." },
97                 { "name": "payload", "$ref": "Runtime.RemoteObject", "description": "Contents of the sample." }
98             ]
99         }
100     ],
101     "commands": [
102         {
103             "name": "enable",
104             "description": "Enables debugger for the given page. Clients should not assume that the debugging has been enabled until the result for this command is received."
105         },
106         {
107             "name": "disable",
108             "description": "Disables debugger for given page."
109         },
110         {
111             "name": "setBreakpointsActive",
112             "parameters": [
113                 { "name": "active", "type": "boolean", "description": "New value for breakpoints active state." }
114             ],
115             "description": "Activates / deactivates all breakpoints on the page."
116         },
117         {
118             "name": "setBreakpointByUrl",
119             "parameters": [
120                 { "name": "lineNumber", "type": "integer", "description": "Line number to set breakpoint at." },
121                 { "name": "url", "type": "string", "optional": true, "description": "URL of the resources to set breakpoint on." },
122                 { "name": "urlRegex", "type": "string", "optional": true, "description": "Regex pattern for the URLs of the resources to set breakpoints on. Either <code>url</code> or <code>urlRegex</code> must be specified." },
123                 { "name": "columnNumber", "type": "integer", "optional": true, "description": "Offset in the line to set breakpoint at." },
124                 { "name": "options", "$ref": "BreakpointOptions", "optional": true, "description": "Options to apply to this breakpoint to modify its behavior." }
125             ],
126             "returns": [
127                 { "name": "breakpointId", "$ref": "BreakpointId", "description": "Id of the created breakpoint for further reference." },
128                 { "name": "locations", "type": "array", "items": { "$ref": "Location"}, "description": "List of the locations this breakpoint resolved into upon addition." }
129             ],
130             "description": "Sets JavaScript breakpoint at given location specified either by URL or URL regex. Once this command is issued, all existing parsed scripts will have breakpoints resolved and returned in <code>locations</code> property. Further matching script parsing will result in subsequent <code>breakpointResolved</code> events issued. This logical breakpoint will survive page reloads."
131         },
132         {
133             "name": "setBreakpoint",
134             "parameters": [
135                 { "name": "location", "$ref": "Location", "description": "Location to set breakpoint in." },
136                 { "name": "options", "$ref": "BreakpointOptions", "optional": true, "description": "Options to apply to this breakpoint to modify its behavior." }
137             ],
138             "returns": [
139                 { "name": "breakpointId", "$ref": "BreakpointId", "description": "Id of the created breakpoint for further reference." },
140                 { "name": "actualLocation", "$ref": "Location", "description": "Location this breakpoint resolved into." }
141             ],
142             "description": "Sets JavaScript breakpoint at a given location."
143         },
144         {
145             "name": "removeBreakpoint",
146             "parameters": [
147                 { "name": "breakpointId", "$ref": "BreakpointId" }
148             ],
149             "description": "Removes JavaScript breakpoint."
150         },
151         {
152             "name": "continueToLocation",
153             "parameters": [
154                 { "name": "location", "$ref": "Location", "description": "Location to continue to." }
155             ],
156             "description": "Continues execution until specific location is reached."
157         },
158         {
159             "name": "stepOver",
160             "description": "Steps over the statement."
161         },
162         {
163             "name": "stepInto",
164             "description": "Steps into the function call."
165         },
166         {
167             "name": "stepOut",
168             "description": "Steps out of the function call."
169         },
170         {
171             "name": "pause",
172             "description": "Stops on the next JavaScript statement."
173         },
174         {
175             "name": "resume",
176             "description": "Resumes JavaScript execution."
177         },
178         {
179             "name": "searchInContent",
180             "parameters": [
181                 { "name": "scriptId", "$ref": "ScriptId", "description": "Id of the script to search in." },
182                 { "name": "query", "type": "string", "description": "String to search for."  },
183                 { "name": "caseSensitive", "type": "boolean", "optional": true, "description": "If true, search is case sensitive." },
184                 { "name": "isRegex", "type": "boolean", "optional": true, "description": "If true, treats string parameter as regex." }
185             ],
186             "returns": [
187                 { "name": "result", "type": "array", "items": { "$ref": "GenericTypes.SearchMatch" }, "description": "List of search matches." }
188             ],
189             "description": "Searches for given string in script content."
190         },
191         {
192             "name": "getScriptSource",
193             "parameters": [
194                 { "name": "scriptId", "$ref": "ScriptId", "description": "Id of the script to get source for." }
195             ],
196             "returns": [
197                 { "name": "scriptSource", "type": "string", "description": "Script source." }
198             ],
199             "description": "Returns source for the script with given id."
200         },
201         {
202             "name": "getFunctionDetails",
203             "parameters": [
204                 { "name": "functionId", "$ref": "Runtime.RemoteObjectId", "description": "Id of the function to get location for." }
205             ],
206             "returns": [
207                 { "name": "details", "$ref": "FunctionDetails", "description": "Information about the function." }
208             ],
209             "description": "Returns detailed informtation on given function."
210         },
211         {
212             "name": "setPauseOnExceptions",
213             "parameters": [
214                 { "name": "state", "type": "string", "enum": ["none", "uncaught", "all"], "description": "Pause on exceptions mode." }
215             ],
216             "description": "Defines pause on exceptions state. Can be set to stop on all exceptions, uncaught exceptions or no exceptions. Initial pause on exceptions state is <code>none</code>."
217         },
218         {
219             "name": "evaluateOnCallFrame",
220             "parameters": [
221                 { "name": "callFrameId", "$ref": "CallFrameId", "description": "Call frame identifier to evaluate on." },
222                 { "name": "expression", "type": "string", "description": "Expression to evaluate." },
223                 { "name": "objectGroup", "type": "string", "optional": true, "description": "String object group name to put result into (allows rapid releasing resulting object handles using <code>releaseObjectGroup</code>)." },
224                 { "name": "includeCommandLineAPI", "type": "boolean", "optional": true, "description": "Specifies whether command line API should be available to the evaluated expression, defaults to false." },
225                 { "name": "doNotPauseOnExceptionsAndMuteConsole", "type": "boolean", "optional": true, "description": "Specifies whether evaluation should stop on exceptions and mute console. Overrides setPauseOnException state." },
226                 { "name": "returnByValue", "type": "boolean", "optional": true, "description": "Whether the result is expected to be a JSON object that should be sent by value." },
227                 { "name": "generatePreview", "type": "boolean", "optional": true, "description": "Whether preview should be generated for the result." }
228             ],
229             "returns": [
230                 { "name": "result", "$ref": "Runtime.RemoteObject", "description": "Object wrapper for the evaluation result." },
231                 { "name": "wasThrown", "type": "boolean", "optional": true, "description": "True if the result was thrown during the evaluation." }
232             ],
233             "description": "Evaluates expression on a given call frame."
234         },
235         {
236             "name": "setOverlayMessage",
237             "parameters": [
238                 { "name": "message", "type": "string", "optional": true, "description": "Overlay message to display when paused in debugger." }
239             ],
240             "description": "Sets overlay message."
241         }
242     ],
243     "events": [
244         {
245             "name": "globalObjectCleared",
246             "description": "Called when global has been cleared and debugger client should reset its state. Happens upon navigation or reload."
247         },
248         {
249             "name": "scriptParsed",
250             "parameters": [
251                 { "name": "scriptId", "$ref": "ScriptId", "description": "Identifier of the script parsed." },
252                 { "name": "url", "type": "string", "description": "URL or name of the script parsed (if any)." },
253                 { "name": "startLine", "type": "integer", "description": "Line offset of the script within the resource with given URL (for script tags)." },
254                 { "name": "startColumn", "type": "integer", "description": "Column offset of the script within the resource with given URL." },
255                 { "name": "endLine", "type": "integer", "description": "Last line of the script." },
256                 { "name": "endColumn", "type": "integer", "description": "Length of the last line of the script." },
257                 { "name": "isContentScript", "type": "boolean", "optional": true, "description": "Determines whether this script is a user extension script." },
258                 { "name": "sourceMapURL", "type": "string", "optional": true, "description": "URL of source map associated with script (if any)." },
259                 { "name": "hasSourceURL", "type": "boolean", "optional": true, "description": "True, if this script has sourceURL." }
260             ],
261             "description": "Fired when virtual machine parses script. This event is also fired for all known and uncollected scripts upon enabling debugger."
262         },
263         {
264             "name": "scriptFailedToParse",
265             "parameters": [
266                 { "name": "url", "type": "string", "description": "URL of the script that failed to parse." },
267                 { "name": "scriptSource", "type": "string", "description": "Source text of the script that failed to parse." },
268                 { "name": "startLine", "type": "integer", "description": "Line offset of the script within the resource." },
269                 { "name": "errorLine", "type": "integer", "description": "Line with error." },
270                 { "name": "errorMessage", "type": "string", "description": "Parse error message." }
271             ],
272             "description": "Fired when virtual machine fails to parse the script."
273         },
274         {
275             "name": "breakpointResolved",
276             "parameters": [
277                 { "name": "breakpointId", "$ref": "BreakpointId", "description": "Breakpoint unique identifier." },
278                 { "name": "location", "$ref": "Location", "description": "Actual breakpoint location." }
279             ],
280             "description": "Fired when breakpoint is resolved to an actual script and location."
281         },
282         {
283             "name": "paused",
284             "parameters": [
285                 { "name": "callFrames", "type": "array", "items": { "$ref": "CallFrame" }, "description": "Call stack the virtual machine stopped on." },
286                 { "name": "reason", "type": "string", "enum": [ "XHR", "DOM", "EventListener", "exception", "assert", "CSPViolation", "other" ], "description": "Pause reason." },
287                 { "name": "data", "type": "object", "optional": true, "description": "Object containing break-specific auxiliary properties." }
288             ],
289             "description": "Fired when the virtual machine stopped on breakpoint or exception or any other stop criteria."
290         },
291         {
292             "name": "resumed",
293             "description": "Fired when the virtual machine resumed execution."
294         },
295         {
296             "name": "didSampleProbe",
297             "description": "Fires when a new probe sample is collected.",
298             "parameters": [
299                 { "name": "sample", "$ref": "ProbeSample", "description": "A collected probe sample." }
300             ]
301         },
302         {
303             "name": "playBreakpointActionSound",
304             "description": "Fired when a \"sound\" breakpoint action is triggered on a breakpoint.",
305             "parameters": [
306                 { "name": "breakpointActionId", "$ref": "BreakpointActionIdentifier", "description": "Breakpoint action identifier." }
307             ]
308         }
309     ]
310 }