CI, Sharding, and the Blob-Merge Pattern

# .github/workflows/playwright.yml — sharded + merged
name: Playwright Tests
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    timeout-minutes: 30
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false       # let all shards finish even if one fails
      matrix:
        shard: [1, 2, 3]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: lts/*
      - name: Install dependencies
        run: npm ci
      - name: Install Playwright browsers
        run: npx playwright install --with-deps

      - name: Run shard ${{ matrix.shard }}/3
        run: npx playwright test --shard=${{ matrix.shard }}/3 --reporter=blob

      - name: Upload blob report
        uses: actions/upload-artifact@v4
        if: ${{ !cancelled() }}
        with:
          name: blob-report-${{ matrix.shard }}
          path: blob-report
          retention-days: 7

  merge:
    needs: [test]
    if: ${{ !cancelled() }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: lts/*
      - run: npm ci

      - name: Download all blob reports
        uses: actions/download-artifact@v4
        with:
          path: all-blob-reports
          pattern: blob-report-*
          merge-multiple: true

      - name: Merge into one HTML report
        run: npx playwright merge-reports --reporter=html ./all-blob-reports

      - name: Upload merged HTML report
        uses: actions/upload-artifact@v4
        with:
          name: playwright-report
          path: playwright-report
          retention-days: 30

// playwright.config.ts — environment-aware
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './e2e',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,         // fail CI if .only slips through
  workers: process.env.CI ? 1 : '50%',  // 1 per shard in CI
  retries: process.env.CI ? 2 : 0,      // catch network jitter, not flakes

  reporter: process.env.CI
    ? [['blob']]                        // blob for sharding + merging
    : [['html', { open: 'never' }]],    // browseable locally

  use: {
    baseURL: process.env.BASE_URL ?? 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
  },

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

# Local — single process, watchable
npx playwright test

# Local — simulate sharding for debugging
npx playwright test --shard=1/3   # run only the first shard locally
npx playwright test --shard=2/3
npx playwright test --shard=3/3

# Local — merge the blobs you produced into one HTML report
npx playwright merge-reports --reporter=html ./blob-report-1 ./blob-report-2 ./blob-report-3

# CI — uses the shard arg from the matrix
npx playwright test --shard=${SHARD}/${TOTAL_SHARDS} --reporter=blob

# Workflow result you should see in the GitHub Actions UI

┌──────────────┐
│ test (1/3)   │ Running shard 1 of 3 ............ 9m 42s ✅
├──────────────┤
│ test (2/3)   │ Running shard 2 of 3 ............ 9m 18s ✅
├──────────────┤
│ test (3/3)   │ Running shard 3 of 3 ............10m 04s ✅
└──────────────┘
          │
          ▼
┌──────────────┐
│ merge        │ Downloading 3 blobs, merging .... 0m 47s ✅
└──────────────┘

Total wall time: ~11 minutes  (vs ~30 minutes serial)
Artifacts: playwright-report (browseable HTML), blob-report-{1,2,3}

Click the failing test in the merged report → click 'Trace' → time-travel through the failure.