Web Inspector: move Mac-specific automation commands to a separate implementation...
[WebKit-https.git] / Source / WebKit2 / UIProcess / Automation / Automation.json
1 {
2     "domain": "Automation",
3     "description": "Automation domain exposes commands for automating user interactions with the browser.",
4     "types": [
5         {
6             "id": "Point",
7             "type": "object",
8             "properties": [
9                 { "name": "x", "type": "number" },
10                 { "name": "y", "type": "number" }
11             ]
12         },
13         {
14             "id": "Size",
15             "type": "object",
16             "properties": [
17                 { "name": "width", "type": "number" },
18                 { "name": "height", "type": "number" }
19             ]
20         },
21         {
22             "id": "Rect",
23             "type": "object",
24             "properties": [
25                 { "name": "origin", "$ref": "Point" },
26                 { "name": "size", "$ref": "Size" }
27             ]
28         },
29         {
30             "id": "BrowsingContextHandle",
31             "type": "string",
32             "description": "An opaque identifier for a browsing context."
33         },
34         {
35             "id": "FrameHandle",
36             "type": "string",
37             "description": "An opaque identifier for a frame in a page."
38         },
39         {
40             "id": "NodeHandle",
41             "type": "string",
42             "description": "An opaque identifier for a node in a page."
43         },
44         {
45             "id": "ErrorMessage",
46             "type": "string",
47             "description": "This enum contains predefined error messages that can be used to signal a well-defined error condition, such as a missing implementation, unknown window handle, and so forth. The backend signals one of these errors by using it as a prefix of the commands's error message (the errorString argument in generated C++ backend dispatchers). This will be reported to the frontend as a protocol error with a JSON-RPC error code of 'ServerError'. It is up to the frontend whether and how to deal with errors.",
48             "enum": [
49                 "InternalError",
50                 "Timeout",
51                 "JavaScriptError",
52                 "JavaScriptTimeout",
53                 "WindowNotFound",
54                 "FrameNotFound",
55                 "NodeNotFound",
56                 "InvalidElementState",
57                 "NoJavaScriptDialog",
58                 "NotImplemented",
59                 "MissingParameter",
60                 "InvalidParameter"
61             ]
62         },
63         {
64             "id": "BrowsingContext",
65             "type": "object",
66             "description": "A handle representing an open window or tab in the automation session.",
67             "properties": [
68                 { "name": "handle", "$ref": "BrowsingContextHandle", "description": "Opaque handle for a browsing context (window or tab). Used as a key for window-related commands." },
69                 { "name": "active", "type": "boolean", "description": "Whether the browsing context has focus at the time the command is handled." },
70                 { "name": "url", "type": "string", "description": "The URL loaded by the browsing context at the time the command is handled." },
71                 { "name": "windowSize", "$ref": "Size", "description": "The current size of the browsing context's window." },
72                 { "name": "windowOrigin", "$ref": "Point", "description": "The current (x, y) position of the browsing context's window relative to the top-left of the screen." }
73             ]
74         },
75         {
76             "id": "MouseInteraction",
77             "type": "string",
78             "description": "Enumerates different ways of interacting with a mouse cursor.",
79             "enum": [
80                 "Move",
81                 "Down",
82                 "Up",
83                 "SingleClick",
84                 "DoubleClick"
85             ]
86         },
87         {
88             "id": "MouseButton",
89             "type": "string",
90             "description": "Enumerates different mouse buttons that can be used.",
91             "enum": [
92                 "None",
93                 "Left",
94                 "Middle",
95                 "Right"
96             ]
97         },
98         {
99             "id": "KeyModifier",
100             "type": "string",
101             "description": "Enumerates different key modifiers that can remain pressed during other mouse/touch interactions.",
102             "enum": [
103                 "CapsLock",
104                 "Control",
105                 "Shift",
106                 "Meta",
107                 "Alt"
108             ]
109         },
110         {
111             "id": "VirtualKey",
112             "type": "string",
113             "description": "Enumerates different platform-independent virtual keys on a physical keyboard whose input via keyboard may or may not produce characters.",
114             "enum": [
115                 "Shift",
116                 "Control",
117                 "Alternate",
118                 "Meta",
119                 "Command",
120                 "Cancel",
121                 "Help",
122                 "Backspace",
123                 "Tab",
124                 "Clear",
125                 "Enter",
126                 "Pause",
127                 "Escape",
128                 "PageUp",
129                 "PageDown",
130                 "End",
131                 "Home",
132                 "LeftArrow",
133                 "UpArrow",
134                 "RightArrow",
135                 "DownArrow",
136                 "Insert",
137                 "Delete",
138                 "Space",
139                 "Semicolon",
140                 "Equals",
141                 "Return",
142                 "NumberPad0",
143                 "NumberPad1",
144                 "NumberPad2",
145                 "NumberPad3",
146                 "NumberPad4",
147                 "NumberPad5",
148                 "NumberPad6",
149                 "NumberPad7",
150                 "NumberPad8",
151                 "NumberPad9",
152                 "NumberPadMultiply",
153                 "NumberPadAdd",
154                 "NumberPadSeparator",
155                 "NumberPadSubtract",
156                 "NumberPadDecimal",
157                 "NumberPadDivide",
158                 "Function1",
159                 "Function2",
160                 "Function3",
161                 "Function4",
162                 "Function5",
163                 "Function6",
164                 "Function7",
165                 "Function8",
166                 "Function9",
167                 "Function10",
168                 "Function11",
169                 "Function12"
170             ]
171         },
172         {
173             "id": "KeyboardInteractionType",
174             "type": "string",
175             "description": "Enumerates different ways of interacting with a keyboard device. 'InsertByKey' implies that a separate KeyDown and KeyUp event are produced for each combining character sequence, regardless of the actual keystrokes required to produce the character sequence.",
176             "enum": [
177                 "KeyPress",
178                 "KeyRelease",
179                 "InsertByKey"
180             ]
181         },
182         {
183             "id": "KeyboardInteraction",
184             "type": "object",
185             "description": "A single step in a key sequence. A step can contain a key up/down of a virtual key, or a sequence of Unicode code points that are delivered to the page at grapheme cluster boundaries. Either a 'key' or 'text' property must be specified.",
186             "properties": [
187                 { "name": "type", "$ref": "KeyboardInteractionType", "description": "The type of interaction to be performed by a step." },
188                 { "name": "key", "$ref": "VirtualKey", "optional": true, "description": "A virtual key to be used to perform the specified interaction." },
189                 { "name": "text", "type": "string", "optional": true, "description": "A unicode string to be delivered to the page. The sequence of key events is determined by splitting the string at grapheme cluster boundaries." }
190             ]
191         },
192         {
193             "id": "Cookie",
194             "type": "object",
195             "properties": [
196                 { "name": "name", "type": "string", "description": "Cookie name." },
197                 { "name": "value", "type": "string", "description": "Cookie value." },
198                 { "name": "domain", "type": "string", "description": "Cookie domain. If empty, the domain is inherited from the relevant browsing context." },
199                 { "name": "path", "type": "string", "description": "Cookie path." },
200                 { "name": "expires", "type": "number", "description": "Cookie expiration in seconds since the UNIX epoch." },
201                 { "name": "size", "type": "integer", "description": "Cookie size." },
202                 { "name": "httpOnly", "type": "boolean", "description": "True if cookie is http-only." },
203                 { "name": "secure", "type": "boolean", "description": "True if cookie is secure." },
204                 { "name": "session", "type": "boolean", "description": "True in case of session cookie." }
205             ]
206         }
207     ],
208     "commands": [
209         {
210             "name": "getBrowsingContexts",
211             "description": "Fetches information about all open browsing contexts (windows and tabs) in the automation session.",
212             "returns": [
213                 { "name": "contexts", "type": "array", "items": { "$ref": "BrowsingContext" }, "description": "All known browsing contexts available to the session." }
214             ]
215         },
216         {
217             "name": "getBrowsingContext",
218             "description": "Fetches information about the specified browsing context.",
219             "parameters": [
220                 { "name": "handle", "$ref": "BrowsingContextHandle", "description": "The handle for the browsing context." }
221             ],
222             "returns": [
223                 { "name": "context", "$ref": "BrowsingContext", "description": "The browsing context available to the session." }
224             ]
225         },
226         {
227             "name": "createBrowsingContext",
228             "description": "Opens a new browsing context in the automation session and makes it the active browsing context for user interaction. This command creates a browsing context in a new window rather than adding a tab to an existing window.",
229             "returns": [
230                 { "name": "handle", "$ref": "BrowsingContextHandle", "description": "An opaque handle for the newly created browsing context." }
231             ]
232         },
233         {
234             "name": "closeBrowsingContext",
235             "description": "Try to close the specified browsing context. This can trigger an unload prompt and thereafter succeed or fail.",
236             "parameters": [
237                 { "name": "handle", "$ref": "BrowsingContextHandle", "description": "The handle for the browsing context that should be closed." }
238             ]
239         },
240         {
241             "name": "switchToBrowsingContext",
242             "description": "Activates the specified browsing context and optional frame, which gives them focus (causing the 'focus' DOM event to fire, and 'blur' DOM event to fire for the previous browsing context and frame).",
243             "parameters": [
244                 { "name": "browsingContextHandle", "$ref": "BrowsingContextHandle", "description": "The handle for the browsing context that should be made focused." },
245                 { "name": "frameHandle", "$ref": "FrameHandle", "optional": true, "description": "The handle for the frame that should be focused. Defaults to the main frame if omitted." }
246             ]
247         },
248         {
249             "name": "resizeWindowOfBrowsingContext",
250             "description": "Resizes the window of the specified browsing context to the specified size.",
251             "platform": "macOS",
252             "parameters": [
253                 { "name": "handle", "$ref": "BrowsingContextHandle", "description": "The handle for the browsing context to be resized." },
254                 { "name": "size", "$ref": "Size", "description": "The new size for the browsing context's window." }
255             ]
256         },
257         {
258             "name": "moveWindowOfBrowsingContext",
259             "description": "Moves the window of the specified browsing context to the specified position.",
260             "platform": "macOS",
261             "parameters": [
262                 { "name": "handle", "$ref": "BrowsingContextHandle", "description": "The handle for the browsing context to be moved." },
263                 { "name": "origin", "$ref": "Point", "description": "The new origin for the browsing context's window. The position is interpreted in screen coordinate space, relative to the upper left corner of the screen." }
264             ]
265         },
266         {
267             "name": "navigateBrowsingContext",
268             "description": "Navigates a browsing context to a specified URL.",
269             "parameters": [
270                 { "name": "handle", "$ref": "BrowsingContextHandle", "description": "The handle for the browsing context that should be navigated." },
271                 { "name": "url", "type": "string", "description": "The URL to load in the browsing context." }
272             ],
273             "async": true
274         },
275         {
276             "name": "goBackInBrowsingContext",
277             "description": "Navigates a browsing context to go back one page in history.",
278             "parameters": [
279                 { "name": "handle", "$ref": "BrowsingContextHandle", "description": "The handle for the browsing context that should be navigated." }
280             ],
281             "async": true
282         },
283         {
284             "name": "goForwardInBrowsingContext",
285             "description": "Navigates a browsing context to got forward one page in history.",
286             "parameters": [
287                 { "name": "handle", "$ref": "BrowsingContextHandle", "description": "The handle for the browsing context that should be navigated." }
288             ],
289             "async": true
290         },
291         {
292             "name": "reloadBrowsingContext",
293             "description": "Reloads the current page in a browsing context.",
294             "parameters": [
295                 { "name": "handle", "$ref": "BrowsingContextHandle", "description": "The handle for the browsing context that should be reloaded." }
296             ],
297             "async": true
298         },
299         {
300             "name": "inspectBrowsingContext",
301             "description": "Inspect the specified browsing context using Web Inspector.",
302             "platform": "macOS",
303             "parameters": [
304                 { "name": "handle", "$ref": "BrowsingContextHandle", "description": "The handle for the browsing context that should be inspected." },
305                 { "name": "enableAutoCapturing", "type": "boolean", "optional": true, "description": "If this option is present and set to true, the Web Inspector will automatically start a timeline recording of the specified browsing context once it is attached. Note that this disables the debugger for the duration of the recording." }
306             ],
307             "async": true
308         },
309         {
310             "name": "evaluateJavaScriptFunction",
311             "description": "Evaluates a script function in a browsing context and calls it with the supplied arguments.",
312             "parameters": [
313                 { "name": "browsingContextHandle", "$ref": "BrowsingContextHandle", "description": "The handle for the browsing context the script should be evaluated." },
314                 { "name": "frameHandle", "$ref": "FrameHandle", "optional": true, "description": "The handle for the frame the script should be evaluated. The main frame is used if this parameter empty string or excluded." },
315                 { "name": "function", "type": "string", "description": "The script to evaluate in the browsing context. It must be a function result." },
316                 { "name": "arguments", "type": "array", "items": { "type": "string" }, "description": "The arguments to pass to the function when called. They will be parsed as JSON before calling the function." },
317                 { "name": "expectsImplicitCallbackArgument", "type": "boolean", "optional": true, "description": "The function expects a callback function as the last argument. It is expected to call this callback with a result." },
318                 { "name": "callbackTimeout", "type": "integer", "optional": true, "description": "The timeout in milliseconds that the implicit callback is expected to be called in, otherwise a <code>JavaScriptTimeout</code> error is returned." }
319             ],
320             "returns": [
321                 { "name": "result", "type": "string", "description": "The result returned by the called function. It is JSON encoded after the function returns or calls the callback." }
322             ],
323             "async": true
324         },
325         {
326             "name": "performMouseInteraction",
327             "description": "Simulates interaction with a mouse cursor.",
328             "parameters": [
329                 { "name": "handle", "$ref": "BrowsingContextHandle", "description": "The browsing context to be interacted with." },
330                 { "name": "position", "$ref": "Point", "description": "The requested position for the mouse cursor, specified in viewport coordinates." },
331                 { "name": "button", "$ref": "MouseButton", "description": "The button to use to perform the interaction. This parameter only has an effect for the <code>Down</code>, <code>Up</code>, <code>Click</code>, and <code>DoubleClick</code> mouse interactions." },
332                 { "name": "interaction", "$ref": "MouseInteraction", "description": "The type of interaction to be performed with the mouse cursor." },
333                 { "name": "modifiers", "type": "array", "items": { "$ref": "KeyModifier" }, "description": "Key modifiers to be active during the mouse interaction." }
334             ],
335             "returns": [
336                 { "name": "position", "$ref": "Point", "description": "The updated position of the mouse cursor, specified in viewport coordinates." }
337             ]
338         },
339         {
340             "name": "performKeyboardInteractions",
341             "description": "Simulates delivering the results of pressing one or more keyboard keys together or successively.",
342             "parameters": [
343                 { "name": "handle", "$ref": "BrowsingContextHandle", "description": "The handle for the browsing context which should receive key." },
344                 { "name": "interactions", "type": "array", "items": { "$ref": "KeyboardInteraction" }, "description": "An ordered list of key sequences to be delivered using native key events." }
345             ],
346             "async": true
347         },
348         {
349             "name": "takeScreenshot",
350             "description": "Take a screenshot of the current page in a browsing context.",
351             "parameters": [
352                 { "name": "handle", "$ref": "BrowsingContextHandle", "description": "The handle for the browsing context to take a screenshot of." }
353             ],
354             "returns": [
355                 { "name": "data", "type": "string", "description": "Base64-encoded image data (PNG)." }
356             ],
357             "async": true
358         },
359         {
360             "name": "resolveChildFrameHandle",
361             "description": "Determines the <code>FrameHandle</code> based on the ordinal, name or node handle of a child frame.",
362             "parameters": [
363                 { "name": "browsingContextHandle", "$ref": "BrowsingContextHandle", "description": "The handle for the browsing context in which to search for the frame." },
364                 { "name": "frameHandle", "$ref": "FrameHandle", "optional": true, "description": "The handle for the frame in which to search for the frame. The main frame is used if this parameter empty string or excluded." },
365                 { "name": "ordinal", "type": "integer", "optional": true, "description": "The ordinal of the child frame to resolve as a <code>FrameHandle</code>. This is analogous to 'window.frames[ordinal]' in JavaScript." },
366                 { "name": "name", "type": "string", "optional": true, "description": "The name of the child frame to resolve as a <code>FrameHandle</code>. This is analogous to 'window.frames[name]' in JavaScript." },
367                 { "name": "nodeHandle", "$ref": "NodeHandle", "optional": true, "description": "The handle of the child frame owner element to resolve as a <code>FrameHandle</code>." }
368             ],
369             "returns": [
370                 { "name": "result", "$ref": "FrameHandle", "description": "The <code>FrameHandle</code> for the requested frame." }
371             ],
372             "async": true
373         },
374         {
375             "name": "resolveParentFrameHandle",
376             "description": "Determines the <code>FrameHandle</code> for the parent frame of the supplied <code>FrameHandle</code>.",
377             "parameters": [
378                 { "name": "browsingContextHandle", "$ref": "BrowsingContextHandle", "description": "The handle for the browsing context the frame is located." },
379                 { "name": "frameHandle", "$ref": "FrameHandle", "description": "The handle for the frame that should resolve its parent frame." }
380             ],
381             "returns": [
382                 { "name": "result", "$ref": "FrameHandle", "description": "The <code>FrameHandle</code> for the requested frame." }
383             ],
384             "async": true
385         },
386         {
387             "name": "computeElementLayout",
388             "description": "Computes the layout for an element.",
389             "parameters": [
390                 { "name": "browsingContextHandle", "$ref": "BrowsingContextHandle", "description": "The handle for the browsing context the frame is located." },
391                 { "name": "frameHandle", "$ref": "FrameHandle", "description": "The handle for the frame that contains the element." },
392                 { "name": "nodeHandle", "$ref": "NodeHandle", "description": "The handle of the element to use." },
393                 { "name": "scrollIntoViewIfNeeded", "optional": true, "type": "boolean", "description": "If the element should be scrolled into view before computing its layout." },
394                 { "name": "useViewportCoordinates", "optional": true, "type": "boolean", "description": "If the result coordinates should be represented as viewport coordinates or not. Defaults to false, which means coordinates should be represented as page coordinates." }
395             ],
396             "returns": [
397                 { "name": "rect", "$ref": "Rect", "description": "The layout rect for the requested element. Specified in page or viewport coordinates based on the useViewportCoordinates parameter." }
398             ],
399             "async": true
400         },
401         {
402             "name": "isShowingJavaScriptDialog",
403             "description": "Checks if a browsing context is showing a JavaScript alert, confirm, or prompt dialog.",
404             "parameters": [
405                 { "name": "browsingContextHandle", "$ref": "BrowsingContextHandle", "description": "The handle for the browsing context." }
406             ],
407             "returns": [
408                 { "name": "result", "type": "boolean", "description": "If the browsing context is showing a JavaScript dialog or not." }
409             ]
410         },
411         {
412             "name": "dismissCurrentJavaScriptDialog",
413             "description": "Dismisses a JavaScript alert, confirm, or prompt dialog currently showing in a browsing context. Equivalent to clicking the 'Cancel' button.",
414             "parameters": [
415                 { "name": "browsingContextHandle", "$ref": "BrowsingContextHandle", "description": "The handle for the browsing context." }
416             ]
417         },
418         {
419             "name": "acceptCurrentJavaScriptDialog",
420             "description": "Accepts a JavaScript alert, confirm, or prompt dialog currently showing in a browsing context. Equivalent to clicking the 'OK' button.",
421             "parameters": [
422                 { "name": "browsingContextHandle", "$ref": "BrowsingContextHandle", "description": "The handle for the browsing context." }
423             ]
424         },
425         {
426             "name": "messageOfCurrentJavaScriptDialog",
427             "description": "Returns the text displayed in a JavaScript alert, confirm, or prompt dialog currently showing in a browsing context.",
428             "parameters": [
429                 { "name": "browsingContextHandle", "$ref": "BrowsingContextHandle", "description": "The handle for the browsing context." }
430             ],
431             "returns": [
432                 { "name": "message", "type": "string", "description": "Text being displayed in the current JavaScript dialog." }
433             ]
434         },
435         {
436             "name": "setUserInputForCurrentJavaScriptPrompt",
437             "description": "Sets the user entered value in a JavaScript prompt dialog currently showing in a browsing context.",
438             "parameters": [
439                 { "name": "browsingContextHandle", "$ref": "BrowsingContextHandle", "description": "The handle for the browsing context." },
440                 { "name": "userInput", "type": "string", "description": "The text to enter in the prompt." }
441             ]
442         },
443         {
444             "name": "getAllCookies",
445             "description": "Returns all cookies visible to the specified browsing context.",
446             "parameters": [
447                 { "name": "browsingContextHandle", "$ref": "BrowsingContextHandle", "description": "The handle for the browsing context." }
448             ],
449             "returns": [
450                 { "name": "cookies", "type": "array", "items": { "$ref": "Cookie" }, "description": "Array of cookie objects." }
451             ],
452             "async": true
453         },
454         {
455             "name": "deleteSingleCookie",
456             "description": "Deletes a cookie with the given name if visible to the specified browsing context.",
457             "parameters": [
458                 { "name": "browsingContextHandle", "$ref": "BrowsingContextHandle", "description": "The handle for the browsing context." },
459                 { "name": "cookieName", "type": "string", "description": "Name of the cookie to remove." }
460             ],
461             "async": true
462         },
463         {
464             "name": "addSingleCookie",
465             "description": "Add a cookie to cookie storage for the specified browsing context.",
466             "parameters": [
467                 { "name": "browsingContextHandle", "$ref": "BrowsingContextHandle", "description": "The handle for the browsing context." },
468                 { "name": "cookie", "$ref": "Cookie", "description": "The cookie that should be added to storage." }
469             ],
470             "async": true
471         },
472         {
473             "name": "deleteAllCookies",
474             "description": "Delete all cookies that are visible to the specified browsing context.",
475             "parameters": [
476                 { "name": "browsingContextHandle", "$ref": "BrowsingContextHandle", "description": "The handle for the browsing context." }
477             ]
478         }
479     ]
480 }