1# CI/CD Integration
2 
3## Table of Contents
4 
51. [GitHub Actions](#github-actions)
62. [Docker](#docker)
73. [Reporting](#reporting)
84. [Sharding](#sharding)
95. [Environment Management](#environment-management)
106. [Caching](#caching)
11 
12## GitHub Actions
13 
14### Basic Workflow
15 
16```yaml
17# .github/workflows/playwright.yml
18name: Playwright Tests
19 
20on:
21  push:
22    branches: [main]
23  pull_request:
24    branches: [main]
25 
26jobs:
27  test:
28    timeout-minutes: 60
29    runs-on: ubuntu-latest
30    steps:
31      - uses: actions/checkout@v4
32 
33      - uses: actions/setup-node@v4
34        with:
35          node-version: 22
36          cache: "npm"
37 
38      - name: Install dependencies
39        run: npm ci
40 
41      - name: Install Playwright browsers
42        run: npx playwright install --with-deps
43 
44      - name: Run Playwright tests
45        run: npx playwright test
46 
47      - uses: actions/upload-artifact@v4
48        if: ${{ !cancelled() }}
49        with:
50          name: playwright-report
51          path: playwright-report/
52          retention-days: 30
53```
54 
55### With Sharding
56 
57```yaml
58name: Playwright Tests
59 
60on:
61  push:
62    branches: [main]
63 
64jobs:
65  test:
66    timeout-minutes: 60
67    runs-on: ubuntu-latest
68    strategy:
69      fail-fast: false
70      matrix:
71        shardIndex: [1, 2, 3, 4]
72        shardTotal: [4]
73    steps:
74      - uses: actions/checkout@v4
75 
76      - uses: actions/setup-node@v4
77        with:
78          node-version: 22
79          cache: "npm"
80 
81      - name: Install dependencies
82        run: npm ci
83 
84      - name: Install Playwright browsers
85        run: npx playwright install --with-deps
86 
87      - name: Run Playwright tests
88        run: npx playwright test --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}
89 
90      - name: Upload blob report
91        if: ${{ !cancelled() }}
92        uses: actions/upload-artifact@v4
93        with:
94          name: blob-report-${{ matrix.shardIndex }}
95          path: blob-report
96          retention-days: 1
97 
98  merge-reports:
99    if: ${{ !cancelled() }}
100    needs: [test]
101    runs-on: ubuntu-latest
102    steps:
103      - uses: actions/checkout@v4
104 
105      - uses: actions/setup-node@v4
106        with:
107          node-version: 22
108          cache: "npm"
109 
110      - name: Install dependencies
111        run: npm ci
112 
113      - name: Download blob reports
114        uses: actions/download-artifact@v4
115        with:
116          path: all-blob-reports
117          pattern: blob-report-*
118          merge-multiple: true
119 
120      - name: Merge reports
121        run: npx playwright merge-reports --reporter html ./all-blob-reports
122 
123      - name: Upload HTML report
124        uses: actions/upload-artifact@v4
125        with:
126          name: html-report
127          path: playwright-report
128          retention-days: 14
129```
130 
131### With Container
132 
133```yaml
134jobs:
135  test:
136    timeout-minutes: 60
137    runs-on: ubuntu-latest
138    container:
139      # Use latest or more appropriate playwright version (match package.json)
140      image: mcr.microsoft.com/playwright:v1.40.0-jammy
141    steps:
142      - uses: actions/checkout@v4
143 
144      - uses: actions/setup-node@v4
145        with:
146          node-version: 22
147          cache: "npm"
148 
149      - name: Install dependencies
150        run: npm ci
151 
152      - name: Run tests
153        run: npx playwright test
154        env:
155          HOME: /root
156```
157 
158## Docker
159 
160### Dockerfile
161 
162```dockerfile
163FROM mcr.microsoft.com/playwright:v1.40.0-jammy
164 
165WORKDIR /app
166 
167COPY package*.json ./
168RUN npm ci
169 
170COPY . .
171 
172CMD ["npx", "playwright", "test"]
173```
174 
175### Docker Compose
176 
177```yaml
178# docker-compose.yml
179version: "3.8"
180 
181services:
182  playwright:
183    build: .
184    volumes:
185      - ./playwright-report:/app/playwright-report
186      - ./test-results:/app/test-results
187    environment:
188      - CI=true
189      - BASE_URL=http://app:3000
190    depends_on:
191      - app
192 
193  app:
194    build: ./app
195    ports:
196      - "3000:3000"
197```
198 
199### Run with Docker
200 
201```bash
202# Build and run
203docker build -t playwright-tests .
204docker run --rm -v $(pwd)/playwright-report:/app/playwright-report playwright-tests
205 
206# With docker-compose
207docker-compose run --rm playwright
208```
209 
210## Reporting
211 
212### Configuration
213 
214```typescript
215// playwright.config.ts
216export default defineConfig({
217  reporter: [
218    // Always generate
219    ["html", { outputFolder: "playwright-report" }],
220 
221    // Console output
222    ["list"],
223 
224    // CI-friendly
225    ["github"], // GitHub Actions annotations
226 
227    // JUnit for CI integration
228    ["junit", { outputFile: "results.xml" }],
229 
230    // JSON for custom processing
231    ["json", { outputFile: "results.json" }],
232 
233    // Blob for merging shards
234    ["blob", { outputDir: "blob-report" }],
235  ],
236});
237```
238 
239### CI-Specific Reporter
240 
241```typescript
242export default defineConfig({
243  reporter: process.env.CI
244    ? [["github"], ["blob"], ["html"]]
245    : [["list"], ["html"]],
246});
247```
248 
249## Sharding
250 
251### Command Line
252 
253```bash
254# Split into 4 shards, run shard 1
255npx playwright test --shard=1/4
256 
257# Run shard 2
258npx playwright test --shard=2/4
259```
260 
261### Configuration
262 
263```typescript
264// playwright.config.ts
265export default defineConfig({
266  // Evenly distribute tests across shards
267  fullyParallel: true,
268 
269  // For blob reporter to merge later
270  reporter: process.env.CI ? [["blob"]] : [["html"]],
271});
272```
273 
274### Merge Sharded Reports
275 
276```bash
277# After all shards complete, merge blob reports
278npx playwright merge-reports --reporter html ./all-blob-reports
279```
280 
281## Environment Management
282 
283### Environment Variables
284 
285```typescript
286// playwright.config.ts
287import { defineConfig } from "@playwright/test";
288import dotenv from "dotenv";
289 
290// Load env file based on environment
291dotenv.config({ path: `.env.${process.env.NODE_ENV || "development"}` });
292 
293export default defineConfig({
294  use: {
295    baseURL: process.env.BASE_URL || "http://localhost:3000",
296  },
297});
298```
299 
300### Multiple Environments
301 
302```yaml
303# .github/workflows/playwright.yml
304jobs:
305  test:
306    strategy:
307      matrix:
308        environment: [staging, production]
309    steps:
310      - name: Run tests
311        run: npx playwright test
312        env:
313          BASE_URL: ${{ matrix.environment == 'staging' && 'https://staging.example.com' || 'https://example.com' }}
314          TEST_USER: ${{ secrets[format('TEST_USER_{0}', matrix.environment)] }}
315```
316 
317### Secrets Management
318 
319```yaml
320# GitHub Actions secrets
321- name: Run tests
322  run: npx playwright test
323  env:
324    TEST_EMAIL: ${{ secrets.TEST_EMAIL }}
325    TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }}
326```
327 
328```typescript
329// tests use environment variables
330test("login", async ({ page }) => {
331  await page.getByLabel("Email").fill(process.env.TEST_EMAIL!);
332  await page.getByLabel("Password").fill(process.env.TEST_PASSWORD!);
333});
334```
335 
336## Caching
337 
338### Cache Playwright Browsers
339 
340```yaml
341- name: Cache Playwright browsers
342  uses: actions/cache@v4
343  id: playwright-cache
344  with:
345    path: ~/.cache/ms-playwright
346    key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
347 
348- name: Install Playwright browsers
349  if: steps.playwright-cache.outputs.cache-hit != 'true'
350  run: npx playwright install --with-deps
351 
352- name: Install system deps only
353  if: steps.playwright-cache.outputs.cache-hit == 'true'
354  run: npx playwright install-deps
355```
356 
357### Cache Node Modules
358 
359```yaml
360- uses: actions/setup-node@v4
361  with:
362    node-version: 22
363    cache: "npm"
364 
365- name: Install dependencies
366  run: npm ci
367```
368 
369## Tag-Based Test Filtering
370 
371### Run Specific Tags in CI
372 
373```yaml
374# Run smoke tests on PR
375- name: Run smoke tests
376  run: npx playwright test --grep @smoke
377 
378# Run full regression nightly
379- name: Run regression
380  run: npx playwright test --grep @regression
381 
382# Exclude flaky tests
383- name: Run stable tests
384  run: npx playwright test --grep-invert @flaky
385```
386 
387### PR vs Nightly Strategy
388 
389```yaml
390# .github/workflows/pr.yml - Fast feedback
391- name: Run critical tests
392  run: npx playwright test --grep "@smoke|@critical"
393 
394# .github/workflows/nightly.yml - Full coverage
395- name: Run all tests
396  run: npx playwright test --grep-invert @flaky
397```
398 
399### Tag Filtering in Config
400 
401```typescript
402// playwright.config.ts
403export default defineConfig({
404  grep: process.env.CI ? /@smoke|@critical/ : undefined,
405  grepInvert: process.env.CI ? /@flaky/ : undefined,
406});
407```
408 
409### Project-Based Tag Filtering
410 
411```typescript
412// playwright.config.ts
413export default defineConfig({
414  projects: [
415    {
416      name: "smoke",
417      grep: /@smoke/,
418    },
419    {
420      name: "regression",
421      grepInvert: /@smoke/,
422    },
423  ],
424});
425```
426 
427## Best Practices
428 
429| Practice                      | Benefit                   |
430| ----------------------------- | ------------------------- |
431| Use `npm ci`                  | Deterministic installs    |
432| Run headless in CI            | Faster, no display needed |
433| Set retries in CI only        | Handle flakiness          |
434| Upload artifacts on failure   | Debug failures            |
435| Use sharding for large suites | Faster execution          |
436| Cache browsers                | Faster setup              |
437| Use blob reporter for shards  | Merge reports correctly   |
438| Use tags for PR vs nightly    | Fast feedback + coverage  |
439| Exclude @flaky in CI          | Stable pipeline           |
440 
441## CI Configuration Reference
442 
443```typescript
444// playwright.config.ts - CI optimized
445export default defineConfig({
446  testDir: "./tests",
447  fullyParallel: true,
448  forbidOnly: !!process.env.CI,
449  retries: process.env.CI ? 2 : 0,
450  workers: process.env.CI ? 1 : undefined,
451  reporter: process.env.CI
452    ? [["github"], ["blob"], ["html"]]
453    : [["list"], ["html"]],
454  use: {
455    baseURL: process.env.BASE_URL || "http://localhost:3000",
456    trace: "on-first-retry",
457    screenshot: "only-on-failure",
458    video: "on-first-retry",
459  },
460});
461```
462 
463## Related References
464 
465- **Test tags**: See [test-tags.md](../core/test-tags.md) for tagging and filtering patterns
466- **Performance optimization**: See [performance.md](performance.md) for sharding and parallelization
467- **Debugging CI failures**: See [debugging.md](../debugging/debugging.md) for troubleshooting
468- **Test reporting**: See [debugging.md](../debugging/debugging.md) for trace viewer usage
469