Sharding and Projects in CI Pipelines

In CI pipelines, you often need to split large Playwright suites across multiple jobs to keep runtime acceptable. Playwright supports projects and sharding so you can control which tests run where without duplicating configuration.

Using Projects and Sharding in CI #

Projects let you define different configurations (such as browsers or devices) under a single suite. Sharding allows you to run a subset of tests on each CI job, identified by shard index and total shard count.

// playwright.config.ts (snippet for projects)
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  projects: [
    {
      name: 'Chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'Firefox',
      use: { ...devices['Desktop Firefox'] },
    },
  ],
});

# Example CI commands for sharding a suite into 3 parts
# Job 1
npx playwright test --shard=1/3
# Job 2
npx playwright test --shard=2/3
# Job 3
npx playwright test --shard=3/3

Combining projects with sharding lets you scale horizontally across CI runners without overcomplicating your Playwright configuration.

Common Mistakes #

Mistake 1 — Hard-coding different configs per CI job #

This is hard to maintain.

❌ Wrong: Maintaining separate config files for each shard or browser combination.

✅ Correct: Use a single config with projects and drive sharding from CI parameters.

Mistake 2 — Ignoring failed shards in CI #

This hides problems.

❌ Wrong: Treating partial green builds as success when one shard fails.

✅ Correct: Configure CI so that any shard failure marks the pipeline as failed.