[Technical review] BiDi - Add pages for input module commands and event #43919
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,64 @@ | ||
| --- | ||
| title: input.fileDialogOpened event | ||
| short-title: fileDialogOpened | ||
| slug: Web/WebDriver/Reference/BiDi/Modules/input/fileDialogOpened | ||
| page-type: webdriver-event | ||
| browser-compat: webdriver.bidi.input.fileDialogOpened_event | ||
| sidebar: webdriver | ||
| --- | ||
|
|
||
| The `input.fileDialogOpened` [event](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules#events) of the [`input`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/input) module fires when a file picker dialog opens in a context, for example when [`click()`](/en-US/docs/Web/API/HTMLElement/click) or [`showPicker()`](/en-US/docs/Web/API/HTMLInputElement/showPicker) is called on an [`<input type="file">`](/en-US/docs/Web/HTML/Reference/Elements/input/file) element. | ||
|
|
||
| ## Event data | ||
|
|
||
| The `params` field in the event notification is an object with the following fields: | ||
|
|
||
| - `context` | ||
| - : A string that contains the ID ([UUID](/en-US/docs/Glossary/UUID)) of the context in which the file picker dialog was triggered. | ||
| Context IDs are returned by commands such as [`browsingContext.getTree`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/getTree). | ||
|
Contributor
There was a problem hiding this comment. This reference is also not used elsewhere. |
||
| - `element` {{optional_inline}} | ||
| - : An object containing the ID that uniquely identifies the [`<input type="file">`](/en-US/docs/Web/HTML/Reference/Elements/input/file) DOM element that triggered the file picker dialog. | ||
| This field is included when the file picker dialog is opened by a file `<input>` element. | ||
| - `multiple` | ||
| - : A boolean that indicates whether the file picker dialog allows multiple file paths. | ||
| - `true`: The file picker dialog accepts multiple files (the associated `<input>` element has the [`multiple`](/en-US/docs/Web/HTML/Reference/Elements/input/file#multiple) attribute). | ||
| - `false`: The file picker dialog accepts only a single file path. | ||
| - `userContext` {{optional_inline}} | ||
| - : A string that contains the ID of the [user context](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browser#user_contexts) in which the file picker dialog was triggered. | ||
|
|
||
| ## Examples | ||
|
|
||
| ### Receiving an event when a file picker dialog opens | ||
|
|
||
| Consider a scenario where a page has an [`<input type="file">`](/en-US/docs/Web/HTML/Reference/Elements/input/file) element that accepts a single file and your script calls [`click()`](/en-US/docs/Web/API/HTMLElement/click) on it. With a [WebDriver BiDi connection](/en-US/docs/Web/WebDriver/How_to/Create_BiDi_connection) and a [subscription](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/session/subscribe) to `input.fileDialogOpened` active, the browser sends a notification when the file picker dialog opens: | ||
|
|
||
| ```json | ||
| { | ||
| "type": "event", | ||
| "method": "input.fileDialogOpened", | ||
| "params": { | ||
| "context": "5f07e3ca-ecac-465e-b9ef-49000c196ecf", | ||
| "element": { | ||
| "sharedId": "3be28343-afd3-4dea-a2b6-a863fbbb80e1" | ||
| }, | ||
| "multiple": false | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| You can then call [`input.setFiles`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/input/setFiles) with the `element.sharedId` from the notification to simulate file upload. | ||
|
|
||
| ## Specifications | ||
|
|
||
| {{Specifications}} | ||
|
|
||
| ## Browser compatibility | ||
|
|
||
| {{Compat}} | ||
|
|
||
| ## See also | ||
|
|
||
| - [`session.subscribe`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/session/subscribe) command | ||
| - [`input.setFiles`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/input/setFiles) command | ||
| - [`input.performActions`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/input/performActions) command | ||
| - [`input.releaseActions`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/input/releaseActions) command | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,255 @@ | ||
| --- | ||
| title: "`input.performActions` command" | ||
| short-title: performActions | ||
| slug: Web/WebDriver/Reference/BiDi/Modules/input/performActions | ||
| page-type: webdriver-command | ||
| browser-compat: webdriver.bidi.input.performActions | ||
| sidebar: webdriver | ||
| --- | ||
|
|
||
| The `input.performActions` [command](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules#commands) of the [`input`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/input) module simulates user input actions in a given context to interact with elements on the page. After performing actions, call [`input.releaseActions`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/input/releaseActions) to release any inputs left in an intermediate state. | ||
|
|
||
| ## Syntax | ||
|
|
||
| ```json-nolint | ||
| { | ||
| "method": "input.performActions", | ||
| "params": { | ||
| "context": "<contextId>", | ||
| "actions": [ | ||
| { | ||
| "type": "<inputSourceType>", | ||
| "id": "<sourceId>", | ||
| "actions": [ | ||
| { | ||
| "type": "<actionType>", | ||
| ... | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### Parameters | ||
|
|
||
| The `params` field contains: | ||
|
|
||
| - `context` | ||
| - : A string that contains the ID ([UUID](/en-US/docs/Glossary/UUID)) of the context in which to perform the actions. Context IDs are returned by commands such as [`browsingContext.getTree`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/getTree). | ||
|
Contributor
There was a problem hiding this comment. Similar comment to the UUID as mentioned for the event. Are you planning to continue using it? If yes, then we probably should update all pages simultaneously? |
||
| - `actions` | ||
| - : An array of objects, each representing an input source (`"key"`, `"pointer"`, or `"wheel"`) and the actions to perform for that source. | ||
| All input sources are processed in parallel. | ||
| This allows combining input sources, for example, holding <kbd>Shift</kbd> while clicking. | ||
|
|
||
| Each `actions` object has the following fields: | ||
| - `id` | ||
| - : A string that uniquely identifies this input source within the action sequence, for example, `"mouse1"` or `"keyboard1"`. | ||
| - `type` | ||
| - : A string that identifies the type of input source. Accepted values are `"none"`, `"key"`, `"pointer"`, and `"wheel"`. | ||
| - `actions` | ||
| - : An array of objects, each representing an action for the input source specified in the [`type`](#type) field. | ||
|
|
||
| Each object has a `type` field that specifies the type of operation and additional fields that depend on the value of this `type`. The `type` field accepts the following values: | ||
| - `"pause"`: Waits for the given duration before the next step. | ||
| - `"keyDown"`: Simulates pressing a key. | ||
| - `"keyUp"`: Simulates releasing a key. | ||
| - `"pointerDown"`: Simulates pressing a pointer button. | ||
| - `"pointerUp"`: Simulates releasing a pointer button. | ||
| - `"pointerMove"`: Simulates moving the pointer. | ||
| - `"scroll"`: Simulates a mouse wheel scroll. | ||
|
|
||
| The following table shows, for each input source `type` value, the `type` values valid inside the nested `actions` array: | ||
|
|
||
| | Input source `type` values | Accepted operation `type` values | | ||
| | -------------------------- | ---------------------------------------------------------- | | ||
| | `"none"` | `"pause"` | | ||
| | `"key"` | `"pause"`, `"keyDown"`, `"keyUp"` | | ||
| | `"pointer"` | `"pause"`, `"pointerDown"`, `"pointerUp"`, `"pointerMove"` | | ||
| | `"wheel"` | `"pause"`, `"scroll"` | | ||
|
|
||
| The following table shows the additional fields in the `actions` object for each operation type: | ||
|
|
||
| | Operation `type` values | Fields available with this `type` value | | ||
| | ----------------------- | -------------------------------------------------------------------------------------------------------------------- | | ||
| | `"pause"` | [`duration`](#duration) | | ||
| | `"keyDown"`, `"keyUp"` | [`value`](#value) | | ||
| | `"pointerDown"` | [`button`](#button), [pointer properties](#common_pointer_properties) | | ||
| | `"pointerUp"` | [`button`](#button) | | ||
| | `"pointerMove"` | [`x`](#x), [`y`](#y), [`duration`](#duration), [`origin`](#origin), [pointer properties](#common_pointer_properties) | | ||
| | `"scroll"` | [`x`](#x), [`y`](#y), [`deltaX`](#deltax), [`deltaY`](#deltay), [`duration`](#duration), [`origin`](#origin) | | ||
|
|
||
| - `parameters` {{optional_inline}} | ||
|
Contributor
There was a problem hiding this comment. Hm, this entry is kinda glued to the bottom of the table and hard to spot as if margin/padding is missing. Could we improve that?
Contributor
Author
There was a problem hiding this comment. As a workaround, I've added a lead-in sentence to add a gap between the table and the definition list. What do you think? |
||
| - : An object with a `pointerType` field that specifies the pointer device type. Accepted values are `"mouse"` (default), `"pen"`, or `"touch"`. This field is valid only when the input source [`type`](#type) is `"pointer"`. | ||
|
|
||
| The following fields are supported depending on the value of the operation `type`: | ||
|
|
||
| - `button` | ||
| - : A non-negative integer that identifies the pointer button (`0` = primary, `1` = middle, `2` = secondary). | ||
| Specify this when the `type` field value is `"pointerDown"` or `"pointerUp"`. | ||
| - `deltaX` | ||
| - : An integer that specifies the horizontal scroll delta in CSS pixels. | ||
| Specify this when the `type` field value is `"scroll"`. | ||
| - `deltaY` | ||
| - : An integer that specifies the vertical scroll delta in CSS pixels. | ||
| Specify this when the `type` field value is `"scroll"`. | ||
| - `duration` {{optional_inline}} | ||
| - : A non-negative integer that specifies the time in milliseconds. | ||
| Specify this when the `type` field value is `"pause"`, `"pointerMove"`, or `"scroll"`. | ||
|
Contributor
There was a problem hiding this comment. We should note that specifying a duration splits the action into sub-steps per tick (~17 ms). For example, a 100 ms duration results in about 6 pointer moves, each covering roughly 1/6 of the total distance. |
||
| - `origin` {{optional_inline}} | ||
| - : A string or an object that specifies the origin for the move or scroll. Accepted string values are `"viewport"` and `"pointer"`. For an object, include the following fields: | ||
|
Contributor
There was a problem hiding this comment. We should ideally explain the difference between the values and what they are used for.
Contributor
Author
There was a problem hiding this comment. Added:
Also moved the sentence "Specify this when..." alongside main |
||
| - `type` | ||
| - : A string set to `"element"`. | ||
| - `element` | ||
| - : An object containing the ID that uniquely identifies the DOM element to use as the origin. The ID is returned by the browser when you locate the element using [`script.evaluate`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/script/evaluate) or [`script.callFunction`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/script/callFunction). | ||
|
dipikabh marked this conversation as resolved.
|
||
|
|
||
| Specify this when the `type` field value is `"pointerMove"` or `"scroll"`. For `"scroll"`, `"viewport"` is the default if this field is omitted. | ||
|
|
||
| - `value` | ||
| - : A string that contains the key value, such as <kbd>a</kbd>, <kbd>Enter</kbd>, or <kbd>Shift</kbd>. | ||
| Specify this when the `type` field value is `"keyDown"` or `"keyUp"`. | ||
| - Common pointer properties | ||
| - : The following optional fields describe the physical characteristics of the pointer device, such as a mouse, stylus, or touchscreen. Specify these when the `type` field value is `"pointerDown"` or `"pointerMove"`. | ||
| - `width` {{optional_inline}} | ||
| - : A non-negative integer that specifies the width, in CSS pixels, of the pointer contact area. See {{domxref("PointerEvent.width")}}. | ||
| - `height` {{optional_inline}} | ||
| - : A non-negative integer that specifies the height, in CSS pixels, of the pointer contact area. See {{domxref("PointerEvent.height")}}. | ||
| - `pressure` {{optional_inline}} | ||
| - : A float that specifies the normalized pressure of the pointer in the range `0.0`–`1.0`. See {{domxref("PointerEvent.pressure")}}. | ||
| - `tangentialPressure` {{optional_inline}} | ||
| - : A float that specifies the normalized tangential pressure in the range `-1.0`–`1.0`. See {{domxref("PointerEvent.tangentialPressure")}}. | ||
| - `twist` {{optional_inline}} | ||
| - : An integer that specifies the clockwise rotation, in degrees, of the pointer in the range `0`–`359`. See {{domxref("PointerEvent.twist")}}. | ||
| - `altitudeAngle` {{optional_inline}} | ||
| - : A float that specifies the altitude angle, in radians, of the pointer in the range `0.0`–`1.5707963267948966`. See {{domxref("PointerEvent.altitudeAngle")}}. | ||
|
dipikabh marked this conversation as resolved.
|
||
| - `azimuthAngle` {{optional_inline}} | ||
| - : A float that specifies the azimuth angle, in radians, of the pointer in the range `0.0`–`6.283185307179586`. See {{domxref("PointerEvent.azimuthAngle")}}. | ||
| - `x` | ||
| - : A number (for `"pointerMove"`) or an integer (for `"scroll"`) that specifies the x-coordinate. | ||
| Specify this when the `type` field value is `"pointerMove"` or `"scroll"`. | ||
| - `y` | ||
| - : A number (for `"pointerMove"`) or an integer (for `"scroll"`) that specifies the y-coordinate. | ||
| Specify this when the `type` field value is `"pointerMove"` or `"scroll"`. | ||
|
|
||
| ### Return value | ||
|
|
||
| The `result` field in the response is an empty object (`{}`). | ||
|
|
||
| ### Errors | ||
|
|
||
| - [`invalid argument`](/en-US/docs/Web/WebDriver/Reference/Errors/InvalidArgument) | ||
| - : The action sequence is malformed; for example, if a required field is missing or a field value is of the wrong type. | ||
|
|
||
| ## Examples | ||
|
|
||
| ### Clicking an element | ||
|
|
||
| Consider a scenario where you want to simulate a mouse click on an element. | ||
| With a [WebDriver BiDi connection](/en-US/docs/Web/WebDriver/How_to/Create_BiDi_connection) and an active session, get the context ID using [`browsingContext.getTree`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/getTree) and the element identifier using [`script.evaluate`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/script/evaluate). | ||
|
dipikabh marked this conversation as resolved.
|
||
| Send the following message that uses three sequential steps: moving (`pointerMove`) the pointer to the center of the element (`x: 0, y: 0` relative to the element), pressing (`pointerDown`) the primary mouse button (`0`), and then releasing (`pointerUp`) it. | ||
|
|
||
| ```json | ||
| { | ||
| "id": 1, | ||
| "method": "input.performActions", | ||
| "params": { | ||
| "context": "5f07e3ca-ecac-465e-b9ef-49000c196ecf", | ||
| "actions": [ | ||
| { | ||
| "type": "pointer", | ||
| "id": "mouse1", | ||
| "parameters": { | ||
| "pointerType": "mouse" | ||
| }, | ||
| "actions": [ | ||
| { | ||
| "type": "pointerMove", | ||
| "x": 0, | ||
| "y": 0, | ||
| "origin": { | ||
| "type": "element", | ||
| "element": { | ||
| "sharedId": "3be28343-afd3-4dea-a2b6-a863fbbb80e1" | ||
| } | ||
| } | ||
| }, | ||
| { | ||
| "type": "pointerDown", | ||
| "button": 0 | ||
| }, | ||
| { | ||
| "type": "pointerUp", | ||
| "button": 0 | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| The browser responds as follows: | ||
|
|
||
| ```json | ||
| { | ||
| "id": 1, | ||
| "type": "success", | ||
| "result": {} | ||
| } | ||
| ``` | ||
|
|
||
| ### Scrolling the page | ||
|
|
||
| Consider a scenario where you want to simulate scrolling a page down. | ||
| With a [WebDriver BiDi connection](/en-US/docs/Web/WebDriver/How_to/Create_BiDi_connection) and an active session, get the context ID using [`browsingContext.getTree`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/getTree). | ||
| Send the following message that scrolls from the top-left of the viewport (`x: 0, y: 0`) by `300` CSS pixels downward (`deltaY: 300`) with no horizontal scrolling (`deltaX: 0`). | ||
|
|
||
| ```json | ||
| { | ||
| "id": 2, | ||
| "method": "input.performActions", | ||
| "params": { | ||
| "context": "5f07e3ca-ecac-465e-b9ef-49000c196ecf", | ||
| "actions": [ | ||
| { | ||
| "type": "wheel", | ||
| "id": "wheel1", | ||
| "actions": [ | ||
| { | ||
| "type": "scroll", | ||
| "x": 0, | ||
| "y": 0, | ||
| "deltaX": 0, | ||
| "deltaY": 300 | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| The browser responds as follows: | ||
|
|
||
| ```json | ||
| { | ||
| "id": 2, | ||
| "type": "success", | ||
| "result": {} | ||
| } | ||
| ``` | ||
|
|
||
| ## Specifications | ||
|
|
||
| {{Specifications}} | ||
|
|
||
| ## Browser compatibility | ||
|
|
||
| {{Compat}} | ||
|
|
||
| ## See also | ||
|
|
||
| - [`input.releaseActions`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/input/releaseActions) command | ||
| - [`input.setFiles`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/input/setFiles) command | ||
| - [`input.fileDialogOpened`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/input/fileDialogOpened) event | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We do not use the reference to
UUIDin other places. Should we get started doing so?