timmy-config/docs/playwright-ci-installation.md

Playwright CI Installation

Issue #561: [CI] Install Playwright in CI for Nexus visual smoke tests

Problem

The visual smoke test (nexus_smoke_test.py, PR #558) supports Playwright for screenshot capture with JS error detection, but CI runners don't have Playwright installed.

Solution

Created a reusable CI workflow that installs Playwright and Chromium for visual smoke tests.

Workflow: .gitea/workflows/playwright-install.yml

Features

1. Reusable Workflow: Can be called by other workflows using workflow_call
2. Conditional Installation: Options to install Chromium and system dependencies
3. Caching: Caches Playwright browsers for faster subsequent runs
4. Verification: Tests Playwright installation and Chromium launch
5. Integration Testing: Tests Nexus smoke test script with Playwright

Usage

1. Call from Another Workflow

jobs:
  visual-tests:
    uses: ./.gitea/workflows/playwright-install.yml
    with:
      install_chromium: true
      install_deps: true

2. Run Standalone

# Trigger manually
gitea-cli workflow run playwright-install.yml

# Or push to trigger
git push origin main

3. Use in PR Checks

name: Visual Smoke Tests

on:
  pull_request:
    paths:
      - 'scripts/**/nexus_smoke_test.py'

jobs:
  smoke-test:
    uses: ./.gitea/workflows/playwright-install.yml
    with:
      install_chromium: true
  
  run-smoke-test:
    needs: smoke-test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ./.gitea/workflows/playwright-install.yml
      - name: Run smoke test
        run: python scripts/nexus_smoke_test.py --programmatic

Installation Details

Python Dependencies

pip install playwright

Browser Installation

playwright install chromium
playwright install-deps chromium

System Dependencies

• libnss3
• libnspr4
• libatk1.0-0
• libatk-bridge2.0-0
• libcups2
• libdrm2
• libxkbcommon0
• libxcomposite1
• libxdamage1
• libxfixes3
• libxrandr2
• libgbm1
• libpango-1.0-0
• libcairo2
• libasound2
• libatspi2.0-0
• libwayland-client0

Benefits

With Playwright

• Full headless Chromium browser
• JS console error detection
• Three.js scene verification
• Network idle wait for SPA rendering
• Dynamic content capture
• page.evaluate() for custom checks

Without Playwright (fallback)

• wkhtmltoimage (no JS execution)
• Limited screenshot capability
• No JS error detection
• No dynamic content capture

Verification

The workflow includes verification steps:

1. Import Test: Verify Playwright can be imported
2. Version Check: Confirm Playwright version
3. Launch Test: Test Chromium browser launch
4. Cache Check: Verify browser caching

Integration with Nexus Smoke Test

The Nexus smoke test (nexus_smoke_test.py) automatically detects Playwright:

def _get_screenshot_backend(self):
    """Get the best available screenshot backend."""
    try:
        from playwright.sync_api import sync_playwright
        return "playwright"
    except ImportError:
        pass
    
    try:
        import subprocess
        subprocess.run(["wkhtmltoimage", "--version"], check=True)
        return "wkhtmltoimage"
    except:
        pass
    
    return None

Troubleshooting

Common Issues

1. Playwright not found: Ensure pip install playwright runs before usage
2. Chromium not launching: Check system dependencies are installed
3. Cache miss: Verify cache key includes workflow file hash
4. Permission denied: Ensure playwright install-deps runs with sudo

Debug Commands

# Check Playwright installation
python -c "import playwright; print(playwright.__version__)"

# Check Chromium installation
playwright --version

# Test browser launch
python -c "
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
    browser = p.chromium.launch()
    print('Chromium launched successfully')
    browser.close()
"

References

• Issue #561: [CI] Install Playwright in CI for Nexus visual smoke tests
• PR #558: feat: Visual Smoke Test for The Nexus #490
• Issue #490: Visual Smoke Test for The Nexus
• Playwright Documentation: https://playwright.dev/python/