Integration Patterns

Integration Patterns

This guide shows various ways to integrate the GUI-Based Testing Code Review action with your existing CI/CD pipelines.

Basic Patterns

1. Simple All-in-One

The easiest way to get started with full functionality:

name: GUI Test Review
on:
  pull_request:
    branches: [main]

jobs:
  test-and-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      pages: write
      id-token: write
    
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Required for visual comparison
          
      - uses: DigitalProductInnovationAndDevelopment/Code-Reviews-of-GUI-Tests@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          enable-visual-comparison: 'true'
          mode: 'full'  # Default - runs lint, test, and dashboard

2. Enhance Existing Test Pipeline

Add visual review to your current Playwright tests:

name: CI Pipeline
on: [pull_request, push]

jobs:
  # Your existing test job
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'
      - run: npm ci
      - run: npm test
      
      # Generate Playwright report with JSON reporter
      - run: npx playwright test --reporter=json
      
      # Upload for dashboard
      - uses: actions/upload-artifact@v4
        with:
          name: test-results
          path: |
            playwright-report/
            test-results/
            playwright-metrics.json
  
  # Add visual dashboard
  visual-review:
    needs: test
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      pages: write
      id-token: write
      
    steps:
      - uses: actions/checkout@v4
      - uses: actions/download-artifact@v4
        with:
          name: test-results
          path: artifacts
      
      - uses: DigitalProductInnovationAndDevelopment/Code-Reviews-of-GUI-Tests@v1
        with:
          mode: 'dashboard-only'
          custom-artifacts-path: 'artifacts'

3. Separate Lint and Test

Run components in parallel for faster feedback:

name: Parallel CI
on: [pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write  # For reviewdog inline comments
    steps:
      - uses: actions/checkout@v4
      - uses: DigitalProductInnovationAndDevelopment/Code-Reviews-of-GUI-Tests@v1
        with:
          mode: 'lint-only'
          reviewdog-reporter: 'github-pr-review'
          
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: DigitalProductInnovationAndDevelopment/Code-Reviews-of-GUI-Tests@v1
        with:
          mode: 'test-only'
          enable-visual-comparison: 'true'
          test-files: 'tests'  # Or your test directory
          
  dashboard:
    needs: [lint, test]
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      pages: write
      id-token: write
      
    steps:
      - uses: actions/checkout@v4
      - uses: actions/download-artifact@v4
      - uses: DigitalProductInnovationAndDevelopment/Code-Reviews-of-GUI-Tests@v1
        with:
          mode: 'dashboard-only'
          enable-pr-comments: 'true'
          enable-github-pages: 'true'

Advanced Patterns

4. Matrix Testing with Consolidated Dashboard

Test across multiple configurations:

name: Matrix Testing
on: [pull_request]

jobs:
  test-matrix:
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        node: [18, 20]
        browser: [chromium, firefox, webkit]
    
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
      
      - name: Run Playwright tests
        run: |
          npx playwright test --browser=${{ matrix.browser }} \
            --reporter=json > playwright-metrics-${{ matrix.os }}-${{ matrix.node }}-${{ matrix.browser }}.json
      
      - uses: actions/upload-artifact@v4
        with:
          name: results-${{ matrix.os }}-${{ matrix.node }}-${{ matrix.browser }}
          path: playwright-metrics-*.json
  
  consolidate-dashboard:
    needs: test-matrix
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      pages: write
      id-token: write
      
    steps:
      - uses: actions/checkout@v4
      - uses: actions/download-artifact@v4
        with:
          pattern: results-*
          merge-multiple: true
          path: artifacts
      
      # Merge JSON results (custom script needed)
      - run: |
          jq -s 'add' artifacts/playwright-metrics-*.json > artifacts/playwright-metrics.json
      
      - uses: DigitalProductInnovationAndDevelopment/Code-Reviews-of-GUI-Tests@v1
        with:
          mode: 'dashboard-only'
          custom-artifacts-path: 'artifacts'

5. Conditional Testing Based on Changes

Only run tests when relevant files change:

name: Smart CI
on:
  pull_request:
    paths:
      - 'src/**'
      - 'tests/**'
      - 'package*.json'
      - 'playwright.config.js'

jobs:
  detect-changes:
    runs-on: ubuntu-latest
    outputs:
      ui-changed: ${{ steps.filter.outputs.ui }}
      tests-changed: ${{ steps.filter.outputs.tests }}
    steps:
      - uses: dorny/paths-filter@v2
        id: filter
        with:
          filters: |
            ui:
              - 'src/components/**'
              - 'src/pages/**'
            tests:
              - 'tests/**'
              - 'playwright.config.js'
  
  gui-review:
    needs: detect-changes
    if: needs.detect-changes.outputs.ui-changed == 'true' || needs.detect-changes.outputs.tests-changed == 'true'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      pages: write
      id-token: write
      
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - uses: DigitalProductInnovationAndDevelopment/Code-Reviews-of-GUI-Tests@v1
        with:
          enable-visual-comparison: 'true'
          test-files: ${{ needs.detect-changes.outputs.ui-changed == 'true' && 'tests/ui' || 'tests' }}

6. Scheduled Regression Testing

Run comprehensive tests nightly:

name: Nightly Regression
on:
  schedule:
    - cron: '0 2 * * *'  # 2 AM UTC daily
  workflow_dispatch:  # Manual trigger

jobs:
  regression-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: DigitalProductInnovationAndDevelopment/Code-Reviews-of-GUI-Tests@v1
        with:
          mode: 'full'
          test-files: 'tests/**/*.spec.ts'  # All tests
          fail-on-test-failure: 'true'  # Strict mode for regression
          
      - name: Notify on failure
        if: failure()
        uses: actions/github-script@v7
        with:
          script: |
            await github.rest.issues.create({
              owner: context.repo.owner,
              repo: context.repo.repo,
              title: 'Nightly regression tests failed',
              body: 'Check the [test results](${{ steps.review.outputs.dashboard-url }})'
            })

Framework Integration

7. Monorepo Support

Handle multiple packages with different test suites:

name: Monorepo CI
on: [pull_request]

jobs:
  test-packages:
    strategy:
      matrix:
        package: [web, mobile, api]
    
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - name: Test ${{ matrix.package }}
        working-directory: packages/${{ matrix.package }}
        run: |
          npm ci
          npm test
      
      - uses: DigitalProductInnovationAndDevelopment/Code-Reviews-of-GUI-Tests@v1
        with:
          mode: 'test-only'
          test-files: 'packages/${{ matrix.package }}/tests'
          playwright-config: 'packages/${{ matrix.package }}/playwright.config.js'
      
      - uses: actions/upload-artifact@v4
        with:
          name: ${{ matrix.package }}-results
          path: artifacts/
  
  unified-dashboard:
    needs: test-packages
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      pages: write
      id-token: write
      
    steps:
      - uses: actions/checkout@v4
      - uses: actions/download-artifact@v4
        with:
          path: combined-artifacts
      
      - uses: DigitalProductInnovationAndDevelopment/Code-Reviews-of-GUI-Tests@v1
        with:
          mode: 'dashboard-only'
          custom-artifacts-path: 'combined-artifacts'

8. Custom Test Frameworks Integration

Adapt non-Playwright frameworks to work with the dashboard:

name: Custom Framework Integration
on: [pull_request]

jobs:
  cypress-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      # Run Cypress tests
      - run: npm run cypress:run
      
      # Convert Cypress results to compatible format
      - name: Convert results
        run: |
          node scripts/convert-cypress-to-playwright-format.js \
            cypress/results/output.json \
            > artifacts/playwright-metrics.json
      
      - uses: actions/upload-artifact@v4
        with:
          name: cypress-results
          path: artifacts/
  
  dashboard:
    needs: cypress-tests
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      pages: write
      id-token: write
      
    steps:
      - uses: actions/checkout@v4
      - uses: actions/download-artifact@v4
      
      - uses: DigitalProductInnovationAndDevelopment/Code-Reviews-of-GUI-Tests@v1
        with:
          mode: 'dashboard-only'
          custom-artifacts-path: '.'

Performance Optimization

9. Optimized Caching Strategy

Maximize speed with proper caching:

name: Optimized CI
on: [pull_request]

jobs:
  test-with-cache:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      # Cache Node modules
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'
      
      # Cache Playwright browsers
      - name: Get Playwright version
        id: playwright-version
        run: echo "version=$(npm ls @playwright/test --json | jq -r '.dependencies["@playwright/test"].version')" >> $GITHUB_OUTPUT
      
      - uses: actions/cache@v3
        id: playwright-cache
        with:
          path: ~/.cache/ms-playwright
          key: ${{ runner.os }}-playwright-${{ steps.playwright-version.outputs.version }}
      
      # Install Playwright browsers if not cached
      - if: steps.playwright-cache.outputs.cache-hit != 'true'
        run: npx playwright install --with-deps
      
      - uses: DigitalProductInnovationAndDevelopment/Code-Reviews-of-GUI-Tests@v1
        with:
          enable-visual-comparison: 'true'
          artifacts-retention-days: '7'  # Reduce storage

10. Sharded Test Execution

Split large test suites for parallel execution:

name: Sharded Tests
on: [pull_request]

jobs:
  test-shard:
    strategy:
      matrix:
        shard: [1, 2, 3, 4]  # 4 parallel shards
    
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Run shard ${{ matrix.shard }}/4
        run: |
          npx playwright test --shard=${{ matrix.shard }}/4 \
            --reporter=json > playwright-metrics-shard-${{ matrix.shard }}.json
      
      - uses: actions/upload-artifact@v4
        with:
          name: shard-${{ matrix.shard }}
          path: playwright-metrics-shard-*.json
  
  merge-results:
    needs: test-shard
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      pages: write
      id-token: write
      
    steps:
      - uses: actions/checkout@v4
      - uses: actions/download-artifact@v4
        with:
          pattern: shard-*
          merge-multiple: true
          path: artifacts
      
      # Merge sharded results
      - run: |
          jq -s '
            {
              suites: map(.suites) | add,
              stats: {
                total: map(.stats.total) | add,
                passed: map(.stats.passed) | add,
                failed: map(.stats.failed) | add,
                skipped: map(.stats.skipped) | add,
                duration: map(.stats.duration) | max
              }
            }
          ' artifacts/playwright-metrics-shard-*.json > artifacts/playwright-metrics.json
      
      - uses: DigitalProductInnovationAndDevelopment/Code-Reviews-of-GUI-Tests@v1
        with:
          mode: 'dashboard-only'
          custom-artifacts-path: 'artifacts'

Enterprise Patterns

11. Multi-Environment Testing

Test against different deployment environments:

name: Multi-Environment
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  test-environments:
    strategy:
      matrix:
        environment: [staging, production]
        include:
          - environment: staging
            url: https://staging.example.com
          - environment: production
            url: https://example.com
    
    runs-on: ubuntu-latest
    environment: ${{ matrix.environment }}
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Test against ${{ matrix.environment }}
        env:
          BASE_URL: ${{ matrix.url }}
        run: |
          npx playwright test --grep @smoke \
            --reporter=json > playwright-metrics-${{ matrix.environment }}.json
      
      - uses: actions/upload-artifact@v4
        with:
          name: ${{ matrix.environment }}-results
          path: playwright-metrics-*.json
  
  consolidated-report:
    needs: test-environments
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      pages: write
      id-token: write
      
    steps:
      - uses: actions/checkout@v4
      - uses: actions/download-artifact@v4
      
      - uses: DigitalProductInnovationAndDevelopment/Code-Reviews-of-GUI-Tests@v1
        with:
          mode: 'dashboard-only'
          web-report-url: 'https://test-results.company.com'

12. Security-First Pattern

Include security checks in the pipeline:

name: Secure CI
on:
  pull_request:
    branches: [main, develop]

jobs:
  security-and-quality:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      security-events: write
      pages: write
      id-token: write
    
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      # Security scan
      - name: Run security audit
        run: npm audit --audit-level=moderate
      
      # Dependency check
      - name: Check dependencies
        run: |
          npx depcheck
          npx npm-check-updates
      
      # Main action with strict settings
      - uses: DigitalProductInnovationAndDevelopment/Code-Reviews-of-GUI-Tests@v1
        with:
          enable-visual-comparison: 'true'
          fail-on-test-failure: 'true'
          reviewdog-reporter: 'github-pr-check'  # Both PR and check
          
      # Additional security checks on generated artifacts
      - name: Scan artifacts for secrets
        run: |
          npx @secretlint/cli artifacts/**/*.json

Best Practices

DO:

• ✅ Use fetch-depth: 0 for visual comparison (required for branch checkout)
• ✅ Set appropriate permissions for your needs (minimum required)
• ✅ Cache dependencies and Playwright browsers for faster runs
• ✅ Use matrix strategies for comprehensive testing across environments
• ✅ Implement smart retries for flaky tests
• ✅ Use artifacts-retention-days to manage storage costs
• ✅ Leverage test-files parameter to focus on relevant tests
• ✅ Use custom-artifacts-path when integrating with existing pipelines

DON'T:

• ❌ Run all tests on every commit (use path filters)
• ❌ Ignore security warnings from npm audit
• ❌ Use fail-on-test-failure: true without retry logic for flaky tests
• ❌ Forget to clean up resources (Docker containers, test servers, etc.)
• ❌ Skip setting key-test-file when using visual comparison
• ❌ Use dashboard-only mode without proper artifact structure

Performance Tips:

1. Use GitHub's larger runners for heavy test suites:

   runs-on: ubuntu-latest-4-cores  # or ubuntu-latest-8-cores

2. Parallelize independent test suites using job matrix

3. Cache everything possible:

   • Node modules (actions/setup-node with cache)
   • Playwright browsers (see example above)
   • Build outputs if applicable

4. Use shallow clones when comparison isn't needed:

   - uses: actions/checkout@v4
     # No fetch-depth: 0 if not comparing branches

5. Consider test sharding for very large suites (see sharding example)

6. Optimize artifact retention:

   artifacts-retention-days: '7'  # Instead of default 30

7. Use continue-on-error for non-critical steps:

   - uses: DigitalProductInnovationAndDevelopment/Code-Reviews-of-GUI-Tests@v1
     continue-on-error: true  # Dashboard still generates if tests fail

Debugging Tips:

Enable verbose logging when troubleshooting:

env:
  ACTIONS_STEP_DEBUG: true
  DEBUG: 'pw:*'  # Playwright debug logs

Check intermediate outputs:

- name: Debug artifacts
  if: always()
  run: |
    find artifacts -type f -name "*.json" -exec echo {} \; -exec head -20 {} \;