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

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

#### 2. Run Standalone

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

# Or push to trigger
git push origin main
```

#### 3. Use in PR Checks

```yaml
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
```bash
pip install playwright
```

### Browser Installation
```bash
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:

```python
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

```bash
# 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/