Chrome Runner for Web UI Testing

🎯 Why Chrome Runner?

Performance Benefits

Addresses Common Issues

🚀 Quick Start

1. Build Chrome Runner

# Build and push to registry
./scripts/build-chrome.sh --push
# Local build only
./scripts/build-chrome.sh

2. Configure Environment

# Copy and customize configuration
cp config/chrome-runner.env.example config/chrome-runner.env
# Edit with your settings
nano config/chrome-runner.env

3. Deploy Chrome Runner

# Start Chrome runner with Docker Compose
GITHUB_TOKEN=<your-token> GITHUB_REPOSITORY=<your-repo> \
docker-compose -f docker/docker-compose.chrome.yml up -d
# Scale to multiple instances
docker-compose -f docker/docker-compose.chrome.yml up -d --scale chrome-runner=3

4. Use in GitHub Actions

jobs:
 ui-tests:
 runs-on: [self-hosted, chrome, ui-tests]
 steps:
 - uses: actions/checkout@v4
 - name: Run Playwright tests
 run: npx playwright test
 - name: Run Cypress tests
 run: npx cypress run --headless

🔧 Technical Specifications

Base Image

Installed Software

Browser & Driver

Testing Frameworks

Security Patches Applied 🔒

GitHub Actions Runner

Resource Configuration

# Default limits (configurable)
deploy:
 resources:
 limits:
 memory: 4G
 cpus: 2
 reservations:
 memory: 2G
 cpus: 1

Environment Variables

# Chrome configuration
CHROME_BIN=/usr/bin/google-chrome-stable
DISPLAY=:99
# GitHub Actions runner
GITHUB_TOKEN=<required>
GITHUB_REPOSITORY=<required>
RUNNER_LABELS=chrome,ui-tests,web-automation

📊 Performance Optimizations

Chrome Flags

--headless=new
--no-sandbox
--disable-dev-shm-usage
--disable-gpu
--disable-background-timer-throttling
--disable-backgrounding-occluded-windows
--disable-renderer-backgrounding
--disable-features=TranslateUI
--disable-ipc-flooding-protection
--enable-features=VizHitTestingDrawQuad

Shared Memory

Persistent Volumes

volumes:
 chrome_cache: # Browser cache and user data
 node_modules: # NPM dependencies
 workspace: # Build artifacts and test reports

🛠 Development & Testing

Local Testing

# Test Chrome installation
docker run --rm ghcr.io/grammatonic/github-runner:chrome-latest \
 google-chrome --version
# Test ChromeDriver
docker run --rm ghcr.io/grammatonic/github-runner:chrome-latest \
 chromedriver --version
# Interactive testing
docker run -it --rm \
 -v /tmp/.X11-unix:/tmp/.X11-unix \
 -e DISPLAY=:0 \
 ghcr.io/grammatonic/github-runner:chrome-latest bash

Framework Examples

Playwright

// playwright.config.js
module.exports = {
 use: {
 headless: true,
 channel: "chrome",
 },
 projects: [
 {
 name: "chromium",
 use: { ...devices["Desktop Chrome"] },
 },
 ],
};

Cypress

// cypress.config.js
module.exports = {
 e2e: {
 setupNodeEvents(on, config) {
 // Configure Chrome browser
 },
 },
 env: {
 chromeWebSecurity: false,
 },
};

Selenium

# Python Selenium example
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
chrome_options = Options()
chrome_options.add_argument("--headless=new")
chrome_options.add_argument("--no-sandbox")
chrome_options.add_argument("--disable-dev-shm-usage")
driver = webdriver.Chrome(options=chrome_options)

🔒 Security & Compliance

Container Security

GitHub Security

Network Security

🚨 Troubleshooting

Common Issues

ChromeDriver Version Mismatch

# Check versions
google-chrome --version
chromedriver --version
# Rebuild with latest ChromeDriver
./scripts/build-chrome.sh --no-cache

Memory Issues

# Increase shared memory
# In docker-compose.chrome.yml:
shm_size: 4g
# Or add Chrome flags
--memory-pressure-off
--max_old_space_size=4096

Display Issues

# Check virtual display
echo $DISPLAY
ps aux | grep Xvfb
# Start virtual display manually
Xvfb :99 -screen 0 1920x1080x24 &

Permission Errors

# Check runner user
whoami
id runner
# Fix permissions
sudo chown -R runner:runner /actions-runner
sudo chown -R runner:runner /home/runner

Debug Mode

# Enable debug logging
export ACTIONS_RUNNER_DEBUG=true
export ACTIONS_STEP_DEBUG=true
# Run with debug output
docker-compose -f docker/docker-compose.chrome.yml up

Health Checks

# Check runner status
docker ps --filter "label=com.github.runner.type=chrome"
# Check logs
docker logs <container-id>
# Health check endpoint
curl http://localhost:8080/health

📈 Monitoring & Metrics

Container Metrics

# Resource usage
docker stats --format "table {{.Container}}\t{{.CPUPerc}}\t{{.MemUsage}}"
# Chrome process monitoring
docker exec <container> ps aux | grep chrome

GitHub Actions Integration

Log Aggregation

# Add to docker-compose.chrome.yml
logging:
 driver: "json-file"
 options:
 max-size: "10m"
 max-file: "3"

🔄 CI/CD Integration

Automated Building

# .github/workflows/ci-cd.yml
- name: Build Chrome Runner Image
 uses: docker/build-push-action@v5
 with:
 context: ./docker
 file: ./docker/Dockerfile.chrome
 platforms: linux/amd64,linux/arm64
 tags: |
 ghcr.io/grammatonic/github-runner:chrome-latest
 ghcr.io/grammatonic/github-runner:chrome-${{ github.sha }}

Security Scanning

- name: Container Security Scan
 uses: aquasecurity/trivy-action@master
 with:
 image-ref: "ghcr.io/grammatonic/github-runner:chrome-latest"
 format: "sarif"
 output: "trivy-results.sarif"

Multi-architecture Support

📚 Related Documentation

🔗 External Resources

Testing Frameworks

Chrome for Testing

GitHub Actions

✅ Production Status