1# GitHub Actions for Playwright
2 
3## Table of Contents
4 
51. [CLI Commands](#cli-commands)
62. [Workflow Patterns](#workflow-patterns)
73. [Scenario Guide](#scenario-guide)
84. [Common Mistakes](#common-mistakes)
95. [Troubleshooting](#troubleshooting)
106. [Related](#related)
11 
12> **When to use**: Automating Playwright tests on pull requests, main branch merges, or scheduled runs.
13 
14## CLI Commands
15 
16```bash
17npx playwright install --with-deps    # browsers + OS dependencies
18npx playwright test --shard=1/4       # run shard 1 of 4
19npx playwright test --reporter=github # PR annotations
20npx playwright merge-reports ./blob-report  # combine shard reports
21```
22 
23## Workflow Patterns
24 
25### Basic Workflow
26 
27**Use when**: Starting a new project or running a small test suite.
28 
29```yaml
30# .github/workflows/e2e.yml
31name: E2E Tests
32 
33on:
34  push:
35    branches: [main]
36  pull_request:
37    branches: [main]
38 
39concurrency:
40  group: e2e-${{ github.ref }}
41  cancel-in-progress: true
42 
43env:
44  CI: true
45 
46jobs:
47  test:
48    timeout-minutes: 30
49    runs-on: ubuntu-latest
50 
51    steps:
52      - uses: actions/checkout@v4
53 
54      - run: npm ci
55 
56      - name: Cache browsers
57        id: browser-cache
58        uses: actions/cache@v4
59        with:
60          path: ~/.cache/ms-playwright
61          key: pw-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
62 
63      - name: Install browsers
64        if: steps.browser-cache.outputs.cache-hit != 'true'
65        run: npx playwright install --with-deps
66 
67      - name: Install OS dependencies
68        if: steps.browser-cache.outputs.cache-hit == 'true'
69        run: npx playwright install-deps
70 
71      - run: npx playwright test
72 
73      - name: Upload report
74        uses: actions/upload-artifact@v4
75        if: ${{ !cancelled() }}
76        with:
77          name: test-report
78          path: playwright-report/
79          retention-days: 14
80 
81      - name: Upload traces
82        uses: actions/upload-artifact@v4
83        if: failure()
84        with:
85          name: traces
86          path: test-results/
87          retention-days: 7
88```
89 
90### Sharded Execution
91 
92**Use when**: Test suite exceeds 10 minutes. Sharding cuts wall-clock time significantly.
93**Avoid when**: Suite runs under 5 minutes—sharding overhead negates benefits.
94 
95```yaml
96# .github/workflows/e2e-sharded.yml
97name: E2E Tests (Sharded)
98 
99on:
100  push:
101    branches: [main]
102  pull_request:
103    branches: [main]
104 
105concurrency:
106  group: e2e-${{ github.ref }}
107  cancel-in-progress: true
108 
109env:
110  CI: true
111 
112jobs:
113  test:
114    timeout-minutes: 20
115    runs-on: ubuntu-latest
116    strategy:
117      fail-fast: false
118      matrix:
119        shard: [1/4, 2/4, 3/4, 4/4]
120 
121    steps:
122      - uses: actions/checkout@v4
123 
124      - run: npm ci
125 
126      - name: Cache browsers
127        id: browser-cache
128        uses: actions/cache@v4
129        with:
130          path: ~/.cache/ms-playwright
131          key: pw-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
132 
133      - name: Install browsers
134        if: steps.browser-cache.outputs.cache-hit != 'true'
135        run: npx playwright install --with-deps
136 
137      - name: Install OS dependencies
138        if: steps.browser-cache.outputs.cache-hit == 'true'
139        run: npx playwright install-deps
140 
141      - name: Run tests (shard ${{ matrix.shard }})
142        run: npx playwright test --shard=${{ matrix.shard }}
143 
144      - name: Upload blob report
145        uses: actions/upload-artifact@v4
146        if: ${{ !cancelled() }}
147        with:
148          name: blob-${{ strategy.job-index }}
149          path: blob-report/
150          retention-days: 1
151 
152  merge:
153    if: ${{ !cancelled() }}
154    needs: test
155    runs-on: ubuntu-latest
156 
157    steps:
158      - uses: actions/checkout@v4
159 
160      - run: npm ci
161 
162      - name: Download blob reports
163        uses: actions/download-artifact@v4
164        with:
165          path: all-blobs
166          pattern: blob-*
167          merge-multiple: true
168 
169      - name: Merge reports
170        run: npx playwright merge-reports --reporter=html ./all-blobs
171 
172      - name: Upload merged report
173        uses: actions/upload-artifact@v4
174        with:
175          name: test-report
176          path: playwright-report/
177          retention-days: 14
178```
179 
180**Config for sharding**—enable blob reporter:
181 
182```typescript
183// playwright.config.ts
184import { defineConfig } from '@playwright/test';
185 
186export default defineConfig({
187  reporter: process.env.CI
188    ? [['blob'], ['github']]
189    : [['html', { open: 'on-failure' }]],
190});
191```
192 
193### Container-Based Execution
194 
195**Use when**: Reproducible environment matching local Docker setup, or runner OS dependencies cause issues.
196**Avoid when**: Standard `ubuntu-latest` with `--with-deps` works fine.
197 
198```yaml
199# .github/workflows/e2e-container.yml
200name: E2E Tests (Container)
201 
202on:
203  pull_request:
204    branches: [main]
205 
206jobs:
207  test:
208    timeout-minutes: 30
209    runs-on: ubuntu-latest
210    container:
211      image: mcr.microsoft.com/playwright:v1.48.0-noble
212 
213    steps:
214      - uses: actions/checkout@v4
215 
216      - run: npm ci
217 
218      - name: Run tests
219        run: npx playwright test
220        env:
221          HOME: /root
222 
223      - uses: actions/upload-artifact@v4
224        if: ${{ !cancelled() }}
225        with:
226          name: test-report
227          path: playwright-report/
228          retention-days: 14
229```
230 
231### Environment Secrets
232 
233**Use when**: Tests target staging/production with credentials.
234**Avoid when**: Tests only run against local dev server.
235 
236```yaml
237# .github/workflows/e2e-staging.yml
238name: Staging Tests
239 
240on:
241  push:
242    branches: [main]
243  workflow_dispatch:
244 
245jobs:
246  test:
247    timeout-minutes: 30
248    runs-on: ubuntu-latest
249    environment: staging
250 
251    env:
252      CI: true
253      BASE_URL: ${{ vars.STAGING_URL }}
254      TEST_USER_PASSWORD: ${{ secrets.TEST_USER_PASSWORD }}
255      API_TOKEN: ${{ secrets.API_TOKEN }}
256 
257    steps:
258      - uses: actions/checkout@v4
259 
260      - run: npm ci
261 
262      - name: Cache browsers
263        id: browser-cache
264        uses: actions/cache@v4
265        with:
266          path: ~/.cache/ms-playwright
267          key: pw-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
268 
269      - name: Install browsers
270        if: steps.browser-cache.outputs.cache-hit != 'true'
271        run: npx playwright install --with-deps
272 
273      - name: Install OS dependencies
274        if: steps.browser-cache.outputs.cache-hit == 'true'
275        run: npx playwright install-deps
276 
277      - name: Run smoke tests
278        run: npx playwright test --grep @smoke
279 
280      - uses: actions/upload-artifact@v4
281        if: ${{ !cancelled() }}
282        with:
283          name: staging-report
284          path: playwright-report/
285          retention-days: 14
286```
287 
288### Scheduled Runs
289 
290**Use when**: Full regression suite is too slow for every PR—run nightly instead.
291**Avoid when**: Suite runs under 15 minutes and can run on every PR.
292 
293```yaml
294# .github/workflows/nightly.yml
295name: Nightly Regression
296 
297on:
298  schedule:
299    - cron: '0 3 * * 1-5'
300  workflow_dispatch:
301 
302jobs:
303  test:
304    timeout-minutes: 60
305    runs-on: ubuntu-latest
306 
307    env:
308      CI: true
309      BASE_URL: ${{ vars.STAGING_URL }}
310 
311    steps:
312      - uses: actions/checkout@v4
313 
314      - run: npm ci
315 
316      - name: Install browsers
317        run: npx playwright install --with-deps
318 
319      - name: Run full regression
320        run: npx playwright test --grep @regression
321 
322      - uses: actions/upload-artifact@v4
323        if: ${{ !cancelled() }}
324        with:
325          name: nightly-${{ github.run_number }}
326          path: playwright-report/
327          retention-days: 30
328 
329      - name: Notify on failure
330        if: failure()
331        uses: slackapi/slack-github-action@latest
332        with:
333          payload: |
334            {
335              "text": "Nightly regression failed: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
336            }
337        env:
338          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
339```
340 
341### Reusable Workflow
342 
343**Use when**: Multiple repositories share the same Playwright setup.
344**Avoid when**: Single repo with one workflow.
345 
346```yaml
347# .github/workflows/pw-reusable.yml
348name: Playwright Reusable
349 
350on:
351  workflow_call:
352    inputs:
353      node-version:
354        type: string
355        default: 'lts/*'
356      test-command:
357        type: string
358        default: 'npx playwright test'
359    secrets:
360      BASE_URL:
361        required: false
362      TEST_PASSWORD:
363        required: false
364 
365jobs:
366  test:
367    timeout-minutes: 30
368    runs-on: ubuntu-latest
369 
370    env:
371      CI: true
372      BASE_URL: ${{ secrets.BASE_URL }}
373      TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }}
374 
375    steps:
376      - uses: actions/checkout@v4
377 
378      - uses: actions/setup-node@v4
379        with:
380          node-version: ${{ inputs.node-version }}
381          cache: npm
382 
383      - run: npm ci
384 
385      - name: Cache browsers
386        id: browser-cache
387        uses: actions/cache@v4
388        with:
389          path: ~/.cache/ms-playwright
390          key: pw-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
391 
392      - name: Install browsers
393        if: steps.browser-cache.outputs.cache-hit != 'true'
394        run: npx playwright install --with-deps
395 
396      - name: Install OS dependencies
397        if: steps.browser-cache.outputs.cache-hit == 'true'
398        run: npx playwright install-deps
399 
400      - name: Run tests
401        run: ${{ inputs.test-command }}
402 
403      - uses: actions/upload-artifact@v4
404        if: ${{ !cancelled() }}
405        with:
406          name: test-report
407          path: playwright-report/
408          retention-days: 14
409```
410 
411**Calling the reusable workflow:**
412 
413```yaml
414# .github/workflows/ci.yml
415name: CI
416on:
417  pull_request:
418    branches: [main]
419 
420jobs:
421  e2e:
422    uses: ./.github/workflows/pw-reusable.yml
423    with:
424      node-version: 'lts/*'
425    secrets:
426      BASE_URL: ${{ secrets.STAGING_URL }}
427      TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }}
428```
429 
430## Scenario Guide
431 
432| Scenario | Approach |
433|---|---|
434| Small suite (< 5 min) | Single job, no sharding |
435| Medium suite (5-20 min) | 2-4 shards with matrix |
436| Large suite (20+ min) | 4-8 shards + blob merge |
437| Cross-browser on PRs | Chromium only on PRs; all browsers on main |
438| Staging/prod smoke tests | Separate workflow with `environment:` |
439| Nightly full regression | `schedule` trigger + `workflow_dispatch` |
440| Multiple repos, same setup | Reusable workflow with `workflow_call` |
441| Reproducible env needed | Container job with Playwright image |
442 
443## Common Mistakes
444 
445| Mistake | Problem | Fix |
446|---|---|---|
447| No `concurrency` group | Duplicate runs waste minutes | Add `concurrency: { group: ..., cancel-in-progress: true }` |
448| `fail-fast: true` with sharding | One failure cancels others | Set `fail-fast: false` |
449| No browser caching | 60-90 seconds wasted per run | Cache `~/.cache/ms-playwright` |
450| No `timeout-minutes` | Stuck jobs run for 6 hours | Set explicit timeout: 20-30 minutes |
451| Artifacts only on failure | No report when tests pass | Use `if: ${{ !cancelled() }}` |
452| Hardcoded secrets | Security risk | Use GitHub Secrets and Environments |
453| All browsers on every PR | 3x CI cost | Chromium on PR; cross-browser on main |
454| No artifact retention | Default 90-day fills storage | Set `retention-days: 7-14` |
455| Missing `--with-deps` | Browser launch failures | Always use `npx playwright install --with-deps` |
456 
457## Troubleshooting
458 
459### Browser launch fails: "Missing dependencies"
460 
461**Cause**: Browsers restored from cache but OS dependencies weren't cached.
462 
463**Fix**: Run `npx playwright install-deps` on cache hit:
464 
465```yaml
466- name: Install OS dependencies
467  if: steps.browser-cache.outputs.cache-hit == 'true'
468  run: npx playwright install-deps
469```
470 
471### Tests pass locally but timeout in CI
472 
473**Cause**: CI runners have fewer resources than dev machines.
474 
475**Fix**: Reduce workers and increase timeouts:
476 
477```typescript
478// playwright.config.ts
479import { defineConfig } from '@playwright/test';
480 
481export default defineConfig({
482  workers: process.env.CI ? '50%' : undefined,
483  use: {
484    actionTimeout: process.env.CI ? 15_000 : 10_000,
485    navigationTimeout: process.env.CI ? 30_000 : 15_000,
486  },
487});
488```
489 
490### Sharded reports incomplete
491 
492**Cause**: Artifact names collide or `merge-multiple` not set.
493 
494**Fix**: Unique names per shard and enable merge:
495 
496```yaml
497# Upload in each shard
498- uses: actions/upload-artifact@v4
499  with:
500    name: blob-${{ strategy.job-index }}
501    path: blob-report/
502 
503# Download in merge job
504- uses: actions/download-artifact@v4
505  with:
506    path: all-blobs
507    pattern: blob-*
508    merge-multiple: true
509```
510 
511### `webServer` fails: "port already in use"
512 
513**Cause**: Zombie process from previous run.
514 
515**Fix**: Kill stale processes before starting:
516 
517```yaml
518- name: Kill stale processes
519  run: lsof -ti:3000 | xargs kill -9 2>/dev/null || true
520```
521 
522### No PR annotations
523 
524**Cause**: `github` reporter not configured.
525 
526**Fix**: Add `github` reporter for CI:
527 
528```typescript
529// playwright.config.ts
530import { defineConfig } from '@playwright/test';
531 
532export default defineConfig({
533  reporter: process.env.CI
534    ? [['html', { open: 'never' }], ['github']]
535    : [['html', { open: 'on-failure' }]],
536});
537```
538 
539## Related
540 
541- [test-tags.md](../core/test-tags.md) — tagging and filtering tests
542- [parallel-sharding.md](parallel-sharding.md) — sharding strategies
543- [reporting.md](reporting.md) — reporter configuration
544- [docker.md](docker.md) — container images
545- [gitlab.md](gitlab.md) — GitLab CI equivalent
546- [other-providers.md](other-providers.md) — CircleCI, Azure DevOps, Jenkins
547