Orchestrate Multiple Local Services with Playwright webServer

Playwright should not start browser tests merely because three child processes exist. The frontend must serve the test build, the API must be ready for real requests, and any background worker must have completed initialization. A multiple webServer configuration becomes reliable only when command ownership, readiness, logs, reuse, ports, and shutdown are specified for every service.

This arrangement is ideal for a small local application stack that belongs to the test run. It removes manual startup from developer workflows and gives CI one command. It does not remove service dependencies; it makes their operational contracts explicit enough for the runner to enforce.

Inventory Processes and Their Readiness Signals

List each required long-running process before writing configuration. For every service, name the command, working directory, port, required environment, readiness signal, startup deadline, and shutdown behavior. Distinguish an HTTP service from a worker that only emits a ready event.

The official Playwright web server guide supports an array of configurations for simultaneous background processes. The array is not a dependency-order declaration. If the frontend's startup command requires the API to be ready first, make that command retry safely, use a wrapper that enforces the order, or move the dependency to a separate orchestrator.

Configure a Named Service Array

Use loopback addresses and fixed, non-overlapping test ports. Names prefix server log output and make startup failures easier to route. Configure local reuse once and apply it consistently unless one service has a deliberate exception.

import { defineConfig } from "@playwright/test";

const reuseLocalServer = !process.env.CI;

export default defineConfig({
  webServer: [
    {
      name: "API",
      command: "npm run dev:api",
      url: "http://127.0.0.1:4100/health/ready",
      env: { PORT: "4100", APP_ENV: "e2e" },
      timeout: 90_000,
      reuseExistingServer: reuseLocalServer,
      stdout: "pipe",
      stderr: "pipe",
      gracefulShutdown: { signal: "SIGTERM", timeout: 5_000 },
    },
    {
      name: "Frontend",
      command: "npm run dev:web -- --port 4173",
      url: "http://127.0.0.1:4173/health/ready",
      env: { PUBLIC_API_URL: "http://127.0.0.1:4100" },
      timeout: 120_000,
      reuseExistingServer: reuseLocalServer,
      stdout: "pipe",
      stderr: "pipe",
      gracefulShutdown: { signal: "SIGTERM", timeout: 5_000 },
    },
    {
      name: "NotificationWorker",
      command: "npm run dev:notification-worker",
      wait: { stdout: /notification worker ready/i },
      timeout: 60_000,
      reuseExistingServer: false,
      stdout: "pipe",
      stderr: "pipe",
      gracefulShutdown: { signal: "SIGTERM", timeout: 5_000 },
    },
  ],
  use: {
    baseURL: "http://127.0.0.1:4173",
  },
});

The exact commands and values belong to the application. Do not place database passwords or production credentials directly in config; inherit secrets through the CI environment or a dedicated test secret provider.

Make HTTP Readiness Dependency-Aware

Playwright considers several HTTP status classes ready, including successful responses and selected client-error responses. A dedicated health endpoint should therefore return a non-ready server status, such as 503, until required dependencies are usable, then return a clear successful response. Do not point readiness at /login if it can return a client error before the backend is initialized.

A strong API readiness endpoint checks that routing is active and required test infrastructure, such as the database schema, is available. A strong frontend readiness endpoint confirms the expected test build is being served. Keep checks fast and side-effect free.

// Illustrative service-side shape for the endpoint Playwright probes.
type Readiness = {
  ready: boolean;
  buildId: string;
  dependencies: Record<string, "ready" | "unavailable">;
};

export function readinessStatus(state: Readiness): number {
  const dependenciesReady = Object.values(state.dependencies)
    .every((value) => value === "ready");
  return state.ready && dependenciesReady ? 200 : 503;
}

The browser suite can separately assert a build fingerprint if reusing a local server might connect to the wrong checkout. Readiness and environment identity are related but distinct guarantees.

Use Output Readiness for Non-HTTP Workers

A queue consumer, event worker, or local emulator may not expose HTTP. Configure wait.stdout or wait.stderr with a message emitted only after subscriptions, migrations, and required connections complete. Avoid broad patterns such as /started/ that also match an early boot message.

When both url and wait are supplied, Playwright treats readiness as satisfied when either condition succeeds. Do not configure both if your intent is to require both. Put the combined requirement behind one health endpoint or wrapper process instead.

Output-based readiness is only as reliable as the application log contract. Treat the ready message as a stable interface and test that the process exits nonzero when initialization fails.

Decide When Local Reuse Is Safe

reuseExistingServer improves local iteration by accepting a process already listening at the configured endpoint. It can also hide a stale build, wrong branch, or incompatible environment. Keep it disabled in CI so the job owns the exact processes under test and port collisions fail loudly.

For local reuse, expose a build or mode fingerprint and assert it in a setup test or fixture. If the reused API has seeded state from yesterday, a health response alone cannot guarantee isolation. Provide a reset endpoint, temporary database, or unique run namespace.

The worker example disables reuse because a background process without an addressable endpoint cannot be identified safely by Playwright's existing-server check.

Keep Frontend and Service URLs Separate

use.baseURL makes browser navigation and relevant page URL matching concise. It does not mean every API helper should share the frontend origin. Create a typed API fixture with its own base URL or use absolute service URLs where the distinction is important.

import { test as base } from "@playwright/test";

type ServiceFixtures = {
  apiBaseUrl: string;
};

export const test = base.extend<ServiceFixtures>({
  apiBaseUrl: async ({}, use) => {
    await use("http://127.0.0.1:4100");
  },
});

test("frontend and API agree on order state", async ({ page, request, apiBaseUrl }) => {
  const response = await request.get(`${apiBaseUrl}/orders/ORD-1042`);
  if (!response.ok()) throw new Error(`Order API returned ${response.status()}`);

  await page.goto("/orders/ORD-1042");
  // Assert user-visible state against the API setup or contract.
});

In a larger framework, turn the API URL into an option fixture supplied by the selected project or environment configuration.

Preserve Logs That Explain Startup

Pipe stdout and stderr while establishing the orchestration policy. Named prefixes show which process bound a port, failed a migration, or emitted the readiness message. Once stable, noisy successful output can be reduced, but CI must retain enough information to diagnose startup timeout and early exit.

Application logs should include the selected port, environment mode, and readiness transition without exposing credentials. If service output is extensive, route it to CI artifacts with a clear retention policy instead of truncating the only evidence.

Plan Shutdown and Crash Recovery

Without a graceful shutdown policy, Playwright can forcefully terminate a process group. A service that needs to flush data or release an embedded database should handle the configured signal and exit within a bounded period. Playwright can follow a graceful signal with a forceful stop after the deadline.

Signal support differs on Windows, so cross-platform repositories should verify shutdown behavior on every runner family or use wrapper commands with portable cleanup. Also design test databases and leases to recover from hard termination; graceful process hooks cannot run after every crash.

Avoid Hidden Startup Ordering

Multiple web servers start simultaneously. If the frontend build only needs the API URL at runtime, this is usually fine because tests wait for all services. If the frontend startup command fetches API schema immediately, it can race the API. Fix the dependency explicitly rather than relying on array order.

Options include a retrying startup script, a generated schema checked into the build, or an external orchestrator with a real dependency graph. A fixed sleep before starting the frontend is fragile because it guesses at readiness rather than observing it.

Diagnose Common Failures

An immediate port error usually means another process owns the configured address and reuse is disabled, which is desirable in CI. A startup timeout with a healthy-looking log suggests the readiness URL or output regex does not match the actual contract. A test that begins before migrations finish indicates the probe is too shallow.

Intermittent local-only failures often point to reused stale processes. Orphan ports after cancellation point to signal handling or child processes escaping the process group. A worker that prints ready and then exits should fail the run; inspect its exit code and stderr rather than extending startup time.

Weigh webServer Against External Orchestration

Playwright webServer gives a small stack direct lifecycle ownership and excellent developer ergonomics. It becomes strained when services require ordered dependencies, containers, durable volumes, shared emulators, or production-like networking. In that case, let Compose, a task runner, or a provisioned test environment own the stack and give Playwright one verified endpoint.

The boundary should remain simple: one system owns startup and readiness. Layering several independent launch mechanisms produces duplicate processes and unclear cleanup responsibility.

Operational Checklist

• List every required process, port, environment value, and owner.
• Give each webServer entry a diagnostic name.
• Use dedicated readiness endpoints that include required dependencies.
• Use one precise output signal for non-HTTP processes.
• Do not rely on array order for startup dependencies.
• Disable existing-server reuse in CI.
• Verify the identity and state of reused local services.
• Keep frontend base URL and backend service URLs explicit.
• Pipe or retain logs needed to explain startup failures.
• Test graceful shutdown and hard-crash cleanup on supported platforms.

Conclusion: Make Readiness the Release Gate for Tests

Define the processes first, then give each one an addressable readiness contract, bounded startup, visible logs, and owned shutdown. Enable reuse only where a developer can verify the existing process, and move complex dependency graphs to a stronger orchestrator. Browser execution should begin because every required service proved it was ready, not because enough time happened to pass.