Shard tests across parallel jobs in GitHub Actions

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        shard: [1, 2, 3, 4]
    steps:
      # Node 24 action versions. As of 2026-07-14, Playwright's docs still show the Node 20
      # v4/v5 (playwright.dev/docs/test-sharding); these are the current equivalents, same behavior.
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v6
        with:
          node-version: 22
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      # strategy.job-total, not a literal 4: the denominator is the matrix size. Hardcode it
      # and someone shrinks the matrix to [1, 2, 3] one day, the flag still says /4, and a
      # quarter of the suite silently never runs. Green CI, untested code.
      - run: npx playwright test --shard=${{ matrix.shard }}/${{ strategy.job-total }} --reporter=blob

      # Each shard emits its own partial blob report. Keep them all, even when
      # a shard fails, so the merge job below can see why.
      - name: Upload blob report
        if: ${{ !cancelled() }}
        uses: actions/upload-artifact@v7
        with:
          name: blob-report-${{ matrix.shard }}
          path: blob-report
          retention-days: 1

      # OTHER FRAMEWORKS: only the RUN step is portable. The artifact path and the merge job
      # below are Playwright's, and copying them for another runner is how you get a green
      # build with an empty report.
      #
      #   Jest, no merge step; each shard reports on its own:
      #     - run: npx jest --shard=${{ matrix.shard }}/${{ strategy.job-total }}
      #
      #   Vitest, same contract as Playwright but ITS OWN paths. Note the reporter flag: without
      #   it the shards pass, emit no blob, and the merge finds nothing. Vitest writes blobs to a
      #   HIDDEN directory, so the upload also needs `path: .vitest-reports/*` and
      #   `include-hidden-files: true` (upload-artifact defaults that to false and would upload
      #   zero files), and the merge is `npx vitest run --merge-reports`:
      #     - run: npx vitest run --reporter=blob --shard=${{ matrix.shard }}/${{ strategy.job-total }}
      #
      #   pytest-split. Commit a .test_durations file (`pytest --store-durations`), or the groups
      #   are balanced by assumed-average time and the shards skew:
      #     - run: pytest --splits ${{ strategy.job-total }} --group ${{ matrix.shard }}
      #
      #   cargo-nextest >= 0.9.127 (older versions use hash:m/n):
      #     - run: cargo nextest run --partition slice:${{ matrix.shard }}/${{ strategy.job-total }}

  # Playwright only. Without this job the run ends with 4 partial reports
  # instead of one. It runs even if a shard failed, so failures still show up.
  merge-reports:
    if: ${{ !cancelled() }}
    needs: [test]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v6
        with:
          node-version: 22
      - run: npm ci
      - name: Download blob reports
        uses: actions/download-artifact@v7
        with:
          path: all-blob-reports
          pattern: blob-report-*
          merge-multiple: true
      - run: npx playwright merge-reports --reporter html ./all-blob-reports
      - name: Upload HTML report
        uses: actions/upload-artifact@v7
        with:
          name: html-report--attempt-${{ github.run_attempt }}
          path: playwright-report
          retention-days: 14

      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest]
        node-version: [22]
        shardIndex: [1, 2]
        shardTotal: [2]
        shardWeights: ['58:42']

    strategy:
      fail-fast: false
      matrix:
        shard: [1, 2, 3, 4]

      matrix:
        shard: [1, 2, 3, 4, 5, 6, 7, 8]
# ...
      - name: Run Tests
        run: yarn e2e --shard=${{ matrix.shard }}/${{ strategy.job-total }} --workers=4