Parallel Execution

npx playwright test
# => Executes tests sequentially
# => One test file after another
# => No parallelization
# => Single worker process
# => Total time: sum of all test durations

// tests/login.spec.ts
import { test, expect } from "@playwright/test";

test("user logs in successfully", async ({ page }) => {
  // => Test 1 starts
  // => No other tests running
  // => Browser context created for this test only

  console.log(`Test started at ${new Date().toISOString()}`);
  // => Log start time
  // => Example: "Test started at 2024-01-15T10:00:00.000Z"

  await page.goto("https://example.com/login");
  await page.fill('input[name="username"]', "user");
  await page.fill('input[name="password"]', "pass");
  await page.click('button[type="submit"]');
  // => Test steps execute
  // => Takes 5 seconds total

  console.log(`Test finished at ${new Date().toISOString()}`);
  // => Log finish time
  // => Example: "Test finished at 2024-01-15T10:00:05.000Z"
  // => 5 seconds elapsed
});

test("user logs out successfully", async ({ page }) => {
  // => Test 2 starts AFTER test 1 finishes
  // => Waits for previous test completion
  // => Sequential execution

  console.log(`Test started at ${new Date().toISOString()}`);
  // => Example: "Test started at 2024-01-15T10:00:05.000Z"
  // => Starts immediately after previous test
  // => No parallelization

  // Test continues...
  // => Takes another 5 seconds
  // => Total time now: 10 seconds
});

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

export default defineConfig({
  workers: process.env.CI ? 2 : undefined,
  // => Set worker count
  // => CI: 2 workers (controlled parallelism)
  // => Local: undefined = auto-detect CPU cores
  // => Auto-detect uses all available cores
  // => Example: 8-core machine = 8 workers

  fullyParallel: true,
  // => Enable full parallelization
  // => Tests in same file run in parallel
  // => Without this: tests within file run sequentially
  // => With this: maximum parallelization

  maxFailures: process.env.CI ? 10 : undefined,
  // => Stop after 10 failures in CI
  // => Prevents wasting CI time on broken builds
  // => undefined in local = run all tests regardless

  retries: process.env.CI ? 2 : 0,
  // => Retry flaky tests 2 times in CI
  // => 0 retries locally for fast feedback
  // => Helps mitigate intermittent failures
});

npx playwright test --workers=4
# => Override config, use 4 workers
# => 4 test files run simultaneously
# => Each worker has own browser process
# => Total time reduced by ~4x (ideally)
# => Example: 20 minutes → 5 minutes

npx playwright test --workers=50%
# => Use 50% of CPU cores
# => 8-core machine = 4 workers
# => Leaves resources for other processes
# => Good for shared CI runners

# .github/workflows/playwright-sharded.yml
name: Playwright Tests (Sharded)
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      # => Don't cancel other shards if one fails
      # => Get full test results from all shards

      matrix:
        shard: [1, 2, 3, 4]
        # => 4 parallel CI jobs (shards)
        # => Each shard runs subset of tests
        # => Tests distributed evenly across shards

    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18

      - name: Install dependencies
        run: npm ci

      - name: Install Playwright browsers
        run: npx playwright install --with-deps

      - name: Run tests (shard ${{ matrix.shard }}/4)
        run: npx playwright test --shard=${{ matrix.shard }}/4
        # => --shard=1/4: Run shard 1 of 4 total shards
        # => Playwright divides tests into 4 groups
        # => Each shard gets ~25% of total tests
        # => Example: 100 tests → each shard runs 25 tests
        # => All 4 shards run simultaneously on separate runners

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: playwright-report-${{ matrix.shard }}
          path: playwright-report/
        # => Upload results from this shard
        # => Separate artifacts per shard
        # => Combine later for full report

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

const cpuCount = os.cpus().length;
// => Get CPU core count
// => Example: 8-core machine returns 8

const workerCount = process.env.CI
  ? 2 // CI: controlled parallelism
  : Math.max(1, Math.floor(cpuCount / 2));
// => Local: use half of cores
// => Leaves resources for browser processes
// => Example: 8 cores → 4 workers

export default defineConfig({
  workers: workerCount,
  // => Dynamic worker allocation
  // => Adapts to machine capabilities
  // => Prevents resource exhaustion

  use: {
    trace: process.env.CI ? "on-first-retry" : "off",
    // => Trace only on retry in CI
    // => Reduces artifact size
    // => Full traces consume significant storage
  },
});

// fixtures/worker-scoped.fixture.ts
import { test as base } from "@playwright/test";

type WorkerFixtures = {
  workerDatabase: Database;
  // => Worker-scoped fixture
  // => Shared across all tests in this worker
  // => Created once per worker
  // => Reused for all tests in worker
};

export const test = base.extend<{}, WorkerFixtures>({
  workerDatabase: [
    async ({}, use, workerInfo) => {
      // => workerInfo provides worker metadata
      // => workerInfo.workerIndex: worker number (0, 1, 2, ...)

      const dbName = `test_db_worker_${workerInfo.workerIndex}`;
      // => Unique database per worker
      // => Example: test_db_worker_0, test_db_worker_1
      // => Prevents worker contention

      const db = await createDatabase(dbName);
      // => Create worker-specific database
      // => Only created once per worker
      // => Shared across all tests in this worker

      await use(db);
      // => Provide database to all tests in worker
      // => Tests in this worker share this db instance

      await db.close();
      // => Cleanup after all worker tests complete
      // => Database closed once per worker
    },
    { scope: "worker" },
    // => scope: 'worker' declares worker-level fixture
    // => Created once per worker, not per test
    // => Improves performance (avoids per-test setup)
  ],
});

// tests/parallel-safe.spec.ts
import { test, expect } from "@playwright/test";

test("test 1 creates user", async ({ page }) => {
  // => Worker 1 runs this test
  // => Has own browser context
  // => Isolated from other workers

  const username = `user_${Date.now()}_${Math.random()}`;
  // => Unique username
  // => Prevents conflicts with parallel tests
  // => Example: user_1640000000000_0.123456

  await page.goto("https://example.com/register");
  await page.fill('input[name="username"]', username);
  // => Uses unique data
  // => No collision with test 2 running in parallel
});

test("test 2 creates user", async ({ page }) => {
  // => Worker 2 runs this test simultaneously
  // => Separate browser context from test 1
  // => Own data namespace

  const username = `user_${Date.now()}_${Math.random()}`;
  // => Different username than test 1
  // => Random component ensures uniqueness
  // => Tests don't interfere
});

// playwright.config.ts
const workers = process.env.CI
  ? 2 // CI: limited resources
  : Math.max(1, os.cpus().length - 1); // Local: all cores minus 1

export default defineConfig({ workers });

// tests/auth-group.spec.ts
test.describe.configure({ mode: "serial" });
// => Tests in this describe run sequentially
// => Share expensive auth setup
// => Still parallel with other describe blocks

test.describe("authenticated user", () => {
  test("views profile", async ({ page }) => {
    /* ... */
  });
  test("edits profile", async ({ page }) => {
    /* ... */
  });
  // Both tests share auth state (serial within describe)
});

// Use worker fixtures for database connections
// See worker-scoped fixture example above

// tests/report-shard-info.ts
test.afterEach(async ({}, testInfo) => {
  console.log(`Worker: ${testInfo.workerIndex}, Duration: ${testInfo.duration}`);
  // => Log worker and duration
  // => Identify slow tests
  // => Optimize bottlenecks
});