feat(test): support project-specific web servers (#43860)

Co-authored-by: microsoft-playwright-automation[bot] <203992400+microsoft-playwright-automation[bot]@users.noreply.github.com>

Author: microsoft-playwright-automation[bot]

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

@@ -164,6 +164,7 @@ Playwright version.
 - type: <[null]|[Object]>
 
 See [`property: TestConfig.webServer`].
+This property is `null` in merged reports because server configuration is not serialized.
 
 ## property: FullConfig.workers
 * since: v1.10

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

@@ -99,3 +99,11 @@ See [`property: TestProject.timeout`].
 - type: <[Fixtures]>
 
 See [`property: TestProject.use`].
+
+## property: FullProject.webServer
+* since: v1.66
+- type: <[Array]<[Object]>>
+
+The servers configured in [`property: TestProject.webServer`], normalized to an array.
+Does not include top-level servers.
+This property is an empty array in merged reports because server configuration is not serialized.

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

@@ -736,6 +736,9 @@ export default defineConfig({
 
 Launch a development web server (or multiple) during the tests.
 
+Top-level servers start before `globalSetup` and stop after `globalTeardown`, regardless of project
+selection. To start servers only for particular projects, use [`property: TestProject.webServer`].
+
 **Details**
 
 If the port is specified, Playwright Test will wait for it to be available on `127.0.0.1` or `::1`, before running the tests. If the url is specified, Playwright Test will wait for the URL to return a 2xx, 3xx, 400, 401, 402, or 403 status code before running the tests.

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

@@ -4,7 +4,7 @@
 
 Playwright Test supports running multiple test projects at the same time. This is useful for running tests in multiple configurations. For example, consider running tests against multiple browsers. This type describes format of a project in the configuration file, to access resolved configuration parameters at run time use [FullProject].
 
-`TestProject` encapsulates configuration specific to a single project. Projects are configured in [`property: TestConfig.projects`] specified in the [configuration file](../test-configuration.md). Note that all properties of [TestProject] are available in the top-level [TestConfig], in which case they are shared between all projects.
+`TestProject` encapsulates configuration specific to a single project. Projects are configured in [`property: TestConfig.projects`] specified in the [configuration file](../test-configuration.md). Note that all properties of [TestProject] are available in the top-level [TestConfig], in which case they are shared between all projects. The exception is [`property: TestProject.webServer`]: top-level servers are started separately, for the whole run.
 
 Here is an example configuration that runs every test in Chromium, Firefox and WebKit, both Desktop and Mobile versions.
 
@@ -428,6 +428,53 @@ export default defineConfig({
 
 Use [`property: TestConfig.use`] to change this option for all projects.
 
+## property: TestProject.webServer
+* since: v1.66
+- type: ?<[Object]|[Array]<[Object]>>
+
+Launch a development web server (or multiple) for this project. Accepts the same options as
+[`property: TestConfig.webServer`].
+
+Project servers are added to the top-level servers, not inherited from them or used to replace them.
+They start after `globalSetup` and stop before its returned teardown function and `globalTeardown`.
+In the command line, project selection controls which servers start, including servers for
+dependencies and teardown projects. Test filters and sharding do not affect server startup.
+Listing tests does not start project servers. In UI mode and VS Code, all project servers start
+with global setup and stay alive across test runs until global teardown or configuration reload.
+
+[`property: FullProject.webServer`] exposes these settings as an array, including in `globalSetup`.
+Project servers are not available during `globalSetup` or `globalTeardown`.
+
+For a single server with `port` and no `url`, the project's [`property: TestOptions.baseURL`] defaults
+to `http://localhost:<port>`. An explicitly configured `baseURL` takes precedence. For arrays or
+servers with `url`, configure `baseURL` explicitly.
+
+**Usage**
+
+```js title="playwright.config.ts"
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  projects: [
+    {
+      name: 'local',
+      webServer: {
+        command: 'npm run start',
+        url: 'http://localhost:3000',
+        reuseExistingServer: !process.env.CI,
+      },
+      use: { baseURL: 'http://localhost:3000' },
+    },
+    {
+      name: 'production',
+      use: { baseURL: 'https://production.example' },
+    },
+  ],
+});
+```
+
+Running `npx playwright test --project=production` does not start the local server.
+
 ## property: TestProject.workers
 * since: v1.52
 - type: ?<[int]|[string]>

docs/src/test-webserver-js.md

@@ -7,6 +7,10 @@ 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.
 
+To start a server only when a particular project runs, configure
+[`property: TestProject.webServer`] inside that project. Top-level servers start regardless of the
+selected projects. Put servers shared by multiple projects at the top level.
+
 ## Configuring a web server
 
 Use the `webServer` property in your Playwright config to launch a development web server during the tests.

packages/playwright/src/common/config.ts

@@ -131,7 +131,7 @@ export class FullConfigInternal {
     }
 
     // When no projects are defined, do not use config.workers as a hard limit for project.workers.
-    const projectConfigs = configCLIOverrides.projects || userConfig.projects || [{ ...userConfig, workers: undefined }];
+    const projectConfigs = configCLIOverrides.projects || userConfig.projects || [{ ...userConfig, workers: undefined, webServer: undefined }];
     this.projects = projectConfigs.map(p => new FullProjectInternal(configDir, userConfig, this, p, this.configCLIOverrides, packageJsonDir));
     resolveProjectDependencies(this.projects);
     this._assignUniqueProjectIds(this.projects);
@@ -175,6 +175,9 @@ export class FullProjectInternal {
     this.snapshotPathTemplate = takeFirst(projectConfig.snapshotPathTemplate, config.snapshotPathTemplate);
 
     const use = mergeObjects(config.use, projectConfig.use, configCLIOverrides.use);
+    const webServer = projectConfig.webServer;
+    if (use.baseURL === undefined && webServer && !Array.isArray(webServer) && webServer.port && !webServer.url)
+      use.baseURL = `http://localhost:${webServer.port}`;
     // `--trace <mode>` only forces the tracing mode, preserving other trace options from the config.
     const configTrace = takeFirst((projectConfig.use as Partial<PlaywrightWorkerOptions> | undefined)?.trace, (config.use as Partial<PlaywrightWorkerOptions> | undefined)?.trace);
     if (typeof configCLIOverrides.use?.trace === 'string' && typeof configTrace === 'object' && configTrace)
@@ -199,7 +202,12 @@ export class FullProjectInternal {
       dependencies: projectConfig.dependencies || [],
       teardown: projectConfig.teardown,
       ignoreSnapshots: takeFirst(configCLIOverrides.ignoreSnapshots,  projectConfig.ignoreSnapshots, config.ignoreSnapshots, false),
+      webServer: webServer ? (Array.isArray(webServer) ? webServer : [webServer]) : [],
     };
+    for (const server of this.project.webServer) {
+      if (server.port !== undefined && server.url !== undefined)
+        throw new Error(`Either 'port' or 'url' should be specified in projects[${this.project.name}].webServer.`);
+    }
     this.fullyParallel = takeFirst(configCLIOverrides.fullyParallel, projectConfig.fullyParallel, config.fullyParallel, undefined);
     this.expect = takeFirst(projectConfig.expect, config.expect, {});
     if (this.expect.toHaveScreenshot?.stylePath) {

packages/playwright/src/isomorphic/teleReceiver.ts

@@ -486,6 +486,7 @@ export class TeleReporterReceiver {
       snapshotDir: this._absolutePath(project.snapshotDir),
       ignoreSnapshots: project.ignoreSnapshots ?? false,
       use: project.use,
+      webServer: [],
     };
   }
 

packages/playwright/src/plugins/webServerPlugin.ts

@@ -27,6 +27,7 @@ import { launchProcess } from '@utils/processLauncher';
 
 import type { TestRunnerPlugin } from '.';
 import type { FullConfig } from '../../types/testReporter';
+import type { FullProject } from '../../types/test';
 import type { FullConfigInternal } from '../common';
 import type { ReporterV2 } from '../reporters/reporterV2';
 
@@ -59,14 +60,16 @@ export class WebServerPlugin implements TestRunnerPlugin {
   private _processExitedPromise!: Promise<any>;
   private _options: WebServerPluginOptions;
   private _checkPortOnly: boolean;
+  private _configLabel: string;
   private _reporter?: ReporterV2;
   private _waitForStdioPromise: ManualPromise | undefined;
 
   name = 'playwright:webserver';
 
-  constructor(options: WebServerPluginOptions, checkPortOnly: boolean) {
+  constructor(options: WebServerPluginOptions, checkPortOnly: boolean, configLabel = 'config.webServer') {
     this._options = options;
     this._checkPortOnly = checkPortOnly;
+    this._configLabel = configLabel;
   }
 
   public async setup(config: FullConfig, configDir: string, reporter: ReporterV2) {
@@ -99,11 +102,11 @@ export class WebServerPlugin implements TestRunnerPlugin {
       if (this._options.reuseExistingServer)
         return;
       const port = new URL(this._options.url!).port;
-      throw new Error(`${this._options.url ?? `http://localhost${port ? ':' + port : ''}`} is already used, make sure that nothing is running on the port/url or set reuseExistingServer:true in config.webServer.`);
+      throw new Error(`${this._options.url ?? `http://localhost${port ? ':' + port : ''}`} is already used, make sure that nothing is running on the port/url or set reuseExistingServer:true in ${this._configLabel}.`);
     }
 
     if (!this._options.command)
-      throw new Error('config.webServer.command cannot be empty');
+      throw new Error(`${this._configLabel}.command cannot be empty`);
 
     debugWebServer(`Starting WebServer process ${this._options.command}...`);
     const { launchedProcess, gracefullyClose } = await launchProcess({
@@ -139,7 +142,7 @@ export class WebServerPlugin implements TestRunnerPlugin {
         });
       },
       log: () => {},
-      onExit: code => processExitedReject(new Error(code ? `Process from config.webServer was not able to start. Exit code: ${code}` : 'Process from config.webServer exited early.')),
+      onExit: code => processExitedReject(new Error(code ? `Process from ${this._configLabel} was not able to start. Exit code: ${code}` : `Process from ${this._configLabel} exited early.`)),
       tempDirectories: [],
     });
     this._killProcess = gracefullyClose;
@@ -205,7 +208,7 @@ export class WebServerPlugin implements TestRunnerPlugin {
     const { timedOut } = await Promise.race(racingPromises);
     cancellationToken.canceled = true;
     if (timedOut)
-      throw new Error(`Timed out waiting ${launchTimeout}ms from config.webServer.`);
+      throw new Error(`Timed out waiting ${launchTimeout}ms from ${this._configLabel}.`);
     debugWebServer(`WebServer available`);
   }
 }
@@ -260,11 +263,18 @@ export const webServer = (options: WebServerPluginOptions): TestRunnerPlugin =>
 };
 
 export const webServerPluginsForConfig = (config: FullConfigInternal): TestRunnerPlugin[] => {
-  const shouldSetBaseUrl = !!config.config.webServer;
+  return webServerPluginsForServers(config.webServers, !!config.config.webServer, 'config.webServer');
+};
+
+export const webServerPluginsForProject = (project: FullProject): TestRunnerPlugin[] => {
+  return webServerPluginsForServers(project.webServer, false, `projects[${project.name}].webServer`);
+};
+
+function webServerPluginsForServers(webServers: FullProject['webServer'], shouldSetBaseUrl: boolean, configLabel: string): TestRunnerPlugin[] {
   const webServerPlugins = [];
-  for (const webServerConfig of config.webServers) {
+  for (const webServerConfig of webServers) {
     if (webServerConfig.port && webServerConfig.url)
-      throw new Error(`Either 'port' or 'url' should be specified in config.webServer.`);
+      throw new Error(`Either 'port' or 'url' should be specified in ${configLabel}.`);
 
     let url: string | undefined;
     if (webServerConfig.port || webServerConfig.url) {
@@ -274,11 +284,11 @@ export const webServerPluginsForConfig = (config: FullConfigInternal): TestRunne
       if (shouldSetBaseUrl && !webServerConfig.url)
         process.env.PLAYWRIGHT_TEST_BASE_URL = url;
     }
-    webServerPlugins.push(new WebServerPlugin({ ...webServerConfig,  url }, webServerConfig.port !== undefined));
+    webServerPlugins.push(new WebServerPlugin({ ...webServerConfig,  url }, webServerConfig.port !== undefined, configLabel));
   }
 
   return webServerPlugins;
-};
+}
 
 function prefixOutputLines(output: string, prefixName: string = 'WebServer'): string {
   const lastIsNewLine = output[output.length - 1] === '\n';

packages/playwright/src/reporters/teleEmitter.ts

@@ -182,7 +182,6 @@ export class TeleReporterEmitter implements ReporterV2 {
       globalSetup: config.globalSetup,
       globalTeardown: config.globalTeardown,
       tags: config.tags,
-      webServer: config.webServer,
       failOnFlakyTests: config.failOnFlakyTests,
     };
   }

packages/playwright/src/runner/tasks.ts

@@ -25,13 +25,14 @@ import { removeFolders } from '@utils/fileUtils';
 
 import { Dispatcher  } from './dispatcher';
 import { collectProjectsAndTestFiles, createRootSuite, loadFileSuites, loadGlobalHook, loadTestList } from './loadUtils';
-import { buildDependentProjects, buildTeardownToSetupsMap, filterProjects } from './projectUtils';
+import { buildDependentProjects, buildProjectsClosure, buildTeardownToSetupsMap, filterProjects } from './projectUtils';
 import { applySuggestedRebaselines, clearSuggestedRebaselines } from './rebase';
 import { TaskRunner } from './taskRunner';
 import { detectChangedTestFiles } from './vcs';
 import { cc, config as commonConfig, FullConfigInternal, suiteUtils, test as testNs } from '../common';
 import { createTestGroups, shuffleTestGroups } from '../runner/testGroups';
 import { createTitleMatcher, forceRegExp, removeDirAndLogToConsole } from '../util';
+import { webServerPluginsForProject } from '../plugins/webServerPlugin';
 
 import type { TestGroup } from '../runner/testGroups';
 import type { EnvByProjectId } from './dispatcher';
@@ -159,6 +160,7 @@ export function createGlobalSetupTasks(config: FullConfigInternal) {
     ...createPluginSetupTasks(config),
     ...config.globalTeardowns.map(file => createGlobalTeardownTask(file, config)).reverse(),
     ...config.globalSetups.map(file => createGlobalSetupTask(file, config)),
+    ...createProjectWebServerSetupTasks(config),
   ];
 }
 
@@ -170,6 +172,26 @@ export function createRunTestsTasks(config: FullConfigInternal) {
   ];
 }
 
+function createProjectWebServerSetupTasks(config: FullConfigInternal): Task<TestRun>[] {
+  return config.projects.flatMap(project => webServerPluginsForProject(project.project).map(plugin => {
+    let started = false;
+    return {
+      title: 'project web server setup',
+      setup: async ({ filteredProjects, reporter }) => {
+        const projects = buildProjectsClosure(filteredProjects);
+        if (!projects.has(project))
+          return;
+        started = true;
+        await plugin.setup?.(config.config, config.configDir, reporter);
+      },
+      teardown: async () => {
+        if (started)
+          await plugin.teardown?.();
+      },
+    };
+  }));
+}
+
 export function createClearCacheTask(config: FullConfigInternal): Task<TestRun> {
   return {
     title: 'clear cache',