From 43e852334b451c34336d2dafe104831a836a0866 Mon Sep 17 00:00:00 2001
From: Yury Semikhatsky <yurys@chromium.org>
Date: Tue, 6 Aug 2024 11:35:53 -0700
Subject: [PATCH] docs: route.fallback() vs. route.continue() (#32035)

Fixes https://github.com/microsoft/playwright/issues/31983
---
 docs/src/api/class-route.md               | 12 +++++++++---
 packages/playwright-core/types/types.d.ts | 17 ++++++++++++++---
 2 files changed, 23 insertions(+), 6 deletions(-)

diff --git a/docs/src/api/class-route.md b/docs/src/api/class-route.md
index 8155e3d60d..106fbf55e0 100644
--- a/docs/src/api/class-route.md
+++ b/docs/src/api/class-route.md
@@ -39,7 +39,7 @@ Optional error code. Defaults to `failed`, could be one of the following:
   - alias-java: resume
   - alias-python: continue_
 
-Continues route's request with optional overrides.
+Sends route's request to the network with optional overrides.
 
 **Usage**
 
@@ -104,6 +104,8 @@ await page.RouteAsync("**/*", async route =>
 
 Note that any overrides such as [`option: url`] or [`option: 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 [`method: Route.fetch`] and [`method: Route.fulfill`] instead.
 
+[`method: Route.continue`] will immediately send the request to the network, other matching handlers won't be invoked. Use [`method: Route.fallback`] If you want next matching handler in the chain to be invoked.
+
 ### option: Route.continue.url
 * since: v1.8
 - `url` <[string]>
@@ -146,13 +148,15 @@ If set changes the request HTTP headers. Header values will be converted to a st
 ## async method: Route.fallback
 * since: v1.23
 
+Continues route's request with optional overrides. The method is similar to [`method: Route.continue`] with the difference that other matching handlers will be invoked before sending the request.
+
+**Usage**
+
 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**
-
 ```js
 await page.route('**/*', async route => {
   // Runs last.
@@ -386,6 +390,8 @@ await page.RouteAsync("**/*", async route =>
 });
 ```
 
+Use [`method: Route.continue`] to immediately send the request to the network, other matching handlers won't be invoked in that case.
+
 ### option: Route.fallback.url
 * since: v1.23
 - `url` <[string]>
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index 8e818983c9..94babc9e80 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -19440,7 +19440,7 @@ export interface Route {
   abort(errorCode?: string): Promise<void>;
 
   /**
-   * Continues route's request with optional overrides.
+   * Sends route's request to the network with optional overrides.
    *
    * **Usage**
    *
@@ -19463,6 +19463,11 @@ export interface Route {
    * through redirects, use the combination of
    * [route.fetch([options])](https://playwright.dev/docs/api/class-route#route-fetch) and
    * [route.fulfill([options])](https://playwright.dev/docs/api/class-route#route-fulfill) instead.
+   *
+   * [route.continue([options])](https://playwright.dev/docs/api/class-route#route-continue) will immediately send the
+   * request to the network, other matching handlers won't be invoked. Use
+   * [route.fallback([options])](https://playwright.dev/docs/api/class-route#route-fallback) If you want next matching
+   * handler in the chain to be invoked.
    * @param options
    */
   continue(options?: {
@@ -19488,13 +19493,17 @@ export interface Route {
   }): Promise<void>;
 
   /**
+   * Continues route's request with optional overrides. The method is similar to
+   * [route.continue([options])](https://playwright.dev/docs/api/class-route#route-continue) with the difference that
+   * other matching handlers will be invoked before sending the request.
+   *
+   * **Usage**
+   *
    * 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**
-   *
    * ```js
    * await page.route('**\/*', async route => {
    *   // Runs last.
@@ -19550,6 +19559,8 @@ export interface Route {
    * });
    * ```
    *
+   * Use [route.continue([options])](https://playwright.dev/docs/api/class-route#route-continue) to immediately send the
+   * request to the network, other matching handlers won't be invoked in that case.
    * @param options
    */
   fallback(options?: {