Interface IRoute

Namespace

Microsoft.Playwright

Assembly

Microsoft.Playwright.dll

Whenever a network route is set up with RouteAsync(string, Action<IRoute>, PageRouteOptions?) or RouteAsync(string, Action<IRoute>, BrowserContextRouteOptions?), the Route object allows to handle the route.

Learn more about networking.

public interface IRoute

Properties

Request

A request to be routed.

IRequest Request { get; }

Property Value

IRequest

Methods

AbortAsync(string?)

Aborts the route's request.

Task AbortAsync(string? errorCode = null)

Parameters

errorCode string

Optional error code. Defaults to failed, could be one of the following:

• 'aborted' - An operation was aborted (due to user action)
• 'accessdenied' - Permission to access a resource, other than the network, was denied
• 'addressunreachable' - The IP address is unreachable. This usually means that there is no route to the specified host or network.
• 'blockedbyclient' - The client chose to block the request.
• 'blockedbyresponse' - The request failed because the response was delivered along with requirements which are not met ('X-Frame-Options' and 'Content-Security-Policy' ancestor checks, for instance).
• 'connectionaborted' - A connection timed out as a result of not receiving an ACK for data sent.
• 'connectionclosed' - A connection was closed (corresponding to a TCP FIN).
• 'connectionfailed' - A connection attempt failed.
• 'connectionrefused' - A connection attempt was refused.
• 'connectionreset' - A connection was reset (corresponding to a TCP RST).
• 'internetdisconnected' - The Internet connection has been lost.
• 'namenotresolved' - The host name could not be resolved.
• 'timedout' - An operation timed out.
• 'failed' - A generic failure occurred.

Returns

Task

ContinueAsync(RouteContinueOptions?)

Continues route's request with optional overrides.

**Usage**

await page.RouteAsync("**/*", async route =>
{
    var headers = new Dictionary<string, string>(route.Request.Headers) { { "foo", "bar" } };
    headers.Remove("origin");
    await route.ContinueAsync(new() { Headers = headers });
});

**Details**

Note that any overrides such as url or headers only apply to the request being routed. If this request results in a redirect, overrides will not be applied to the new redirected request. If you want to propagate a header through redirects, use the combination of FetchAsync(RouteFetchOptions?) and FulfillAsync(RouteFulfillOptions?) instead.

Task ContinueAsync(RouteContinueOptions? options = null)

Parameters

options RouteContinueOptions

Call options

Returns

Task

FallbackAsync(RouteFallbackOptions?)

When several routes match the given pattern, they run in the order opposite to their registration. That way the last registered route can always override all the previous ones. In the example below, request will be handled by the bottom-most handler first, then it'll fall back to the previous one and in the end will be aborted by the first registered route.

**Usage**

await page.RouteAsync("**/*", route => {
    // Runs last.
    await route.AbortAsync();
});
await page.RouteAsync("**/*", route => {
// Runs second.
await route.FallbackAsync();
});
await page.RouteAsync("**/*", route => {
// Runs first.
await route.FallbackAsync();
});

Registering multiple routes is useful when you want separate handlers to handle different kinds of requests, for example API calls vs page resources or GET requests vs POST requests as in the example below.

// Handle GET requests.
await page.RouteAsync("**/*", route => {
    if (route.Request.Method != "GET") {
        await route.FallbackAsync();
        return;
    }
    // Handling GET only.
    // ...
});
// Handle POST requests.
await page.RouteAsync("**/*", route => {
if (route.Request.Method != "POST") {
await route.FallbackAsync();
return;
}
// Handling POST only.
// ...
});

One can also modify request while falling back to the subsequent handler, that way intermediate route handler can modify url, method, headers and postData of the request.

await page.RouteAsync("**/*", async route =>
{
    var headers = new Dictionary<string, string>(route.Request.Headers) { { "foo", "foo-value" } };
    headers.Remove("bar");
    await route.FallbackAsync(new() { Headers = headers });
});

Task FallbackAsync(RouteFallbackOptions? options = null)

Parameters

options RouteFallbackOptions

Call options

Returns

Task

FetchAsync(RouteFetchOptions?)

Performs the request and fetches result without fulfilling it, so that the response could be modified and then fulfilled.

**Usage**

await page.RouteAsync("https://dog.ceo/api/breeds/list/all", async route =>
{
    var response = await route.FetchAsync();
    dynamic json = await response.JsonAsync();
    json.message.big_red_dog = new string[] {};
    await route.FulfillAsync(new() { Response = response, Json = json });
});

**Details**

Note that headers option will apply to the fetched request as well as any redirects initiated by it. If you want to only apply headers to the original request, but not to redirects, look into ContinueAsync(RouteContinueOptions?) instead.

Task<IAPIResponse> FetchAsync(RouteFetchOptions? options = null)

Parameters

options RouteFetchOptions

Call options

Returns

Task<IAPIResponse>

FulfillAsync(RouteFulfillOptions?)

Fulfills route's request with given response.

**Usage**

An example of fulfilling all requests with 404 responses:

await page.RouteAsync("**/*", route => route.FulfillAsync(new ()
{
    Status = 404,
    ContentType = "text/plain",
    Body = "Not Found!"
}));

An example of serving static file:

await page.RouteAsync("**/xhr_endpoint", route => route.FulfillAsync(new() { Path = "mock_data.json" }));

Task FulfillAsync(RouteFulfillOptions? options = null)

Parameters

options RouteFulfillOptions

Call options

Returns

Task