Package com.microsoft.playwright

Interface Route

All Known Implementing Classes:
RouteImpl
public interface Route
Whenever a network route is set up with Page.route() or BrowserContext.route(), the Route object allows to handle the route.

Learn more about networking.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static class 
    Route.FallbackOptions
     
    static class 
    Route.FetchOptions
     
    static class 
    Route.FulfillOptions
     
    static class 
    Route.ResumeOptions
     

  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    abort()
    Aborts the route's request.
    void
    abort(String errorCode)
    Aborts the route's request.
    default void
    fallback()
    When several routes match the given pattern, they run in the order opposite to their registration.
    void
    fallback(Route.FallbackOptions options)
    When several routes match the given pattern, they run in the order opposite to their registration.
    default APIResponse
    fetch()
    Performs the request and fetches result without fulfilling it, so that the response could be modified and then fulfilled.
    APIResponse
    fetch(Route.FetchOptions options)
    Performs the request and fetches result without fulfilling it, so that the response could be modified and then fulfilled.
    default void
    fulfill()
    Fulfills route's request with given response.
    void
    fulfill(Route.FulfillOptions options)
    Fulfills route's request with given response.
    Request
    request()
    A request to be routed.
    default void
    resume()
    Continues route's request with optional overrides.
    void
    resume(Route.ResumeOptions options)
    Continues route's request with optional overrides.

  • Method Details

    • abort

      default void abort()
      Aborts the route's request.
      Since:
      v1.8

    • abort

      void abort(String errorCode)
      Aborts the route's request.
      Parameters:
      errorCode - 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.
      Since:
      v1.8

    • resume

      default void resume()
      Continues route's request with optional overrides.

      **Usage** 

      
 page.route("**\/*", route -> {
   // Override headers
   Map<String, String> headers = new HashMap<>(route.request().headers());
   headers.put("foo", "foo-value"); // set "foo" header
   headers.remove("bar"); // remove "bar" header
   route.resume(new Route.ResumeOptions().setHeaders(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 Route.fetch() and Route.fulfill() instead.

      Since:
      v1.8

    • resume

      void resume(Route.ResumeOptions options)
      Continues route's request with optional overrides.

      **Usage** 

      
 page.route("**\/*", route -> {
   // Override headers
   Map<String, String> headers = new HashMap<>(route.request().headers());
   headers.put("foo", "foo-value"); // set "foo" header
   headers.remove("bar"); // remove "bar" header
   route.resume(new Route.ResumeOptions().setHeaders(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 Route.fetch() and Route.fulfill() instead.

      Since:
      v1.8

    • fallback

      default void fallback()
      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** 

      
 page.route("**\/*", route -> {
   // Runs last.
   route.abort();
 });

 page.route("**\/*", route -> {
   // Runs second.
   route.fallback();
 });

 page.route("**\/*", route -> {
   // Runs first.
   route.fallback();
 });

      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.
 page.route("**\/*", route -> {
   if (!route.request().method().equals("GET")) {
     route.fallback();
     return;
   }
   // Handling GET only.
   // ...
 });

 // Handle POST requests.
 page.route("**\/*", route -> {
   if (!route.request().method().equals("POST")) {
     route.fallback();
     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. 

      
 page.route("**\/*", route -> {
   // Override headers
   Map<String, String> headers = new HashMap<>(route.request().headers());
   headers.put("foo", "foo-value"); // set "foo" header
   headers.remove("bar"); // remove "bar" header
   route.fallback(new Route.ResumeOptions().setHeaders(headers));
 });
      Since:
      v1.23

    • fallback

      void fallback(Route.FallbackOptions options)
      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** 

      
 page.route("**\/*", route -> {
   // Runs last.
   route.abort();
 });

 page.route("**\/*", route -> {
   // Runs second.
   route.fallback();
 });

 page.route("**\/*", route -> {
   // Runs first.
   route.fallback();
 });

      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.
 page.route("**\/*", route -> {
   if (!route.request().method().equals("GET")) {
     route.fallback();
     return;
   }
   // Handling GET only.
   // ...
 });

 // Handle POST requests.
 page.route("**\/*", route -> {
   if (!route.request().method().equals("POST")) {
     route.fallback();
     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. 

      
 page.route("**\/*", route -> {
   // Override headers
   Map<String, String> headers = new HashMap<>(route.request().headers());
   headers.put("foo", "foo-value"); // set "foo" header
   headers.remove("bar"); // remove "bar" header
   route.fallback(new Route.ResumeOptions().setHeaders(headers));
 });
      Since:
      v1.23

    • fetch

      default APIResponse fetch()
      Performs the request and fetches result without fulfilling it, so that the response could be modified and then fulfilled.

      **Usage** 

      
 page.route("https://dog.ceo/api/breeds/list/all", route -> {
   APIResponse response = route.fetch();
   JsonObject json = new Gson().fromJson(response.text(), JsonObject.class);
   JsonObject message = itemObj.get("json").getAsJsonObject();
   message.set("big_red_dog", new JsonArray());
   route.fulfill(new Route.FulfillOptions()
     .setResponse(response)
     .setBody(json.toString()));
 });

      **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 Route.resume() instead.

      Since:
      v1.29

    • fetch

      APIResponse fetch(Route.FetchOptions options)
      Performs the request and fetches result without fulfilling it, so that the response could be modified and then fulfilled.

      **Usage** 

      
 page.route("https://dog.ceo/api/breeds/list/all", route -> {
   APIResponse response = route.fetch();
   JsonObject json = new Gson().fromJson(response.text(), JsonObject.class);
   JsonObject message = itemObj.get("json").getAsJsonObject();
   message.set("big_red_dog", new JsonArray());
   route.fulfill(new Route.FulfillOptions()
     .setResponse(response)
     .setBody(json.toString()));
 });

      **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 Route.resume() instead.

      Since:
      v1.29

    • fulfill

      default void fulfill()
      Fulfills route's request with given response.

      **Usage**

      An example of fulfilling all requests with 404 responses: 

      
 page.route("**\/*", route -> {
   route.fulfill(new Route.FulfillOptions()
     .setStatus(404)
     .setContentType("text/plain")
     .setBody("Not Found!"));
 });

      An example of serving static file: 

      
 page.route("**\/xhr_endpoint", route -> route.fulfill(
   new Route.FulfillOptions().setPath(Paths.get("mock_data.json"))));
      Since:
      v1.8

    • fulfill

      void fulfill(Route.FulfillOptions options)
      Fulfills route's request with given response.

      **Usage**

      An example of fulfilling all requests with 404 responses: 

      
 page.route("**\/*", route -> {
   route.fulfill(new Route.FulfillOptions()
     .setStatus(404)
     .setContentType("text/plain")
     .setBody("Not Found!"));
 });

      An example of serving static file: 

      
 page.route("**\/xhr_endpoint", route -> route.fulfill(
   new Route.FulfillOptions().setPath(Paths.get("mock_data.json"))));
      Since:
      v1.8

    • request

      Request request()
      A request to be routed.
      Since:
      v1.8