stably 4.9.0 → 4.10.0

package/dist/stably-plugin/skills/playwright-best-practices/references/ci-cd.md

@@ -1,407 +0,0 @@
-# CI/CD Integration
-
-## Table of Contents
-
-1. [GitHub Actions](#github-actions)
-2. [Docker](#docker)
-3. [Reporting](#reporting)
-4. [Sharding](#sharding)
-5. [Environment Management](#environment-management)
-6. [Caching](#caching)
-
-## GitHub Actions
-
-### Basic Workflow
-
-```yaml
-# .github/workflows/playwright.yml
-name: Playwright Tests
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-jobs:
-  test:
-    timeout-minutes: 60
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: "npm"
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Install Playwright browsers
-        run: npx playwright install --with-deps
-
-      - name: Run Playwright tests
-        run: npx playwright test
-
-      - uses: actions/upload-artifact@v4
-        if: ${{ !cancelled() }}
-        with:
-          name: playwright-report
-          path: playwright-report/
-          retention-days: 30
-```
-
-### With Sharding
-
-```yaml
-name: Playwright Tests
-
-on:
-  push:
-    branches: [main]
-
-jobs:
-  test:
-    timeout-minutes: 60
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        shardIndex: [1, 2, 3, 4]
-        shardTotal: [4]
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: "npm"
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Install Playwright browsers
-        run: npx playwright install --with-deps
-
-      - name: Run Playwright tests
-        run: npx playwright test --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}
-
-      - name: Upload blob report
-        if: ${{ !cancelled() }}
-        uses: actions/upload-artifact@v4
-        with:
-          name: blob-report-${{ matrix.shardIndex }}
-          path: blob-report
-          retention-days: 1
-
-  merge-reports:
-    if: ${{ !cancelled() }}
-    needs: [test]
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: "npm"
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Download blob reports
-        uses: actions/download-artifact@v4
-        with:
-          path: all-blob-reports
-          pattern: blob-report-*
-          merge-multiple: true
-
-      - name: Merge reports
-        run: npx playwright merge-reports --reporter html ./all-blob-reports
-
-      - name: Upload HTML report
-        uses: actions/upload-artifact@v4
-        with:
-          name: html-report
-          path: playwright-report
-          retention-days: 14
-```
-
-### With Container
-
-```yaml
-jobs:
-  test:
-    timeout-minutes: 60
-    runs-on: ubuntu-latest
-    container:
-      # Use latest or more appropriate playwright version (match package.json)
-      image: mcr.microsoft.com/playwright:v1.40.0-jammy
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: "npm"
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Run tests
-        run: npx playwright test
-        env:
-          HOME: /root
-```
-
-## Docker
-
-### Dockerfile
-
-```dockerfile
-FROM mcr.microsoft.com/playwright:v1.40.0-jammy
-
-WORKDIR /app
-
-COPY package*.json ./
-RUN npm ci
-
-COPY . .
-
-CMD ["npx", "playwright", "test"]
-```
-
-### Docker Compose
-
-```yaml
-# docker-compose.yml
-version: "3.8"
-
-services:
-  playwright:
-    build: .
-    volumes:
-      - ./playwright-report:/app/playwright-report
-      - ./test-results:/app/test-results
-    environment:
-      - CI=true
-      - BASE_URL=http://app:3000
-    depends_on:
-      - app
-
-  app:
-    build: ./app
-    ports:
-      - "3000:3000"
-```
-
-### Run with Docker
-
-```bash
-# Build and run
-docker build -t playwright-tests .
-docker run --rm -v $(pwd)/playwright-report:/app/playwright-report playwright-tests
-
-# With docker-compose
-docker-compose run --rm playwright
-```
-
-## Reporting
-
-### Configuration
-
-```typescript
-// playwright.config.ts
-export default defineConfig({
-  reporter: [
-    // Always generate
-    ["html", { outputFolder: "playwright-report" }],
-
-    // Console output
-    ["list"],
-
-    // CI-friendly
-    ["github"], // GitHub Actions annotations
-
-    // JUnit for CI integration
-    ["junit", { outputFile: "results.xml" }],
-
-    // JSON for custom processing
-    ["json", { outputFile: "results.json" }],
-
-    // Blob for merging shards
-    ["blob", { outputDir: "blob-report" }],
-  ],
-});
-```
-
-### CI-Specific Reporter
-
-```typescript
-export default defineConfig({
-  reporter: process.env.CI
-    ? [["github"], ["blob"], ["html"]]
-    : [["list"], ["html"]],
-});
-```
-
-## Sharding
-
-### Command Line
-
-```bash
-# Split into 4 shards, run shard 1
-npx playwright test --shard=1/4
-
-# Run shard 2
-npx playwright test --shard=2/4
-```
-
-### Configuration
-
-```typescript
-// playwright.config.ts
-export default defineConfig({
-  // Evenly distribute tests across shards
-  fullyParallel: true,
-
-  // For blob reporter to merge later
-  reporter: process.env.CI ? [["blob"]] : [["html"]],
-});
-```
-
-### Merge Sharded Reports
-
-```bash
-# After all shards complete, merge blob reports
-npx playwright merge-reports --reporter html ./all-blob-reports
-```
-
-## Environment Management
-
-### Environment Variables
-
-```typescript
-// playwright.config.ts
-import { defineConfig } from "@playwright/test";
-import dotenv from "dotenv";
-
-// Load env file based on environment
-dotenv.config({ path: `.env.${process.env.NODE_ENV || "development"}` });
-
-export default defineConfig({
-  use: {
-    baseURL: process.env.BASE_URL || "http://localhost:3000",
-  },
-});
-```
-
-### Multiple Environments
-
-```yaml
-# .github/workflows/playwright.yml
-jobs:
-  test:
-    strategy:
-      matrix:
-        environment: [staging, production]
-    steps:
-      - name: Run tests
-        run: npx playwright test
-        env:
-          BASE_URL: ${{ matrix.environment == 'staging' && 'https://staging.example.com' || 'https://example.com' }}
-          TEST_USER: ${{ secrets[format('TEST_USER_{0}', matrix.environment)] }}
-```
-
-### Secrets Management
-
-```yaml
-# GitHub Actions secrets
-- name: Run tests
-  run: npx playwright test
-  env:
-    TEST_EMAIL: ${{ secrets.TEST_EMAIL }}
-    TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }}
-```
-
-```typescript
-// tests use environment variables
-test("login", async ({ page }) => {
-  await page.getByLabel("Email").fill(process.env.TEST_EMAIL!);
-  await page.getByLabel("Password").fill(process.env.TEST_PASSWORD!);
-});
-```
-
-## Caching
-
-### Cache Playwright Browsers
-
-```yaml
-- name: Cache Playwright browsers
-  uses: actions/cache@v4
-  id: playwright-cache
-  with:
-    path: ~/.cache/ms-playwright
-    key: playwright-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
-
-- name: Install Playwright browsers
-  if: steps.playwright-cache.outputs.cache-hit != 'true'
-  run: npx playwright install --with-deps
-
-- name: Install system deps only
-  if: steps.playwright-cache.outputs.cache-hit == 'true'
-  run: npx playwright install-deps
-```
-
-### Cache Node Modules
-
-```yaml
-- uses: actions/setup-node@v4
-  with:
-    node-version: 20
-    cache: "npm"
-
-- name: Install dependencies
-  run: npm ci
-```
-
-## Best Practices
-
-| Practice                      | Benefit                   |
-| ----------------------------- | ------------------------- |
-| Use `npm ci`                  | Deterministic installs    |
-| Run headless in CI            | Faster, no display needed |
-| Set retries in CI only        | Handle flakiness          |
-| Upload artifacts on failure   | Debug failures            |
-| Use sharding for large suites | Faster execution          |
-| Cache browsers                | Faster setup              |
-| Use blob reporter for shards  | Merge reports correctly   |
-
-## CI Configuration Reference
-
-```typescript
-// playwright.config.ts - CI optimized
-export default defineConfig({
-  testDir: "./tests",
-  fullyParallel: true,
-  forbidOnly: !!process.env.CI,
-  retries: process.env.CI ? 2 : 0,
-  workers: process.env.CI ? 1 : undefined,
-  reporter: process.env.CI
-    ? [["github"], ["blob"], ["html"]]
-    : [["list"], ["html"]],
-  use: {
-    baseURL: process.env.BASE_URL || "http://localhost:3000",
-    trace: "on-first-retry",
-    screenshot: "only-on-failure",
-    video: "on-first-retry",
-  },
-});
-```
-
-## Related References
-
-- **Performance optimization**: See [performance.md](performance.md) for sharding and parallelization
-- **Debugging CI failures**: See [debugging.md](debugging.md) for troubleshooting
-- **Test reporting**: See [debugging.md](debugging.md) for trace viewer usage