[Tech review] BiDi - Add pages for navigation and page load events of browsingContext module by dipikabh · Pull Request #44571 · mdn/content

dipikabh · 2026-06-25T00:32:37Z

Description

This PR adds pages for the following navigation and page load events:

browsingContext.navigationStarted
browsingContext.navigationCommitted
browsingContext.domContentLoaded
browsingContext.load
browsingContext.navigationFailed
browsingContext.fragmentNavigated
browsingContext.historyUpdated

Note

browsingContext.navigationAborted is not documented yet. The BCD key is also missing for this event. I'll cover it when there is an implementation.

Spec links

Related issue

Doc issue: mdn/mdn#339

github-actions · 2026-06-25T00:34:11Z

Preview URLs (9 pages)

dipikabh · 2026-06-25T00:43:49Z

+- `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.


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

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.

dipikabh · 2026-06-25T00:51:42Z

+```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"
+  }
+}
+```


I wasn't able to reproduce this. I used https://not-a-valid-domain.example as the URL but this returned:

"error": "unknown error", "message": "Error: NS_ERROR_UNKNOWN_HOST",

as a browsingContext.navigate command error rather than firing the browsingContext.navigationFailed event. The stacktrace showed #onNavigationCommitted being called.

Is the example documented here good enough? Any other variables I can tweak to trigger the event?

A navigation to an unknown host is not going to trigger navigationFailed, you can find the list of scenarios in the following comment: https://bugzilla.mozilla.org/show_bug.cgi?id=1846601#c9

The easiest to explain might be onbeforeunload where the user (or the test) rejects the unload?

Note that based on the HTML spec, there are some situations where we shouldn't emit navigationStarted (step 9 and 12 of https://html.spec.whatwg.org/#beginning-navigation, navigation started is step 18) but I'm not sure we implement that properly at the moment. I would maybe not mention navigationStarted here.

On my side: I will file a bug for your initial scenario. I'm not sure exactly how we should handle navigating to this https://not-a-valid-domain.example URL, but normally unknown error should be reserved for failed navigations, so that error looks fishy and in any case the error message means we didn't handle the navigation properly.

juliandescottes

(answers for the inline questions, reviewing the rest of the PR still, thanks!)

juliandescottes · 2026-06-30T12:37:16Z

+- `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.


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.

juliandescottes · 2026-06-30T13:01:48Z

+```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"
+  }
+}
+```


A navigation to an unknown host is not going to trigger navigationFailed, you can find the list of scenarios in the following comment: https://bugzilla.mozilla.org/show_bug.cgi?id=1846601#c9

The easiest to explain might be onbeforeunload where the user (or the test) rejects the unload?

Note that based on the HTML spec, there are some situations where we shouldn't emit navigationStarted (step 9 and 12 of https://html.spec.whatwg.org/#beginning-navigation, navigation started is step 18) but I'm not sure we implement that properly at the moment. I would maybe not mention navigationStarted here.

On my side: I will file a bug for your initial scenario. I'm not sure exactly how we should handle navigating to this https://not-a-valid-domain.example URL, but normally unknown error should be reserved for failed navigations, so that error looks fishy and in any case the error message means we didn't handle the navigation properly.

juliandescottes

Thanks, just some comments on my end, will take another look once they are addressed.

juliandescottes · 2026-06-30T13:27:23Z

+  - : 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).


Isn't it confusing to mention UTC here? This is just a number of ms since epoch, timezones should not matter.

juliandescottes · 2026-06-30T13:36:11Z

+  - : 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.


As a general note, navigation (and navigation events) can be triggered by other means than calling navigate or reload. 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.

juliandescottes · 2026-06-30T13:50:06Z

+
+## 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.


Cannot be completed is too vague, but at the same time I don't have a good short definition for this. Based on the list of examples, we could say that the navigation is blocked (could be for security/csp reason, because the user canceled the unload prompt...)

Maybe having navigationAborted documented could help a bit, Chrome implements it AFAIK. This one is triggered when we abort a document load.

dipikabh added 5 commits June 24, 2026 19:22

adds page for navigationstarted

8f960c8

adds page for navigationcommitted, navigationfailed

9cde0b9

adds pages for hisotrynavigated and fragmentuppdated

c8b6446

adds pages for domcontentloaded and load

516d90b

adds wait info

08aa2dc

dipikabh requested review from a team as code owners June 25, 2026 00:32

dipikabh requested review from hamishwillee and pepelsbey and removed request for a team June 25, 2026 00:32

github-actions Bot added Content:WebDriver WebDriver docs size/l [PR only] 501-1000 LoC changed labels Jun 25, 2026

dipikabh requested review from a team and removed request for hamishwillee and pepelsbey June 25, 2026 00:33

dipikabh commented Jun 25, 2026

View reviewed changes

juliandescottes reviewed Jun 30, 2026

View reviewed changes

juliandescottes requested changes Jun 30, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[Tech review] BiDi - Add pages for navigation and page load events of browsingContext module#44571

[Tech review] BiDi - Add pages for navigation and page load events of browsingContext module#44571
dipikabh wants to merge 5 commits into
mdn:mainfrom
dipikabh:bidi-browsingcontext-nav-events

dipikabh commented Jun 25, 2026

Uh oh!

github-actions Bot commented Jun 25, 2026

Uh oh!

dipikabh Jun 25, 2026

Uh oh!

juliandescottes Jun 30, 2026

Uh oh!

dipikabh Jun 25, 2026

Uh oh!

juliandescottes Jun 30, 2026

Uh oh!

juliandescottes left a comment

Uh oh!

juliandescottes Jun 30, 2026

Uh oh!

juliandescottes Jun 30, 2026

Uh oh!

juliandescottes left a comment

Uh oh!

juliandescottes Jun 30, 2026

Uh oh!

juliandescottes Jun 30, 2026

Uh oh!

juliandescottes Jun 30, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		- `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.


		## 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.

Uh oh!

Conversation

dipikabh commented Jun 25, 2026

Description

Spec links

Related issue

Uh oh!

github-actions Bot commented Jun 25, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

juliandescottes left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

juliandescottes left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

juliandescottes Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

juliandescottes Jun 30, 2026 •

edited

Loading