network module

The network module contains commands and events for monitoring and controlling the browser's network requests and responses.

Requests

In WebDriver BiDi, each network request the browser makes has a request ID. This includes requests for a page or its subresources, such as stylesheets and scripts, as well as requests made by a script using fetch(). Every event in the network module that relates to the request includes this ID in the request field of its request object. You can use this ID to match events that belong to the same request.

A request that loads a document into a context as part of a navigation has a navigation ID. This includes the request for a navigation started with browsingContext.navigate. This ID matches the navigation ID of the browsingContext events for the same navigation, such as browsingContext.navigationStarted. Requests for the document's subresources have a navigation value of null.

Request lifecycle

To receive the events, subscribe to them with session.subscribe. As a request goes ahead, the browser sends the following events in order:

  1. network.beforeRequestSent fires before the browser sends the request over the network or before it handles the request using its cache.
  2. network.responseStarted fires when the browser has received the response headers.
  3. network.responseCompleted fires when the browser has received the whole response body.

If the server asks for authentication, the browser also sends network.authRequired after network.responseStarted. If the request fails at any point, for example because the host can't be reached or because the page aborts the request while the body is arriving, the browser sends network.fetchError. This is the last event in the request's lifecycle.

When the server responds with a redirect, the browser sends network.responseStarted and network.responseCompleted for the redirect response, and then network.beforeRequestSent for the new URL. All the events for the original URL and the new URL have the same request ID, and the redirectCount field increases by one with each redirect.

Intercepts

A client can block requests or responses with intercepts, which can be added to the session using the network.addIntercept command. When a request matches an intercept, the browser blocks the request or response at a phase that the intercept covers, provided the client is subscribed to the corresponding event (such as network.beforeRequestSent or network.responseStarted). The event for that phase has isBlocked set to true and includes the matching intercept IDs in its payload. The browser then waits until the client lets the request continue, for example with the network.continueRequest command.

Commands

Events

Specifications

Specification
WebDriver BiDi
# module-network

Browser compatibility