pyWebLayout/COVERAGE_GUTTERS_SETUP.md

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:

   pip install pytest pytest-cov coverage
   

Configuration Files

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

Your VSCode settings are already configured with:

{
    "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:

[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

python run_coverage_gutters.py

Option 2: Manual pytest command

python -m pytest tests/ --cov=pyWebLayout --cov-report=xml --cov-report=html --cov-report=term

Option 3: Full coverage analysis

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

# Install dependencies
pip install pytest pytest-cov coverage

# Generate coverage for gutters
python run_coverage_gutters.py

# View HTML report
open htmlcov/index.html