| | |

Playwright 14 ๐ŸŽญ Projects โ€” Running Chromium, Firefox, and WebKit in one suite

โฑ๏ธ Estimated read: 8 min | |

A Playwright project is a logical group of tests that share a configuration. The projects array in playwright.config.ts defines one entry per browser, viewport, or environment, and the same test file runs once per project. The default scaffold creates three projectsโ€”chromium, firefox, and webkitโ€”and npx playwright test runs all three in parallel . The project is the unit that makes the cross-browser matrix work: the test code does not know which engine it is running on, and the config decides.

This chapter covers the projects array, the devices presets that configure each browser, and the --project flag that selects a subset. The sections that follow walk through the three-engine setup, the per-project overrides, and the dependency graph that orders the setup project before the browsers.

Key point: The projects array defines one entry per browser or configuration, each with a name and a use block; npx playwright test runs every project by default, and --project=chromium runs one, while dependencies orders a setup project before the browsers that need its state.


a. The three-engine setup

The default config from npm init playwright@latest includes the three rendering engines behind the major browsers. devices["Desktop Chrome"] configures Chromium with a desktop viewport, devices["Desktop Firefox"] configures Firefox, and devices["Desktop Safari"] configures WebKit .

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

export default defineConfig({
  projects: [
    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
    { name: "firefox", use: { ...devices["Desktop Firefox"] } },
    { name: "webkit", use: { ...devices["Desktop Safari"] } },
  ],
});

The devices preset is a spread of options that includes the viewport, the userAgent, the deviceScaleFactor, and the isMobile flag. The preset is not the browser itself; it is the configuration the browser runs with. A project that uses devices["iPhone 15"] runs on WebKit with the iPhone’s viewport and user agent .

The same test file runs once per project. A test that page.goto("/") and asserts on a heading runs three times, once for each engine, and the reporter output shows the project name as the prefix: [chromium] โ€บ example.spec.ts:3:1 โ€บ basic test . The prefix is the way the developer knows which engine failed.


b. Per-project overrides and the selection

Each project can override the top-level options. The timeout, retries, testMatch, and use.baseURL are all project-level, and the override applies only to the tests in that project.

projects: [
  {
    name: "smoke",
    testMatch: /.*smoke.spec.ts/,
    retries: 0,
    use: { ...devices["Desktop Chrome"] },
  },
  {
    name: "regression",
    testIgnore: /.*smoke.spec.ts/,
    retries: 2,
    use: { ...devices["Desktop Chrome"] },
  },
],

The testMatch and testIgnore split the suite by file name. The smoke project runs the smoke tests with no retries, and the regression project runs everything else with two retries. The split is the pattern for a CI pipeline that runs the fast suite on every pull request and the full suite on the merge.

The --project flag selects one project. npx playwright test --project=chromium runs only the Chromium project, and --project=chromium --project=firefox runs two. The flag is the development shortcut for running one browser while iterating, and the full run is the CI default .

The --no-deps flag skips the dependency projects. A run with --project=chromium --no-deps runs only the Chromium project, without the setup project that it depends on. The flag is for local iteration when the setup state is already fresh, not for CI .


c. The dependency graph and the setup project

The dependencies array orders the projects. A project that lists setup in its dependencies runs after the setup project, and the setup project’s state is available when the dependent project runs .

projects: [
  { name: "setup", testMatch: /.*\.setup\.ts/ },
  {
    name: "chromium",
    use: { ...devices["Desktop Chrome"], storageState: "playwright/.auth/user.json" },
    dependencies: ["setup"],
  },
  {
    name: "firefox",
    use: { ...devices["Desktop Firefox"], storageState: "playwright/.auth/user.json" },
    dependencies: ["setup"],
  },
],

The setup project runs the login flow and writes the storage state. The chromium and firefox projects depend on it, so they run after the state file exists. The storageState option loads the file, and the test starts authenticated .

The teardown property is the other side of the dependency. A setup project can point at a teardown project, which runs after all the dependent projects finish. The teardown is for the cleanup that must happen onceโ€”deleting temporary files, stopping a mock server, revoking a token .

{
  name: "setup",
  testMatch: /global\.setup\.ts/,
  teardown: "cleanup",
},
{
  name: "cleanup",
  testMatch: /global\.teardown\.ts/,
},

The dependency graph is the mechanism that turns the projects from a flat list into an ordered pipeline. The setup runs first, the browser projects run in parallel after it, and the teardown runs last.


Complete Example Session

// ============================================
// PART 1: THE THREE-ENGINE MATRIX
// ============================================
import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  projects: [
    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
    { name: "firefox", use: { ...devices["Desktop Firefox"] } },
    { name: "webkit", use: { ...devices["Desktop Safari"] } },
  ],
});

// ============================================
// PART 2: THE AUTHENTICATED MATRIX
// ============================================
export default defineConfig({
  projects: [
    { name: "setup", testMatch: /.*\.setup\.ts/ },
    {
      name: "chromium",
      use: { ...devices["Desktop Chrome"], storageState: "playwright/.auth/user.json" },
      dependencies: ["setup"],
    },
    {
      name: "firefox",
      use: { ...devices["Desktop Firefox"], storageState: "playwright/.auth/user.json" },
      dependencies: ["setup"],
    },
    {
      name: "webkit",
      use: { ...devices["Desktop Safari"], storageState: "playwright/.auth/user.json" },
      dependencies: ["setup"],
    },
  ],
});

// ============================================
// PART 3: THE SELECTION
// ============================================
// All projects
// npx playwright test

// One project
// npx playwright test --project=chromium

// Two projects
// npx playwright test --project=chromium --project=firefox

The parts covered the three-engine matrix, the authenticated matrix with the setup dependency, and the selection flags.


Quick Reference

Project Configuration

OptionPurpose
nameProject identifier
useProject-specific options
testMatch / testIgnoreFile selection
dependenciesRun after listed projects
teardownCleanup project
retries / timeoutPer-project overrides

Devices Presets

PresetEngine
devices["Desktop Chrome"]Chromium
devices["Desktop Firefox"]Firefox
devices["Desktop Safari"]WebKit
devices["iPhone 15"]WebKit mobile

Selection Flags

FlagEffect
(none)All projects
--project=chromiumOne project
--project=chromium --project=firefoxTwo projects
--no-depsSkip dependencies

Best Practices

โœ… Do This:

// Use devices presets
use: { ...devices["Desktop Chrome"] }                          // โœ…

// Order the setup project with dependencies
dependencies: ["setup"]                                        // โœ…

// Select one project during development
npx playwright test --project=chromium                         // โœ…

โŒ Don’t Do This:

// Hard-code the browser options
use: { browserName: "chromium", viewport: { width: 1280, height: 720 } } // โŒ

// Forget the dependency for the auth project
use: { storageState: "auth.json" } // without dependencies     // โŒ

// Run all three browsers for every local iteration
npx playwright test // slow for a single change                // โŒ

Common Pitfalls

PitfallWhy It HappensFix
Setup runs after the browsersNo dependenciesAdd the array
Tests run unauthenticatedState file missingAdd dependencies: ["setup"]
One browser fails onlyEngine-specific bugRun --project to isolate
Slow local runsAll three engines--project=chromium

Real-World Examples

1. Three-engine matrix

projects: [
  { name: "chromium", use: { ...devices["Desktop Chrome"] } },
  { name: "firefox", use: { ...devices["Desktop Firefox"] } },
  { name: "webkit", use: { ...devices["Desktop Safari"] } },
]

2. Mobile project

{ name: "mobile", use: { ...devices["iPhone 15"] } }

3. Setup dependency

{ name: "chromium", dependencies: ["setup"] }

4. Teardown project

{ name: "setup", teardown: "cleanup" }

5. File split

{ name: "smoke", testMatch: /.*smoke.spec.ts/ }

6. Ignore pattern

{ name: "regression", testIgnore: /.*smoke.spec.ts/ }

7. Per-project retries

{ name: "smoke", retries: 0 }

8. Select one

npx playwright test --project=chromium

9. Select two

npx playwright test --project=chromium --project=firefox

10. Skip deps

npx playwright test --project=chromium --no-deps

Visual

The Matrix

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚  projects: [                                            โ”‚
โ”‚    { name: "chromium", use: devices["Desktop Chrome"] },โ”‚
โ”‚    { name: "firefox", use: devices["Desktop Firefox"] },โ”‚
โ”‚    { name: "webkit", use: devices["Desktop Safari"] },  โ”‚
โ”‚  ]                                                      โ”‚
โ”‚                                                         โ”‚
โ”‚  The same test file runs three times.                   โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

The Dependency Graph

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚  setup (login, save state)                              โ”‚
โ”‚         โ”‚                                               โ”‚
โ”‚    โ”Œโ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”                                  โ”‚
โ”‚    โ–ผ    โ–ผ            โ–ผ                                  โ”‚
โ”‚  chromium  firefox  webkit                              โ”‚
โ”‚                                                         โ”‚
โ”‚  Each depends on setup; setup runs first.               โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

The Selection

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚  npx playwright test                                    โ”‚
โ”‚    โ†’ chromium, firefox, webkit                          โ”‚
โ”‚                                                         โ”‚
โ”‚  npx playwright test --project=chromium                 โ”‚
โ”‚    โ†’ chromium only (and its dependencies)               โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Summary

ItemValue
Project definitionprojects array
Project optionsname, use, dependencies
Cross-browserThree projects, one per engine
Devices presetsdevices["Desktop Chrome"] etc.
Selection--project=name
Orderingdependencies: ["setup"]
Cleanupteardown: "cleanup"

Key takeaways:

  • A project is a logical group of tests with a shared configuration. The projects array defines one entry per browser, viewport, or environment, and the same test file runs once per project .
  • The devices presets configure the engine. devices["Desktop Chrome"] is Chromium with a desktop viewport, and devices["iPhone 15"] is WebKit with a mobile viewport. The preset is the configuration, not the browser binary .
  • The --project flag selects a subset. The default run is every project, and the flag is the development shortcut for one browser. The --no-deps flag skips the dependency projects for local iteration .
  • dependencies orders the setup before the browsers. The setup project runs the login and saves the state, and the browser projects load the state and start authenticated .
  • teardown is the cleanup after the dependents. The setup project points at a teardown project, which runs after all the dependent projects finish. The pattern is for the cleanup that must happen once .

Remember: The projects are the matrix. The config defines the browsers, the test file does not know which engine it is running on, and the runner executes the same file once per project. Use the devices presets, order the setup with dependencies, and select one project with --project during development. The full matrix is for CI; the single project is for the iteration loop.

Was this helpful?


Stop using slow, ad-bloated tool sites! ๐Ÿคฎ

๐Ÿ”Ž Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
โœ… Finance (Mortgage, Interest, Inflation)
โœ… Tech (Base64, JSON, Dev Suite, IP)
โœ… Health (BMI, BMR, TDEE)
โœ… Productivity (Timer, Workspace, QR)

โšก๏ธ Fast & Private
๐Ÿ”’ No data leaves your device
๐Ÿ’Ž 100% Free

๐Ÿ”— Use it now: https://tools.kandz.me
๐Ÿ”– Bookmark itโ€”youโ€™ll need it later!