[Tech review] BiDi - Add pages for navigation and page load events of browsingContext module #44571
+513
−2
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
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,74 @@ | ||
| --- | ||
| title: "`browsingContext.domContentLoaded` event" | ||
| short-title: domContentLoaded | ||
| slug: Web/WebDriver/Reference/BiDi/Modules/browsingContext/domContentLoaded | ||
| page-type: webdriver-event | ||
| browser-compat: webdriver.bidi.browsingContext.domContentLoaded_event | ||
| sidebar: webdriver | ||
| --- | ||
|
|
||
| The `browsingContext.domContentLoaded` [event](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules#events) of the [`browsingContext`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext) module fires when the HTML document has been parsed during a cross-document navigation in a context. | ||
|
|
||
| ## Description | ||
|
|
||
| In the lifecycle of a successful navigation, this event fires after [`browsingContext.navigationCommitted`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigationCommitted) and before [`browsingContext.load`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/load) events. | ||
|
|
||
| At this point, the HTML has been parsed, equivalent to the {{domxref("Document/DOMContentLoaded_event", "DOMContentLoaded")}} event firing in the context, but subresources such as stylesheets and images may still be loading. | ||
|
|
||
| If you set `wait` to `"interactive"` for the [`browsingContext.navigate`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigate) and [`browsingContext.reload`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/reload) commands, they return as soon as `browsingContext.domContentLoaded` fires. | ||
|
|
||
| ## Event data | ||
|
|
||
| The `params` field in the event notification is a navigation object with the following fields: | ||
|
|
||
| - `context` | ||
| - : A string that contains the ID of the context in which the HTML document is being parsed. | ||
| - `navigation` | ||
| - : A string that contains the [UUID](/en-US/docs/Glossary/UUID) that uniquely identifies this navigation. | ||
| This ID matches the `navigation` value in the response of the [`browsingContext.navigate`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigate) and [`browsingContext.reload`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/reload) commands. | ||
| - `timestamp` | ||
| - : A non-negative integer that represents the time in UTC when the event was fired, as milliseconds elapsed since the [epoch](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#the_epoch_timestamps_and_invalid_date). | ||
|
Contributor
There was a problem hiding this comment. Isn't it confusing to mention UTC here? This is just a number of ms since epoch, timezones should not matter. |
||
| - `url` | ||
| - : A string that contains the URL being loaded. | ||
| - `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 HTML document is being parsed. | ||
|
Comment on lines
+33
to
+34
Contributor
Author
There was a problem hiding this comment. I was thinking to leave this field out, but I noticed in the implementation tracker that Firefox support is coming in 154. So I've included it, though examples of all events in this PR are currently missing this field. I would have asked for clarification on when this field is included vs. omitted in the payload - but from the comment in the spreadsheet, it seems that this field will eventually become required. But let me know, if in the meantime, any more details need to be added here
Contributor
There was a problem hiding this comment. This is similar to #44121 (review) , it might be better to leave those out until they are mandatory in the spec. We implemented it in Firefox 154, but AFAIK Chrome doesn't support it yet. |
||
|
|
||
| ## Examples | ||
|
|
||
| ### Receiving an event when a document is parsed | ||
|
|
||
| Assume you have a [WebDriver BiDi connection](/en-US/docs/Web/WebDriver/How_to/Create_BiDi_connection) and an [active session](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/session/new) with a [subscription](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/session/subscribe) to `browsingContext.domContentLoaded`. | ||
|
|
||
| Suppose you use [`browsingContext.navigate`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigate) to load `https://example.com`, passing the context ID you obtain from [`browsingContext.getTree`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/getTree). | ||
|
|
||
| The browser first fires [`browsingContext.navigationStarted`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigationStarted) and [`browsingContext.navigationCommitted`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigationCommitted) events (those notifications are not received since the subscription in this example is only to `browsingContext.domContentLoaded`). | ||
|
|
||
| Once the HTML has been parsed, the browser sends the following notification, where the `context` value matches the context ID you passed to `browsingContext.navigate`: | ||
|
|
||
| ```json | ||
| { | ||
| "type": "event", | ||
| "method": "browsingContext.domContentLoaded", | ||
| "params": { | ||
| "context": "5e5e96e8-5247-4f22-9b35-a4a2d841cbaa", | ||
| "navigation": "a1b2c3d4-5678-90ab-cdef-1234567890ab", | ||
| "timestamp": 1782342489906, | ||
| "url": "https://example.com" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Specifications | ||
|
|
||
| {{Specifications}} | ||
|
|
||
| ## Browser compatibility | ||
|
|
||
| {{Compat}} | ||
|
|
||
| ## See also | ||
|
|
||
| - [`browsingContext.navigationStarted`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigationStarted) event | ||
| - [`browsingContext.navigationCommitted`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigationCommitted) event | ||
| - [`browsingContext.load`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/load) event | ||
| - [`browsingContext.navigationFailed`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigationFailed) event | ||
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,60 @@ | ||
| --- | ||
| title: "`browsingContext.fragmentNavigated` event" | ||
| short-title: fragmentNavigated | ||
| slug: Web/WebDriver/Reference/BiDi/Modules/browsingContext/fragmentNavigated | ||
| page-type: webdriver-event | ||
| browser-compat: webdriver.bidi.browsingContext.fragmentNavigated_event | ||
| sidebar: webdriver | ||
| --- | ||
|
|
||
| The `browsingContext.fragmentNavigated` [event](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules#events) of the [`browsingContext`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext) module fires when a same-document navigation to a [URL fragment](/en-US/docs/Web/URI/Reference/Fragment) occurs in a context. | ||
|
|
||
| ## Event data | ||
|
|
||
| The `params` field in the event notification is a navigation object with the following fields: | ||
|
|
||
| - `context` | ||
| - : A string that contains the ID of the context in which the fragment navigation is occurring. | ||
| - `navigation` | ||
| - : A string that contains the [UUID](/en-US/docs/Glossary/UUID) that uniquely identifies this navigation. | ||
| This ID matches the `navigation` value in the response of the [`browsingContext.navigate`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigate) and [`browsingContext.reload`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/reload) commands. | ||
| - `timestamp` | ||
| - : A non-negative integer that represents the time in UTC when the event was fired, as milliseconds elapsed since the [epoch](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#the_epoch_timestamps_and_invalid_date). | ||
| - `url` | ||
| - : A string that contains the updated URL, including the fragment. | ||
| - `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 fragment navigation is occurring. | ||
|
|
||
| ## Examples | ||
|
|
||
| ### Receiving a fragment navigation event | ||
|
|
||
| Assume you have a [WebDriver BiDi connection](/en-US/docs/Web/WebDriver/How_to/Create_BiDi_connection) and an [active session](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/session/new) with a [subscription](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/session/subscribe) to `browsingContext.fragmentNavigated`. | ||
|
|
||
| Suppose a navigation to a section on `https://example.com/page` occurs. The browser sends the following notification: | ||
|
|
||
| ```json | ||
| { | ||
| "type": "event", | ||
| "method": "browsingContext.fragmentNavigated", | ||
| "params": { | ||
| "context": "5e5e96e8-5247-4f22-9b35-a4a2d841cbaa", | ||
| "navigation": "a1b2c3d4-5678-90ab-cdef-1234567890ab", | ||
| "timestamp": 1712345678901, | ||
| "url": "https://example.com/page#section-2" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Specifications | ||
|
|
||
| {{Specifications}} | ||
|
|
||
| ## Browser compatibility | ||
|
|
||
| {{Compat}} | ||
|
|
||
| ## See also | ||
|
|
||
| - [`browsingContext.navigationStarted`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigationStarted) event | ||
| - [`browsingContext.historyUpdated`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/historyUpdated) event |
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,63 @@ | ||
| --- | ||
| title: "`browsingContext.historyUpdated` event" | ||
| short-title: historyUpdated | ||
| slug: Web/WebDriver/Reference/BiDi/Modules/browsingContext/historyUpdated | ||
| page-type: webdriver-event | ||
| browser-compat: webdriver.bidi.browsingContext.historyUpdated_event | ||
| sidebar: webdriver | ||
| --- | ||
|
|
||
| The `browsingContext.historyUpdated` [event](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules#events) of the [`browsingContext`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext) module fires when the active URL in a context is updated programmatically without a full navigation. | ||
|
|
||
| ## Description | ||
|
|
||
| This event fires when {{domxref("History.pushState", "history.pushState()")}} or {{domxref("History.replaceState", "history.replaceState()")}} is called to update the URL, or when {{domxref("Document.open", "document.open()")}} is called to replace the document. | ||
| These calls change the active URL in the context. | ||
|
|
||
| `browsingContext.historyUpdated` fires specifically when the URL is changed programmatically, unlike [`browsingContext.fragmentNavigated`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/fragmentNavigated), which fires for same-document navigations to a URL fragment. | ||
|
|
||
| ## Event data | ||
|
|
||
| The `params` field in the event notification is a history update object with the following fields: | ||
|
|
||
| - `context` | ||
| - : A string that contains the ID of the context in which the history update is occurring. | ||
| - `timestamp` | ||
| - : A non-negative integer that represents the time in UTC when the event was fired, as milliseconds elapsed since the [epoch](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#the_epoch_timestamps_and_invalid_date). | ||
| - `url` | ||
| - : A string that contains the updated URL. | ||
| - `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 history update is occurring. | ||
|
|
||
| ## Examples | ||
|
|
||
| ### Receiving an event when `history.pushState()` is called | ||
|
|
||
| Assume you have a [WebDriver BiDi connection](/en-US/docs/Web/WebDriver/How_to/Create_BiDi_connection) and an [active session](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/session/new) with a [subscription](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/session/subscribe) to `browsingContext.historyUpdated`. | ||
|
|
||
| Suppose {{domxref("History.pushState", "history.pushState()")}} is called to update the URL to `https://example.com/new-path`. The browser sends the following notification: | ||
|
|
||
| ```json | ||
| { | ||
| "type": "event", | ||
| "method": "browsingContext.historyUpdated", | ||
| "params": { | ||
| "context": "5e5e96e8-5247-4f22-9b35-a4a2d841cbaa", | ||
| "timestamp": 1781888825943, | ||
| "url": "https://example.com/new-path" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Specifications | ||
|
|
||
| {{Specifications}} | ||
|
|
||
| ## Browser compatibility | ||
|
|
||
| {{Compat}} | ||
|
|
||
| ## See also | ||
|
|
||
| - [`browsingContext.navigationStarted`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigationStarted) event | ||
| - [`browsingContext.fragmentNavigated`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/fragmentNavigated) event |
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,74 @@ | ||
| --- | ||
| title: "`browsingContext.load` event" | ||
| short-title: load | ||
| slug: Web/WebDriver/Reference/BiDi/Modules/browsingContext/load | ||
| page-type: webdriver-event | ||
| browser-compat: webdriver.bidi.browsingContext.load_event | ||
| sidebar: webdriver | ||
| --- | ||
|
|
||
| The `browsingContext.load` [event](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules#events) of the [`browsingContext`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext) module fires when a cross-document navigation has fully completed in a context. | ||
|
|
||
| ## Description | ||
|
|
||
| In the lifecycle of a successful navigation, this event fires after [`browsingContext.domContentLoaded`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/domContentLoaded) and is the final event in the sequence. | ||
|
|
||
| At this point, the document and all its subresources have finished loading, equivalent to the {{domxref("Window/load_event", "load")}} event firing. | ||
|
|
||
| If you set `wait` to `"complete"` for the [`browsingContext.navigate`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigate) and [`browsingContext.reload`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/reload) commands, they return as soon as `browsingContext.load` fires. | ||
|
|
||
| ## Event data | ||
|
|
||
| The `params` field in the event notification is a navigation object with the following fields: | ||
|
|
||
| - `context` | ||
| - : A string that contains the ID of the context in which the document has fully loaded. | ||
| - `navigation` | ||
| - : A string that contains the [UUID](/en-US/docs/Glossary/UUID) that uniquely identifies this navigation. | ||
| This ID matches the `navigation` value in the response of the [`browsingContext.navigate`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigate) and [`browsingContext.reload`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/reload) commands. | ||
| - `timestamp` | ||
| - : A non-negative integer that represents the time in UTC when the event was fired, as milliseconds elapsed since the [epoch](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#the_epoch_timestamps_and_invalid_date). | ||
| - `url` | ||
| - : A string that contains the URL of the document that has fully loaded. | ||
| - `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 document has fully loaded. | ||
|
|
||
| ## Examples | ||
|
|
||
| ### Receiving an event when a document has fully loaded | ||
|
|
||
| Assume you have a [WebDriver BiDi connection](/en-US/docs/Web/WebDriver/How_to/Create_BiDi_connection) and an [active session](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/session/new) with a [subscription](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/session/subscribe) to `browsingContext.load`. | ||
|
|
||
| Suppose you use [`browsingContext.navigate`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigate) to load `https://example.com`, passing the context ID you obtain from [`browsingContext.getTree`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/getTree). | ||
|
|
||
| The browser first fires [`browsingContext.navigationStarted`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigationStarted), [`browsingContext.navigationCommitted`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigationCommitted), and [`browsingContext.domContentLoaded`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/domContentLoaded) events (those notifications are not received since the subscription in this example is only to `browsingContext.load`). | ||
|
|
||
| Once the document and all its subresources have finished loading, the browser sends the following notification, where the `context` value matches the context ID you passed to `browsingContext.navigate`: | ||
|
|
||
| ```json | ||
| { | ||
| "type": "event", | ||
| "method": "browsingContext.load", | ||
| "params": { | ||
| "context": "5e5e96e8-5247-4f22-9b35-a4a2d841cbaa", | ||
| "navigation": "a1b2c3d4-5678-90ab-cdef-1234567890ab", | ||
| "timestamp": 1782343062410, | ||
| "url": "https://example.com" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Specifications | ||
|
|
||
| {{Specifications}} | ||
|
|
||
| ## Browser compatibility | ||
|
|
||
| {{Compat}} | ||
|
|
||
| ## See also | ||
|
|
||
| - [`browsingContext.navigationStarted`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigationStarted) event | ||
| - [`browsingContext.navigationCommitted`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigationCommitted) event | ||
| - [`browsingContext.domContentLoaded`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/domContentLoaded) event | ||
| - [`browsingContext.navigationFailed`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigationFailed) event |
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.
As a general note, navigation (and navigation events) can be triggered by other means than calling
navigateorreload. Maybe hint at that by saying "if the navigation was started through a command". Otherwise it might give the impression that the navigation id is not going to be set for navigations which were not initiated by the command?Could also be nice to mention that the navigation id is shared by all the events related to this navigation: that is all browsingContext navigation events, as well as the network events.