# Parallelism within one machine
npx playwright test --workers=4
npx playwright test --workers=50%

# Splitting across CI jobs
npx playwright test --shard=1/4
npx playwright test --shard=2/4

# Merging shard outputs
npx playwright merge-reports ./blob-report
npx playwright merge-reports --reporter=html,json ./blob-report

# Override config for single run
npx playwright test --fully-parallel

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

export default defineConfig({
  // Tests WITHIN a file also run in parallel
  fullyParallel: true,

  // Worker count options:
  // - undefined: auto-detect (half CPU cores)
  // - number: fixed count
  // - string: percentage of cores
  workers: process.env.CI ? '50%' : undefined,
})

// tests/checkout-flow.spec.ts
import {test, expect} from '@playwright/test'

test.describe.configure({mode: 'serial'})

test('add items to cart', async ({page}) => {
  // ...
})

test('complete payment', async ({page}) => {
  // ...
})

# Job 1            Job 2            Job 3            Job 4
--shard=1/4        --shard=2/4      --shard=3/4      --shard=4/4

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

export default defineConfig({
  fullyParallel: true,
  workers: process.env.CI ? '50%' : undefined,

  reporter: process.env.CI ? [['blob'], ['github']] : [['html', {open: 'on-failure'}]],
})

# Merge all blobs into HTML
npx playwright merge-reports --reporter=html ./all-blob-reports

# Multiple formats
npx playwright merge-reports --reporter=html,json,junit ./all-blob-reports

# Custom output location
PLAYWRIGHT_HTML_REPORT=merged-report npx playwright merge-reports --reporter=html ./all-blob-reports

merge-reports:
  if: ${{ !cancelled() }}
  needs: test
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - run: npm ci

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

    - run: npx playwright merge-reports --reporter=html ./all-blob-reports

    - uses: actions/upload-artifact@v4
      with:
        name: playwright-report
        path: playwright-report/
        retention-days: 14

// fixtures.ts
import {test as base} from '@playwright/test'

type WorkerFixtures = {
  dbClient: DatabaseClient
  apiToken: string
}

export const test = base.extend<{}, WorkerFixtures>({
  dbClient: [
    async ({}, use) => {
      const client = await DatabaseClient.connect(process.env.DB_URL!)
      await use(client)
      await client.disconnect()
    },
    {scope: 'worker'},
  ],

  apiToken: [
    async ({}, use, workerInfo) => {
      const res = await fetch(`${process.env.API_URL}/auth`, {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify({
          user: `test-user-${workerInfo.workerIndex}`,
          password: process.env.TEST_PASSWORD,
        }),
      })
      const {token} = await res.json()
      await use(token)
    },
    {scope: 'worker'},
  ],
})

export {expect} from '@playwright/test'

// BAD: Shared user causes race conditions
test('edit settings', async ({page}) => {
  await page.goto('/users/test-user/settings')
  await page.getByLabel('Email').fill('[email protected]')
  await page.getByRole('button', {name: 'Save'}).click()
})

// GOOD: Unique user per test
test('edit settings', async ({page, request}) => {
  const res = await request.post('/api/users', {
    data: {name: `user-${Date.now()}`, email: `${Date.now()}@test.com`},
  })
  const user = await res.json()

  await page.goto(`/users/${user.id}/settings`)
  await page.getByLabel('Email').fill('[email protected]')
  await page.getByRole('button', {name: 'Save'}).click()
  await expect(page.getByLabel('Email')).toHaveValue('[email protected]')

  await request.delete(`/api/users/${user.id}`)
})

import {test, expect} from '@playwright/test'

test('submit order', async ({page}, testInfo) => {
  const orderId = `order-${testInfo.workerIndex}-${Date.now()}`
  await page.goto(`/orders/new?ref=${orderId}`)
  // ...
})

# .github/workflows/playwright.yml
jobs:
  calculate-shards:
    runs-on: ubuntu-latest
    outputs:
      shard-count: ${{ steps.calc.outputs.count }}
      shard-matrix: ${{ steps.calc.outputs.matrix }}
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - id: calc
        run: |
          TEST_COUNT=$(npx playwright test --list --reporter=json 2>/dev/null | node -e "
            const data = require('fs').readFileSync('/dev/stdin', 'utf8');
            const parsed = JSON.parse(data);
            console.log(parsed.suites?.reduce((acc, s) => acc + (s.specs?.length || 0), 0) || 0);
          ")
          # 1 shard per 20 tests, min 1, max 8
          SHARDS=$(( (TEST_COUNT + 19) / 20 ))
          SHARDS=$(( SHARDS > 8 ? 8 : SHARDS ))
          SHARDS=$(( SHARDS < 1 ? 1 : SHARDS ))
          MATRIX="["
          for i in $(seq 1 $SHARDS); do
            [ $i -gt 1 ] && MATRIX+=","
            MATRIX+="\"$i/$SHARDS\""
          done
          MATRIX+="]"
          echo "count=$SHARDS" >> $GITHUB_OUTPUT
          echo "matrix=$MATRIX" >> $GITHUB_OUTPUT

  test:
    needs: calculate-shards
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        shard: ${{ fromJson(needs.calculate-shards.outputs.shard-matrix) }}
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test --shard=${{ matrix.shard }}