diff --git a/files/en-us/web/webdriver/reference/bidi/modules/browsingcontext/contextcreated/index.md b/files/en-us/web/webdriver/reference/bidi/modules/browsingcontext/contextcreated/index.md index e2f491f328945ea..1ef98ff2c753b86 100644 --- a/files/en-us/web/webdriver/reference/bidi/modules/browsingcontext/contextcreated/index.md +++ b/files/en-us/web/webdriver/reference/bidi/modules/browsingcontext/contextcreated/index.md @@ -11,7 +11,7 @@ The `browsingContext.contextCreated` [event](/en-US/docs/Web/WebDriver/Reference ## Event data -The `params` field in the event notification is a [context object](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/getTree#contexts) with the following properties: +The `params` field in the event notification is a [context object](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/getTree#contexts) with the following fields: - `children` - : An array of [context objects](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/getTree#contexts) that represents child contexts. diff --git a/files/en-us/web/webdriver/reference/bidi/modules/browsingcontext/contextdestroyed/index.md b/files/en-us/web/webdriver/reference/bidi/modules/browsingcontext/contextdestroyed/index.md index 29c769c896974f8..057603531681f65 100644 --- a/files/en-us/web/webdriver/reference/bidi/modules/browsingcontext/contextdestroyed/index.md +++ b/files/en-us/web/webdriver/reference/bidi/modules/browsingcontext/contextdestroyed/index.md @@ -11,7 +11,7 @@ The `browsingContext.contextDestroyed` [event](/en-US/docs/Web/WebDriver/Referen ## Event data -The `params` field in the event notification is a [context object](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/getTree#contexts) with the following properties, describing the discarded context and its subtree: +The `params` field in the event notification is a [context object](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/getTree#contexts) with the following fields, describing the discarded context and its subtree: - `children` - : An array of [context objects](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/getTree#contexts) that represents child contexts. diff --git a/files/en-us/web/webdriver/reference/bidi/modules/browsingcontext/domcontentloaded/index.md b/files/en-us/web/webdriver/reference/bidi/modules/browsingcontext/domcontentloaded/index.md new file mode 100644 index 000000000000000..fffeb793f204849 --- /dev/null +++ b/files/en-us/web/webdriver/reference/bidi/modules/browsingcontext/domcontentloaded/index.md @@ -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). +- `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. + +## 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 diff --git a/files/en-us/web/webdriver/reference/bidi/modules/browsingcontext/fragmentnavigated/index.md b/files/en-us/web/webdriver/reference/bidi/modules/browsingcontext/fragmentnavigated/index.md new file mode 100644 index 000000000000000..6c838cf951b35be --- /dev/null +++ b/files/en-us/web/webdriver/reference/bidi/modules/browsingcontext/fragmentnavigated/index.md @@ -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 diff --git a/files/en-us/web/webdriver/reference/bidi/modules/browsingcontext/historyupdated/index.md b/files/en-us/web/webdriver/reference/bidi/modules/browsingcontext/historyupdated/index.md new file mode 100644 index 000000000000000..5f30c85c6e9de1e --- /dev/null +++ b/files/en-us/web/webdriver/reference/bidi/modules/browsingcontext/historyupdated/index.md @@ -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 diff --git a/files/en-us/web/webdriver/reference/bidi/modules/browsingcontext/load/index.md b/files/en-us/web/webdriver/reference/bidi/modules/browsingcontext/load/index.md new file mode 100644 index 000000000000000..306fe28e127c1c1 --- /dev/null +++ b/files/en-us/web/webdriver/reference/bidi/modules/browsingcontext/load/index.md @@ -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 diff --git a/files/en-us/web/webdriver/reference/bidi/modules/browsingcontext/navigationcommitted/index.md b/files/en-us/web/webdriver/reference/bidi/modules/browsingcontext/navigationcommitted/index.md new file mode 100644 index 000000000000000..9cdd67209233ccf --- /dev/null +++ b/files/en-us/web/webdriver/reference/bidi/modules/browsingcontext/navigationcommitted/index.md @@ -0,0 +1,78 @@ +--- +title: "`browsingContext.navigationCommitted` event" +short-title: navigationCommitted +slug: Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigationCommitted +page-type: webdriver-event +browser-compat: webdriver.bidi.browsingContext.navigationCommitted_event +sidebar: webdriver +--- + +The `browsingContext.navigationCommitted` [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 browser commits a cross-document navigation and begins loading the new page. + +## Description + +A navigation is committed when the browser has accepted the URL from the server response and begun loading the new page, but before any content has been parsed or rendered. Page content is not yet available at this point. + +In the lifecycle of a successful navigation, this event fires after [`browsingContext.navigationStarted`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigationStarted) and before [`browsingContext.domContentLoaded`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/domContentLoaded) and [`browsingContext.load`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/load) events. + +If you set `wait` to `"none"` 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.navigationCommitted` fires. + +This event does not fire for same-document navigations. +For navigations to a URL fragment, see [`browsingContext.fragmentNavigated`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/fragmentNavigated). +For URL changes made through the History API without a full navigation, see [`browsingContext.historyUpdated`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/historyUpdated). + +## 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 navigation is committed. +- `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 being loaded, including any basic auth credentials. +- `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 navigation is committed. + +## Examples + +### Receiving an event when a cross-document navigation commits + +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.navigationCommitted`. + +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 a [`browsingContext.navigationStarted`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigationStarted) event (that notification is not received since the subscription in this example is only to `browsingContext.navigationCommitted`). + +Once the browser accepts the server response and commits to loading the page, it sends the following notification, where the `context` value matches the context ID you passed to `browsingContext.navigate`: + +```json +{ + "type": "event", + "method": "browsingContext.navigationCommitted", + "params": { + "context": "9f271a75-04b2-4b35-80cc-e22427d446fc", + "navigation": "dc716296-7076-4ec0-b446-51c6fb5fefe8", + "timestamp": 1781715436774, + "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.navigationFailed`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigationFailed) event +- [`browsingContext.fragmentNavigated`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/fragmentNavigated) event +- [`browsingContext.historyUpdated`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/historyUpdated) event diff --git a/files/en-us/web/webdriver/reference/bidi/modules/browsingcontext/navigationfailed/index.md b/files/en-us/web/webdriver/reference/bidi/modules/browsingcontext/navigationfailed/index.md new file mode 100644 index 000000000000000..0600f09b885c580 --- /dev/null +++ b/files/en-us/web/webdriver/reference/bidi/modules/browsingcontext/navigationfailed/index.md @@ -0,0 +1,68 @@ +--- +title: "`browsingContext.navigationFailed` event" +short-title: navigationFailed +slug: Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigationFailed +page-type: webdriver-event +browser-compat: webdriver.bidi.browsingContext.navigationFailed_event +sidebar: webdriver +--- + +The `browsingContext.navigationFailed` [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 cannot be completed. + +## Description + +In the lifecycle of a failed navigation, this event fires after [`browsingContext.navigationStarted`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigationStarted) when the navigation cannot be completed. + +## 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 navigation failed. +- `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 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 navigation failed. + +## Examples + +### Receiving an event when a cross-document navigation fails + +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.navigationFailed`. + +Suppose you use [`browsingContext.navigate`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigate) to load a URL, passing the context ID you obtain from [`browsingContext.getTree`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/getTree). + +The browser first fires a [`browsingContext.navigationStarted`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigationStarted) event (that notification is not received since the subscription in this example is only to `browsingContext.navigationFailed`). + +The browser sends the following notification if the navigation cannot be completed, where the `context` value matches the context ID you passed to `browsingContext.navigate`: + +```json +{ + "type": "event", + "method": "browsingContext.navigationFailed", + "params": { + "context": "5e5e96e8-5247-4f22-9b35-a4a2d841cbaa", + "navigation": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "timestamp": 1712345678901, + "url": "https://not-a-valid-domain.example" + } +} +``` + +## 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 diff --git a/files/en-us/web/webdriver/reference/bidi/modules/browsingcontext/navigationstarted/index.md b/files/en-us/web/webdriver/reference/bidi/modules/browsingcontext/navigationstarted/index.md new file mode 100644 index 000000000000000..0563ad246a9a984 --- /dev/null +++ b/files/en-us/web/webdriver/reference/bidi/modules/browsingcontext/navigationstarted/index.md @@ -0,0 +1,80 @@ +--- +title: "`browsingContext.navigationStarted` event" +short-title: navigationStarted +slug: Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigationStarted +page-type: webdriver-event +browser-compat: webdriver.bidi.browsingContext.navigationStarted_event +sidebar: webdriver +--- + +The `browsingContext.navigationStarted` [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 begins in a context. + +## Description + +The navigation to a different page can be triggered by the [`browsingContext.navigate`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigate) or [`browsingContext.reload`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/reload) command, by user interaction with elements on the page, or by JavaScript running in the page's context. + +For cross-document navigations, this is the first in the sequence of navigation events and fires when the browser begins fetching the URL. +If the navigation succeeds, [`browsingContext.navigationCommitted`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigationCommitted) fires next, when the browser has accepted the response and begun loading the new page. +After that, [`browsingContext.domContentLoaded`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/domContentLoaded) fires when the HTML has been parsed, and [`browsingContext.load`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/load) fires last when the document and all its subresources have finished loading. +If the navigation fails, [`browsingContext.navigationFailed`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigationFailed) fires instead. + +> [!NOTE] +> This event is not emitted when the initial `about:blank` page is loaded for a new top-level browsing context. + +This event does not fire for same-document navigations. +For navigations to a URL fragment, see [`browsingContext.fragmentNavigated`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/fragmentNavigated). +For URL changes made through the History API without a full navigation, see [`browsingContext.historyUpdated`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/historyUpdated). + +## 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 navigation is starting. +- `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 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 navigation is starting. + +## Examples + +### Receiving an event when a cross-document navigation starts + +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.navigationStarted`. + +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 obtained from [`browsingContext.getTree`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/getTree). + +The browser sends the following notification, where the `context` value matches the context ID you passed to `browsingContext.navigate`: + +```json +{ + "type": "event", + "method": "browsingContext.navigationStarted", + "params": { + "context": "5e5e96e8-5247-4f22-9b35-a4a2d841cbaa", + "navigation": "a1b2c3d4-5678-90ab-cdef-1234567890ab", + "timestamp": 1781646423959, + "url": "https://example.com" + } +} +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [`browsingContext.navigationCommitted`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigationCommitted) event +- [`browsingContext.navigationFailed`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigationFailed) event +- [`browsingContext.fragmentNavigated`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/fragmentNavigated) event +- [`browsingContext.historyUpdated`](/en-US/docs/Web/WebDriver/Reference/BiDi/Modules/browsingContext/historyUpdated) event diff --git a/files/sidebars/webdriver.yaml b/files/sidebars/webdriver.yaml index 33bdbc8f5d90756..d4a8ff2d8e7a52f 100644 --- a/files/sidebars/webdriver.yaml +++ b/files/sidebars/webdriver.yaml @@ -62,6 +62,20 @@ sidebar: code: true - link: /Web/WebDriver/Reference/BiDi/Modules/browsingContext/contextDestroyed code: true + - link: /Web/WebDriver/Reference/BiDi/Modules/browsingContext/fragmentNavigated + code: true + - link: /Web/WebDriver/Reference/BiDi/Modules/browsingContext/historyUpdated + code: true + - link: /Web/WebDriver/Reference/BiDi/Modules/browsingContext/domContentLoaded + code: true + - link: /Web/WebDriver/Reference/BiDi/Modules/browsingContext/load + code: true + - link: /Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigationCommitted + code: true + - link: /Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigationFailed + code: true + - link: /Web/WebDriver/Reference/BiDi/Modules/browsingContext/navigationStarted + code: true - link: /Web/WebDriver/Reference/BiDi/Modules/emulation code: true - link: /Web/WebDriver/Reference/BiDi/Modules/input