Design a Playwright Project Matrix for Browsers, Devices, and Environments

A Playwright project matrix should express product risk, not enumerate every combination your configuration syntax can produce. Browsers, device profiles, and deployment environments are independent dimensions, but multiplying all of them creates duplicate execution, noisy reports, and expensive triage. The useful matrix is the smallest set of projects that can expose meaningful differences.

The design work therefore starts before playwright.config.ts. Identify where browser engines differ, which responsive interactions matter, and which environments have distinct integrations or policy. Then encode those decisions as named projects that a developer can run locally and a CI system can schedule deliberately.

Start With Coverage Questions, Not Configuration

Write down the failure hypothesis for each proposed project. Chromium, Firefox, and WebKit can be justified when the product promises support for all three engines. A mobile descriptor is justified when navigation, touch targets, viewport-dependent layouts, or mobile user-agent behavior creates risk. A production project may be justified for a tiny read-only synthetic journey, but it is a poor place for destructive checkout or account-management tests.

The official Playwright projects guide defines a project as a logical group of tests with the same configuration. That definition is broader than "browser." Projects can vary browser, device, authentication, retry policy, test selection, or environment. Use that flexibility to describe intentional coverage lanes rather than a mechanical cross-product.

Separate Dimensions Before Combining Them

Maintain a small coverage table outside the config. For each dimension, record the behavior it can affect, the tests that exercise that behavior, and the cadence at which it must run. This prevents "mobile" from becoming a vague extra copy of the desktop suite.

For example, an application might need all smoke journeys on three desktop engines, responsive navigation checks on one Chromium mobile descriptor and one WebKit mobile descriptor, and a read-only health journey against production. That is seven purposeful lanes, not three engines multiplied by two devices multiplied by three environments. The distinction matters because each additional project multiplies every matching test.

Playwright's emulation documentation explains that device descriptors include values such as viewport, screen size, user agent, and touch support. A descriptor is a bundle, so spread it first and place explicit overrides afterward. Otherwise, a descriptor can silently replace a viewport or related value declared earlier.

Build an Explicit Project List

An explicit list is easier to review than a clever generator when the matrix is small. The configuration below keeps staging as the main functional environment, adds two narrow mobile projects, and reserves production for tagged synthetic tests.

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

export default defineConfig({
  testDir: "./tests",
  reporter: [["line"], ["html", { open: "never" }]],
  use: {
    trace: "on-first-retry",
    screenshot: "only-on-failure",
    video: "retain-on-failure",
  },
  projects: [
    {
      name: "chromium-desktop-staging",
      use: {
        ...devices["Desktop Chrome"],
        baseURL: "https://staging.example.test",
      },
    },
    {
      name: "firefox-desktop-staging",
      use: {
        ...devices["Desktop Firefox"],
        baseURL: "https://staging.example.test",
      },
    },
    {
      name: "webkit-desktop-staging",
      use: {
        ...devices["Desktop Safari"],
        baseURL: "https://staging.example.test",
      },
    },
    {
      name: "chromium-mobile-staging",
      testMatch: /.*\.mobile\.spec\.ts/,
      use: {
        ...devices["Pixel 5"],
        baseURL: "https://staging.example.test",
      },
    },
    {
      name: "webkit-mobile-staging",
      testMatch: /.*\.mobile\.spec\.ts/,
      use: {
        ...devices["iPhone 12"],
        baseURL: "https://staging.example.test",
      },
    },
    {
      name: "chromium-production-synthetic",
      grep: /@synthetic/,
      retries: 0,
      use: {
        ...devices["Desktop Chrome"],
        baseURL: "https://www.example.test",
      },
    },
  ],
});

The file names and tags are policy, not decoration. A mobile-only file should assert a responsive behavior, while @synthetic should identify a journey proven to be read-only and safe to repeat manually. Review those boundaries like application code.

Keep Shared Options Truly Shared

Global use settings are appropriate for evidence collection, stable timeouts, headers that every target needs, and other invariant behavior. Project-level use should carry the dimensions that define the lane. Copying the same trace, screenshot, and locale settings into every project increases drift and hides the meaningful differences.

Be cautious with shared authentication state. A storage file created against staging may contain cookies whose domain does not match production. A single account used by several projects can also create parallel data collisions. Authentication and data ownership may need project dependencies or worker-scoped fixtures even when browser settings share a common base.

When project definitions become numerous, generate them from typed records, but preserve explicit names and reviewable allowlists. Do not generate combinations from unconstrained arrays. A generator should encode the approved matrix, not make accidental expansion easier.

Filter Execution Without Losing Intent

Playwright runs all configured projects by default, and --project selects a specific one. Local commands should make the intended lane obvious:

npx playwright test tests/checkout.spec.ts --project=chromium-desktop-staging
npx playwright test tests/navigation.mobile.spec.ts --project=webkit-mobile-staging
npx playwright test --project=chromium-production-synthetic

Use CI jobs to separate feedback speed from breadth. A pull request might run Chromium desktop plus a narrow set of engine-sensitive checks. A scheduled pipeline can run the complete supported-browser set. Production synthetics should have their own credentials, alerting, and concurrency controls. This scheduling approach changes cadence, not test meaning: the project remains the stable unit shown in reports.

Avoid relying on a developer to remember exclusions. If a project must never execute destructive tests, encode a dedicated testMatch, testIgnore, or tag filter and add a guard in the tests. Command-line convention alone is too weak for a safety boundary.

Make Reports Explain the Failed Dimension

A matrix only helps when triage can identify what differed. Keep browser, device class, and environment in project names. Attach environment-specific service versions or deployment identifiers through annotations when available, but do not leak secrets. A failure titled only "checkout failed" forces responders to reconstruct configuration from logs; "webkit-mobile-staging" immediately narrows the investigation.

Interpret patterns across projects. Failure in all staging projects suggests shared application or test-data trouble. Failure only in WebKit points toward engine-sensitive behavior. Failure in both mobile projects but no desktop project suggests responsive layout or touch interaction. This comparison is more valuable than treating each red test as an isolated event.

Diagnose Matrix Failure Modes

The most common design failure is uncontrolled multiplication. Runtime jumps, workers compete for the same accounts, and identical failures flood the report. Fix it by returning to distinct risk hypotheses and removing combinations that do not exercise a difference.

A second failure is configuration shadowing. Spreading a device descriptor after setting locale, viewport, or userAgent can overwrite the intended value. Put the descriptor first, overrides second, and add a small configuration review test when those values are business-critical.

Environment confusion is equally costly. A test may create data through a staging API while the page points to production because only baseURL was changed. Resolve all environment endpoints from one typed environment object, and print a non-secret summary at startup. Finally, do not mistake device emulation for hardware certification; keep those claims separate in the test strategy.

Weigh Breadth Against Feedback Time

Running every critical journey on every supported engine provides strong compatibility evidence, but it lengthens feedback and duplicates backend load. Targeted projects are faster and easier to own, but require disciplined classification of engine-sensitive and device-sensitive behavior. There is no permanent optimum: support commitments and defect history should move tests between lanes.

Branded browser channels can validate the browser users actually install, while bundled engines make execution repeatable. Use a branded channel only when that distinction matters to release risk. Similarly, production coverage gives deployment confidence but must trade depth for safety. The right matrix makes these compromises visible instead of hiding them in CI scripts.

Operational Checklist

• Name every project with the dimensions needed during triage.
• Document one failure hypothesis for each browser, device, or environment lane.
• Spread device descriptors before project-specific overrides.
• Keep destructive tests out of production projects by enforced selection rules.
• Allocate isolated accounts or data namespaces to parallel projects.
• Run a narrow matrix on pull requests and broader coverage on a defined cadence.
• Preserve project names in HTML, CI, and merged reports.
• Review runtime, duplicate failures, and unique defects when pruning the matrix.
• Recheck the matrix whenever browser support or deployment topology changes.

Action Plan

Begin with the current support promise and choose one primary desktop project. Add a second engine, a mobile descriptor, or another environment only when you can name the behavior it protects. Encode those lanes explicitly, run each one by name, and confirm the report preserves their identity. After several cycles, use failure history and runtime data to remove duplication or promote high-value lanes. A Playwright project matrix is successful when every execution has a reason and every failure says where to look.