# Coverage Gutters Setup Guide

This guide helps you set up Coverage Gutters in VSCode to visualize code coverage for the pyWebLayout project.

## Prerequisites

1. **Install VSCode Extension**: Make sure you have the "Coverage Gutters" extension installed in VSCode.
2. **Install Python packages**: 
   ```bash
   pip install pytest pytest-cov coverage
   ```

## Configuration Files

### 1. VSCode Settings (`.vscode/settings.json`)

Your VSCode settings are already configured with:
```json
{
    "coverage-gutters.coverageBaseDir": "./",
    "coverage-gutters.coverageFileNames": [
        "coverage.xml",
        "lcov.info",
        "cov.xml",
        "coverage.info"
    ],
    "coverage-gutters.showGutterCoverage": true,
    "coverage-gutters.showLineCoverage": true,
    "coverage-gutters.showRulerCoverage": true,
    "coverage-gutters.xmlname": "coverage.xml"
}
```

### 2. Coverage Configuration (`pyproject.toml`)

Coverage settings are configured in `pyproject.toml`:
```toml
[tool.coverage.run]
source = ["pyWebLayout"]
branch = true
omit = [
    "*/tests/*",
    "*/test_*",
    "setup.py",
    "*/examples/*",
    "*/__main__.py"
]

[tool.coverage.xml]
output = "coverage.xml"

[tool.coverage.html]
directory = "htmlcov"
```

## How to Generate Coverage

### Option 1: Quick Coverage for Gutters
```bash
python run_coverage_gutters.py
```

### Option 2: Manual pytest command
```bash
python -m pytest tests/ --cov=pyWebLayout --cov-report=xml --cov-report=html --cov-report=term
```

### Option 3: Full coverage analysis
```bash
python scripts/run_coverage.py
```

## Using Coverage Gutters in VSCode

1. **Generate coverage data** using one of the options above
2. **Open VSCode** and navigate to your Python source files
3. **Enable Coverage Gutters**:
   - Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on Mac)
   - Type "Coverage Gutters: Display Coverage"
   - Or click the "Watch" button in the status bar

## What You'll See

- **Green lines**: Code that is covered by tests
- **Red lines**: Code that is NOT covered by tests
- **Yellow lines**: Partially covered code (branches)
- **Coverage percentage** in the status bar

## Troubleshooting

1. **No coverage showing**:
   - Make sure `coverage.xml` exists in the project root
   - Check that the Coverage Gutters extension is enabled
   - Try reloading VSCode window

2. **Coverage not updating**:
   - Re-run the coverage command
   - Click "Watch" in the status bar to refresh

3. **Tests not running**:
   - Make sure you're in the project root directory
   - Install missing dependencies: `pip install pytest pytest-cov`

## Coverage Files Generated

After running coverage, you should see:
- `coverage.xml` - XML format for Coverage Gutters
- `htmlcov/` - HTML coverage report directory
- `coverage.json` - JSON format for badges
- `.coverage` - Coverage database file

## Commands Summary

```bash
# Install dependencies
pip install pytest pytest-cov coverage

# Generate coverage for gutters
python run_coverage_gutters.py

# View HTML report
open htmlcov/index.html