From 6d549320b1f7b7a5e2cfed33a25ffd2533c0041b Mon Sep 17 00:00:00 2001
From: Debbie O'Brien <debs-obrien@users.noreply.github.com>
Date: Mon, 6 Mar 2023 16:42:54 +0100
Subject: [PATCH] docs: add doc on webserver (#21378)

---
 docs/src/test-webserver-js.md | 115 ++++++++++++++++++++++++++++++++++
 1 file changed, 115 insertions(+)
 create mode 100644 docs/src/test-webserver-js.md

diff --git a/docs/src/test-webserver-js.md b/docs/src/test-webserver-js.md
new file mode 100644
index 0000000000..8666c3bae3
--- /dev/null
+++ b/docs/src/test-webserver-js.md
@@ -0,0 +1,115 @@
+---
+id: test-webserver
+title: "Web Server"
+---
+
+Playwright comes with a `webserver` option in the config file which gives you the ability to launch a local dev server before running your tests. This is ideal for when writing your tests during development and when you don't have a staging or production url to test against.
+
+## Configuring a web server
+
+Use the `webserver` property in your Playwright config to launch a development web server during the tests.
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  // Run your local dev server before starting the tests
+  webServer: {
+    command: 'npm run start',
+    url: 'http://127.0.0.1:3000',
+    reuseExistingServer: !process.env.CI,
+  },
+});
+```
+
+| Property | Description |
+| :- | :- |
+| [`property: TestConfig.webServer`] | Launch a development web server (or multiple) during the tests. |
+| `command`| Shell command to start the local dev server of your app. |
+| `url`| URL of your http server that is expected to return a 2xx, 3xx, 400, 401, 402, or 403 status code when the server is ready to accept connections. |
+| `reuseExistingServer`| If `true`, it will re-use an existing server on the url when available. If no server is running on that url, it will run the command to start a new server. If `false`, it will throw if an existing process is listening on the url. To see the stdout, you can set the `DEBUG=pw:webserver` environment variable. |
+
+## Adding a server timeout
+
+Webservers can sometimes take longer to boot up. In this case, you can increase the timeout to wait for the server to start.
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  // Rest of your config...
+
+  // Run your local dev server before starting the tests
+  webServer: {
+    command: 'npm run start',
+    url: 'http://127.0.0.1:3000',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120 * 1000,
+  },
+});
+```
+
+## Adding a baseURL
+
+It is also recommended to specify the `baseURL` in the `use: {}` section of your config, so that tests can use relative urls and you don't have to specify the full URL over and over again. 
+
+When using [`method: Page.goto`], [`method: Page.route`], [`method: Page.waitForURL`], [`method: Page.waitForRequest`], or [`method: Page.waitForResponse`] it takes the base URL in consideration by using the [`URL()`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) constructor for building the corresponding URL. For Example, by setting the baseURL to `http://127.0.0.1:3000` and navigating to `/login` in your tests, Playwright will run the test using `http://127.0.0.1:3000/login`.
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  // Rest of your config...
+
+  // Run your local dev server before starting the tests
+  webServer: {
+    command: 'npm run start',
+    url: 'http://127.0.0.1:3000',
+    reuseExistingServer: !process.env.CI,
+  },
+  use: {
+    baseURL: 'http://127.0.0.1:3000',
+  },
+});
+```
+
+Now you can use a relative path when navigating the page:
+
+```js
+// test.spec.js
+const { test } = require('@playwright/test');
+
+test('test', async ({ page }) => {
+  // This will navigate to http://127.0.0.1:3000/login
+  await page.goto('./login');
+});
+```
+
+## Multiple web servers
+
+Multiple web servers (or background processes) can be launched simultaneously by providing an array of `webServer` configurations. See [`property: TestConfig.webServer`] for more info.
+
+
+```js
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  webServer: [
+    {
+      command: 'npm run start',
+      url: 'http://127.0.0.1:3000',
+      timeout: 120 * 1000,
+      reuseExistingServer: !process.env.CI,
+    },
+    {
+      command: 'npm run backend',
+      url: 'http://127.0.0.1:3333',
+      timeout: 120 * 1000,
+      reuseExistingServer: !process.env.CI,
+    }
+  ],
+  use: {
+    baseURL: 'http://127.0.0.1:3000',
+  },
+});
+```