# Docker Testing Guide

This guide explains how to set up and run tests using Docker for the Low Cost Browsing MCP Server.

## Overview

The Docker testing environment provides:
- **Isolated Testing**: Tests run in clean, reproducible containers
- **Multiple Browsers**: Chromium, Firefox, and WebKit pre-installed
- **CI/CD Ready**: Optimized for continuous integration pipelines
- **Cross-Platform**: Works on Linux, macOS, and Windows
- **Parallel Testing**: Run tests across different browsers simultaneously

## Quick Start

### 1. Setup Environment

```bash
# Make setup script executable
chmod +x scripts/docker-setup.sh

# Run automated setup
./scripts/docker-setup.sh

# Or with LLM providers
./scripts/docker-setup.sh --start-with-llm
```

### 2. Run Tests

```bash
# Using Make (recommended)
make test                    # Unit tests
make test-e2e               # E2E tests
make test-coverage          # Tests with coverage
make test-browsers          # All browsers

# Using Docker directly
docker run --rm lc-browser-mcp:test-latest unit
docker run --rm lc-browser-mcp:test-latest e2e
```

## Docker Images

### Available Images

| Image | Target | Purpose | Size |
|-------|--------|---------|------|
| `lc-browser-mcp:dev-latest` | development | Development with hot reload | ~2GB |
| `lc-browser-mcp:test-latest` | testing | Testing with all browsers | ~1.5GB |
| `lc-browser-mcp:latest` | production | Production runtime | ~200MB |

### Build Images

```bash
# Build all images
make build-all

# Build specific images
make build-dev      # Development image
make build-test     # Testing image
make build-prod     # Production image
```

## Testing Commands

### Make Commands

```bash
# Basic testing
make test                    # Run unit tests
make test-e2e               # Run E2E tests
make test-coverage          # Run with coverage report
make test-all               # Run all tests

# Browser-specific testing
make test-chromium          # Test on Chromium only
make test-firefox           # Test on Firefox only  
make test-webkit            # Test on WebKit only
make test-browsers          # Test on all browsers

# Development
make dev                    # Start development environment
make dev-shell              # Open development shell
make dev-logs              # View development logs

# Cleanup
make clean                  # Remove containers
make clean-images          # Remove images
make clean-all             # Remove everything
```

### Docker Compose Commands

```bash
# Development
docker compose up app-dev                    # Start development
docker compose logs -f app-dev              # View logs

# Testing
docker compose --profile testing up app-test    # Run tests
docker compose --profile browsers up            # Test all browsers

# With LLM providers
docker compose --profile llm up ollama          # Start Ollama
docker compose --profile llm up jan-ai          # Start JAN AI

# Reports server
docker compose --profile reports up test-reports  # Serve reports at :8080
```

### Direct Docker Commands

```bash
# Unit tests
docker run --rm \
  -v $(pwd)/coverage:/app/coverage \
  lc-browser-mcp:test-latest unit

# E2E tests
docker run --rm \
  -v $(pwd)/test-results:/app/test-results \
  -v $(pwd)/playwright-report:/app/playwright-report \
  --shm-size=1gb \
  lc-browser-mcp:test-latest e2e

# Coverage tests
docker run --rm \
  -v $(pwd)/coverage:/app/coverage \
  lc-browser-mcp:test-latest coverage

# Browser-specific tests
docker run --rm \
  -e PLAYWRIGHT_PROJECT=chromium \
  -v $(pwd)/test-results:/app/test-results \
  --shm-size=1gb \
  lc-browser-mcp:test-latest e2e
```

## CI/CD Integration

### Using the CI Script

```bash
# Run all CI tests
./scripts/ci-test.sh

# Run specific test types
./scripts/ci-test.sh --unit-only
./scripts/ci-test.sh --e2e-only
./scripts/ci-test.sh --browsers-only

# With custom settings
./scripts/ci-test.sh --timeout 900 --threshold 85
```

### GitHub Actions Example

```yaml
name: Docker Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Run CI Tests
        run: ./scripts/ci-test.sh
        
      - name: Upload Coverage
        uses: codecov/codecov-action@v3
        with:
          file: ./coverage/lcov.info
          
      - name: Upload Test Results
        uses: actions/upload-artifact@v3
        if: always()
        with:
          name: test-results
          path: |
            coverage/
            test-results/
            playwright-report/
```

### GitLab CI Example

```yaml
test:
  image: docker:latest
  services:
    - docker:dind
  script:
    - chmod +x scripts/ci-test.sh
    - ./scripts/ci-test.sh
  artifacts:
    reports:
      junit: test-results/junit.xml
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura-coverage.xml
    paths:
      - coverage/
      - test-results/
      - playwright-report/
    expire_in: 1 week
```

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `NODE_ENV` | test | Environment mode |
| `CI` | false | CI environment flag |
| `DISPLAY` | :99 | X11 display for browsers |
| `PLAYWRIGHT_BROWSERS_PATH` | /ms-playwright | Browser installation path |
| `PLAYWRIGHT_PROJECT` | all | Specific browser to test |

### Docker Compose Profiles

| Profile | Services | Purpose |
|---------|----------|---------|
| default | app-dev | Development |
| testing | app-test | Testing |
| browsers | test-* | Browser-specific testing |
| llm | ollama, jan-ai | LLM providers |
| reports | test-reports | Report server |
| production | app-prod | Production |

### Volume Mounts

```yaml
volumes:
  - ./coverage:/app/coverage           # Test coverage
  - ./test-results:/app/test-results   # E2E results
  - ./playwright-report:/app/playwright-report  # E2E reports
  - ./logs:/app/logs                   # Application logs
```

## Browser Testing

### Supported Browsers

- **Chromium**: Latest stable version
- **Firefox**: Latest stable version  
- **WebKit**: Latest stable version

### Browser-Specific Options

```bash
# Test specific browser
PLAYWRIGHT_PROJECT=chromium make test-e2e
PLAYWRIGHT_PROJECT=firefox make test-e2e
PLAYWRIGHT_PROJECT=webkit make test-e2e

# Browser launch options (in playwright.config.ts)
launchOptions: {
  args: [
    '--no-sandbox',              # Required for Docker
    '--disable-setuid-sandbox',  # Security for containers
    '--disable-dev-shm-usage',   # Shared memory
    '--disable-gpu',             # GPU acceleration
    '--no-first-run',           # Skip first run
    '--no-zygote',              # Process model
    '--single-process'           # Single process mode
  ]
}
```

## Troubleshooting

### Common Issues

1. **Browser Launch Failures**
   ```bash
   # Increase shared memory
   docker run --shm-size=1gb ...
   
   # Check browser installation
   docker run --rm lc-browser-mcp:test-latest npx playwright install --dry-run
   ```

2. **Permission Errors**
   ```bash
   # Fix permissions
   chmod -R 755 coverage test-results playwright-report
   ```

3. **Network Issues**
   ```bash
   # Use host network
   docker run --network=host ...
   ```

4. **Out of Memory**
   ```bash
   # Increase Docker memory limit
   # Docker Desktop: Settings > Resources > Memory
   ```

### Debug Mode

```bash
# Enable debug logging
docker run --rm \
  -e DEBUG=* \
  -e PLAYWRIGHT_DEBUG=1 \
  lc-browser-mcp:test-latest e2e

# Interactive debugging
make dev-shell
npx playwright test --debug
```

### Performance Optimization

```bash
# Parallel browser testing
docker compose --profile browsers up

# Use test cache
docker run --rm \
  -v playwright-cache:/ms-playwright \
  lc-browser-mcp:test-latest e2e

# Resource limits
docker run --rm \
  --memory=2g \
  --cpus="2.0" \
  lc-browser-mcp:test-latest e2e
```

## Reports and Artifacts

### Coverage Reports
- **Location**: `./coverage/lcov-report/index.html`
- **Format**: HTML, LCOV, JSON
- **Threshold**: 80% by default

### E2E Test Reports  
- **Location**: `./playwright-report/index.html`
- **Videos**: `./test-results/videos/`
- **Screenshots**: `./test-results/screenshots/`
- **Traces**: `./test-results/traces/`

### CI Reports
- **JUnit XML**: `./test-results/junit.xml`
- **JSON Results**: `./test-results/results.json`
- **Summary**: `./reports/test-summary.md`

### Viewing Reports

```bash
# Open coverage report
make docs-coverage

# Open test report
make docs-tests

# Serve reports via HTTP
docker compose --profile reports up test-reports
# View at http://localhost:8080
```

## Best Practices

### Performance
- Use `--shm-size=1gb` for browser tests
- Limit parallel workers in CI: `workers: 1`
- Use browser-specific projects for targeted testing

### Reliability
- Set appropriate timeouts: `timeout: 30000`
- Enable retries in CI: `retries: 2`
- Use `--no-sandbox` in containers

### Security
- Run containers as non-root user
- Use minimal base images
- Scan images for vulnerabilities

### Monitoring
- Enable health checks
- Collect logs and metrics
- Monitor resource usage

## Examples

### Complete Test Suite

```bash
# Full CI pipeline
./scripts/docker-setup.sh
make ci-test
make docs-coverage
```

### Development Workflow

```bash
# Start development
make dev

# Run tests during development
make test-quick

# Debug specific test
make dev-shell
npx playwright test specific-test.spec.ts --debug
```

### Production Validation

```bash
# Build production image
make build-prod

# Test production image
docker run --rm \
  -p 3000:3000 \
  lc-browser-mcp:latest

# Health check
curl http://localhost:3000/health
```