Playwright 14 ๐ญ Projects โ Running Chromium, Firefox, and WebKit in one suite
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
| Option | Purpose |
|---|---|
name | Project identifier |
use | Project-specific options |
testMatch / testIgnore | File selection |
dependencies | Run after listed projects |
teardown | Cleanup project |
retries / timeout | Per-project overrides |
Devices Presets
| Preset | Engine |
|---|---|
devices["Desktop Chrome"] | Chromium |
devices["Desktop Firefox"] | Firefox |
devices["Desktop Safari"] | WebKit |
devices["iPhone 15"] | WebKit mobile |
Selection Flags
| Flag | Effect |
|---|---|
| (none) | All projects |
--project=chromium | One project |
--project=chromium --project=firefox | Two projects |
--no-deps | Skip 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
| Pitfall | Why It Happens | Fix |
|---|---|---|
| Setup runs after the browsers | No dependencies | Add the array |
| Tests run unauthenticated | State file missing | Add dependencies: ["setup"] |
| One browser fails only | Engine-specific bug | Run --project to isolate |
| Slow local runs | All 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
| Item | Value |
|---|---|
| Project definition | projects array |
| Project options | name, use, dependencies |
| Cross-browser | Three projects, one per engine |
| Devices presets | devices["Desktop Chrome"] etc. |
| Selection | --project=name |
| Ordering | dependencies: ["setup"] |
| Cleanup | teardown: "cleanup" |
Key takeaways:
- A project is a logical group of tests with a shared configuration. The
projectsarray defines one entry per browser, viewport, or environment, and the same test file runs once per project . - The
devicespresets configure the engine.devices["Desktop Chrome"]is Chromium with a desktop viewport, anddevices["iPhone 15"]is WebKit with a mobile viewport. The preset is the configuration, not the browser binary . - The
--projectflag selects a subset. The default run is every project, and the flag is the development shortcut for one browser. The--no-depsflag skips the dependency projects for local iteration . dependenciesorders 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 .teardownis 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.
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!