feat: server side mocking

docs/src/api/class-mockingproxyfactory.md

@@ -0,0 +1,18 @@
+# class: MockingProxyFactory
+* since: v1.51
+
+This class is used for creating [MockingProxy] instances which in turn can be used to intercept network traffic from your application server. An instance
+of this class can be obtained via [`property: Playwright.mockingProxy`]. For more information
+see [MockingProxy].
+
+## async method: MockingProxyFactory.newProxy
+* since: v1.16
+- returns: <[MockingProxy]>
+
+Creates a new instance of [MockingProxy].
+
+### param: MockingProxyFactory.newProxy.port
+* since: v1.51
+- `port` <[int]>
+
+Port to listen on.

docs/src/api/class-playwright.md

@@ -243,6 +243,10 @@ Selectors can be used to install custom selector engines. See
 
 This object can be used to launch or connect to WebKit, returning instances of [Browser].
 
+## property: Playwright.mockingProxy
+* since: v1.51
+- type: <[MockingProxyFactory]>
+
 ## method: Playwright.close
 * since: v1.9
 * langs: java

docs/src/mock.md

@@ -1,4 +1,4 @@
 ---
 id: mock
 title: "Mock APIs"
 ---
@@ -554,3 +554,169 @@
 ```
 
 For more details, see [WebSocketRoute].
+
+## Mock Application Server
+
+If you want to intercept network traffic originating from the server, you can use [MockingProxy] to intercept and mock network traffic going through a proxy server.
+
+```js
+test('calls the cms to fetch frontpage posts', async ({ page, server }) => {
+  await server.route("https://headless-cms.example.com/frontpage", (route, request) => {
+    await route.fulfill({
+      json: [
+        { id: 1, title: 'Hello, World!' },
+        { id: 2, title: 'Second post' },
+        { id: 2, title: 'Third post' }
+      ]
+    });
+  })
+
+  await page.goto('http://localhost:3000/');
+
+  await expect(page.getByRole('list')).toMatchAriaSnapshot(`
+    - list:
+      - listitem: Hello, World!
+      - listitem: Second post
+      - listitem: Third post
+  `);
+});
+```
+
+You can configure the port of the proxy server in the `playwright.config.ts` file.
+
+```ts
+# playwright.config.ts
+export default defineConfig({
+  workers: 1, // disable parallelism because we can't share the proxy server across multiple workers
+  ...
+  use: {
+    ...
+    mockingProxy: {
+      port: 8123 // example port
+    }
+  },
+});
+```
+
+We need to disable parallelism because we can't share the proxy server across multiple workers.
+
+Now, configure your application server to route HTTP traffic through `http://localhost:8123/`.
+
+#### `.env` file
+
+If you're using a `.env` file to configure API endpoints, prepend the proxy server URL:
+
+```env
+# .env.test
+CMS_BASE_URL=http://localhost:8123/https://headless-cms.example.com
+STOREFRONT_BASE_URL=http://localhost:8123/https://api.myexample.com
+```
+
+#### `HTTP_PROXY` environment variable
+
+If all your requests are going to localhost, you can use the `HTTP_PROXY` environment variable to route all requests through the proxy server.
+
+```bash
+HTTP_PROXY=http://localhost:8888
+```
+
+This environment variable is interpreted by many HTTP clients, including Node.js `axios` and Python `requests`. 
+
+Pay attention though: it's important that you use `HTTP_PROXY` and not `HTTPS_PROXY` because the latter will use [`CONNECT`-style proxying](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/CONNECT) where the proxy cannot intercept the traffic.
+
+#### Manual
+
+In your server code, prepend the proxy server URL to all outgoing requests:
+
+```js
+let proxyURL = isUnderTest ? 'http://localhost:8123/' : '';
+await axios.get(proxyURL + 'https://headless-cms.example.com/items');
+// or
+await fetch(proxyURL + 'https://headless-cms.example.com/frontpage');
+```
+
+```python
+proxy_url = "http://localhost:8123/" if is_under_test else ""
+requests.get(proxy_url + "https://headless-cms.example.com/frontpage")
+```
+
+```csharp
+var proxyURL = isUnderTest ? "http://localhost:8123/" : "";
+await client.GetAsync(proxyURL + "https://headless-cms.example.com/frontpage");
+```
+
+#### Injecting the proxy port
+
+The previous examples all use a single proxy server with a hard-coded port. This has the downside that you can't run tests in parallel.
+If your application allows accessing current request headers conveniently, you can use `inject` mode to dynamically create one proxy server per worker, and inject the port into the request headers.
+
+To do this, set `mockingProxy.port` to `'inject'` in your `playwright.config.ts`:
+
+```ts
+# playwright.config.ts
+export default defineConfig({
+  use: {
+    ...
+    mockingProxy: {
+      port: 'inject'
+    }
+  },
+});
+```
+
+Now, you can access the proxy port from the request headers:
+
+```js
+let proxyPort = await headers().get("x-playwright-proxy-port");
+let proxyURL = proxyPort ? `http://localhost:${proxyPort}/` : '';
+await axios.get(proxyURL + 'https://headless-cms.example.com/items');
+// or
+await fetch(proxyURL + 'https://headless-cms.example.com/frontpage');
+```
+
+```python
+proxy_port = request.headers.get("x-playwright-proxy-port")
+proxy_url = f"http://localhost:{proxy_port}/" if proxy_port else ""
+requests.get(proxy_url + "https://headless-cms.example.com/frontpage")
+```
+
+```csharp
+var proxyPort = httpContextAccessor.HttpContext?.Request.Headers["x-playwright-proxy-port"];
+var proxyURL = proxyPort.HasValue ? $"http://localhost:{proxyPort}/" : "";
+await client.GetAsync(proxyURL + "https://headless-cms.example.com/frontpage");
+```
+
+#### Interceptors
+
+If your HTTP client or runtime supports HTTP interceptors, you can use them to prepend the proxy URL to all outgoing requests
+with minimal changes to your existing code:
+
+##### Node.js Axios
+
+```js
+const api = axios.create({
+  baseURL: "https://jsonplaceholder.typicode.com",
+});
+
+if (isUnderTest) {
+  api.interceptors.request.use(async config => {
+    config.proxy = { protocol: "http", host: "localhost", port: 8123 };
+    return config;
+  });
+}
+```
+
+##### Node.js fetch / undici
+
+```js
+import { setGlobalDispatcher, getGlobalDispatcher } from "undici";
+
+if (isUnderTest) {
+  const proxyingDispatcher = getGlobalDispatcher().compose(dispatch => (opts, handler) => {
+    opts.path = opts.origin + opts.path;
+    opts.origin = `http://localhost:8123`;
+    return dispatch(opts, handler);
+  })
+  setGlobalDispatcher(proxyingDispatcher);
+}
+```

docs/src/test-api/class-fixtures.md

@@ -112,3 +112,9 @@ test('basic test', async ({ request }) => {
   // ...
 });
 ```
+
+## property: Fixtures.server
+* since: v1.51
+- type: <[MockingProxy]>
+
+Instance of [MockingProxy] that can be used to intercept network requests from your application server.

docs/src/test-api/class-testoptions.md

@@ -676,3 +676,22 @@ export default defineConfig({
   },
 });
 ```
+
+## property: TestOptions.mockingProxy
+* since: v1.51
+- type: <[Object]>
+  - `port` <[int]|"inject"> What port to start the mocking proxy on. If set to `"inject"`, Playwright will use a free port and inject it into all outgoing requests under the `x-playwright-proxy-port` parameter.
+
+**Usage**
+
+```js title="playwright.config.ts"
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    mockingProxy: {
+      port: 9956,
+    },
+  },
+});
+```

packages/playwright-core/src/client/browserContext.ts

@@ -198,7 +198,7 @@ export class BrowserContext extends ChannelOwner<channels.BrowserContextChannel>
   }
 
   async _onRoute(route: network.Route) {
-    route._context = this;
+    route._request = this.request;
     const page = route.request()._safePage();
     const routeHandlers = this._routes.slice();
     for (const routeHandler of routeHandlers) {

packages/playwright-core/src/client/localUtils.ts

@@ -17,6 +17,7 @@
 import type * as channels from '@protocol/channels';
 import { ChannelOwner } from './channelOwner';
 import type { Size } from './types';
+import { APIRequestContext } from './fetch';
 
 type DeviceDescriptor = {
   userAgent: string,
@@ -30,12 +31,14 @@ type Devices = { [name: string]: DeviceDescriptor };
 
 export class LocalUtils extends ChannelOwner<channels.LocalUtilsChannel> {
   readonly devices: Devices;
+  readonly requestContext: APIRequestContext;
 
   constructor(parent: ChannelOwner, type: string, guid: string, initializer: channels.LocalUtilsInitializer) {
     super(parent, type, guid, initializer);
     this.markAsInternalType();
     this.devices = {};
     for (const { name, descriptor } of initializer.deviceDescriptors)
       this.devices[name] = descriptor;
+    this.requestContext = APIRequestContext.from(initializer.requestContext);
   }
 }