What are Playwright projects and when would you use them?

Projects are Playwright's primary parameterisation primitive. A project bundles:

• use: per-project fixture overrides (browser, viewport, locale, storageState, baseURL, custom fixtures' inputs).
• testMatch / testIgnore: file glob to include/exclude.
• dependencies: other projects that must run first.
• teardown: a project that runs after this one.
• name: identifier used in reports and --project filters.

Use cases beyond cross-browser:

1. Mobile vs desktop separation:

projects: [
  { name: 'desktop', use: { viewport: { width: 1280, height: 800 } } },
  { name: 'mobile',  use: { ...devices['iPhone 14 Pro'] }, testMatch: /\.mobile\./ },
]

2. Smoke vs full:

projects: [
  { name: 'smoke', testMatch: /\.smoke\./, retries: 0 },
  { name: 'full',  testMatch: /^(?!.*\.smoke\.).*\.spec\./, retries: 2 },
]

Run npx playwright test --project=smoke for fast PR feedback; --project=full for nightly.

3. Setup-then-test:

projects: [
  { name: 'setup', testMatch: /\.setup\./ },
  { name: 'tests', dependencies: ['setup'], use: { storageState: 'auth.json' } },
]

4. Per-environment:

projects: [
  { name: 'staging', use: { baseURL: 'https://staging.example.com' } },
  { name: 'prod',    use: { baseURL: 'https://example.com' }, testMatch: /\.prod\./ },
]

5. Cross-browser: the canonical case, already covered.

Why projects beat env-var-driven duplication: each project has its own report section, its own retry/worker config, its own filtering. The runner natively understands the matrix; you don't write CI shell to re-run with different vars.

Limit: too many projects and the report becomes unwieldy. Most teams have 3-7 active projects; more usually means a config that should be split.