swadhin / laxyfile public
/ laxyfile / docs / codecov-setup.md
swadhin biswas Update on working process · 7/28/2025
f1cf876
201 lines · 5.8 KB
Raw Download

Codecov Integration Setup Guide

This guide explains how to set up and configure Codecov for LaxyFile's code coverage reporting.

Overview

Codecov is integrated into LaxyFile's CI/CD pipeline to provide:

  • Automated coverage reporting for all pull requests and commits
  • Coverage trends and historical data
  • Component-based coverage tracking for different parts of the codebase
  • Coverage status checks to maintain code quality

Setup Steps

1. Codecov Account Setup

  1. Sign up for Codecov: Go to codecov.io and sign up with your GitHub account
  2. Add Repository: Add the swadhinbiswas/laxyfile repository to your Codecov dashboard
  3. Get Upload Token: Copy the repository upload token from Codecov dashboard

2. GitHub Secrets Configuration

Add the following secrets to your GitHub repository:

  1. Go to Settings → Secrets and variables → Actions
  2. Add new repository secret:
    • Name: CODECOV_TOKEN
    • Value: Your Codecov upload token from step 1.3

3. Configuration Files

The following files are already configured in the repository:

codecov.yml - Main Configuration

coverage:
  precision: 2
  round: down
  range: "70...100"

  status:
    project:
      default:
        target: 80% # Overall project coverage target
        threshold: 1% # Allow 1% decrease
    patch:
      default:
        target: 75% # New code coverage target
        threshold: 2% # Allow 2% decrease for patches

Component Coverage Targets

  • Core Components: 85% coverage target
  • File Operations: 85% coverage target
  • Utilities: 85% coverage target
  • AI Components: 80% coverage target
  • Plugin System: 80% coverage target
  • UI Components: 75% coverage target
  • Preview System: 75% coverage target

4. GitHub Actions Integration

Coverage is automatically collected and uploaded in two workflows:

Test Workflow (.github/workflows/test.yml)

  • Runs on every push and pull request
  • Tests across multiple OS and Python versions
  • Uploads coverage with detailed flags

Release Workflow (.github/workflows/release.yml)

  • Runs on tagged releases
  • Ensures coverage before deployment
  • Uploads release-specific coverage data

Coverage Reports

Viewing Coverage

  1. Codecov Dashboard: Visit your repository on codecov.io
  2. GitHub PR Comments: Codecov automatically comments on pull requests
  3. GitHub Status Checks: Coverage status appears in PR checks
  4. Local HTML Reports: Generated in htmlcov/ directory after running tests

Coverage Flags

The integration uses several flags to organize coverage data:

  • unittests: Unit test coverage
  • integration: Integration test coverage
  • performance: Performance test coverage
  • release: Release build coverage
  • OS flags: ubuntu-latest, macos-latest, windows-latest
  • Python version flags: python3.8, python3.9, etc.

Understanding Coverage Reports

Project Coverage

  • Overall percentage of code covered by tests
  • Trend analysis showing coverage changes over time
  • File-by-file breakdown of coverage percentages

Patch Coverage

  • New code coverage for pull requests
  • Line-by-line analysis of what's covered
  • Suggestions for improving coverage

Component Coverage

  • Module-specific targets for different parts of the codebase
  • Individual status checks for each component
  • Focused improvement recommendations

Best Practices

Writing Tests for Coverage

  1. Aim for 80%+ overall coverage
  2. Focus on critical paths first
  3. Test edge cases and error conditions
  4. Mock external dependencies appropriately

Improving Coverage

  1. Identify uncovered lines using coverage reports
  2. Add tests for missing scenarios
  3. Remove dead code that can't be covered
  4. Use # pragma: no cover for intentionally uncovered code

Coverage Exclusions

The following are excluded from coverage:

  • Test files (tests/)
  • Documentation (docs/)
  • Build scripts (scripts/)
  • Package metadata (setup.py, __main__.py)
  • Generated files (build/, dist/)

Troubleshooting

Common Issues

Coverage Not Uploading

  • Check that CODECOV_TOKEN is set correctly
  • Verify the coverage.xml file is generated
  • Check GitHub Actions logs for upload errors

Low Coverage Warnings

  • Review uncovered lines in Codecov dashboard
  • Add tests for critical uncovered code
  • Consider adjusting coverage targets if appropriate

Status Check Failures

  • Check if coverage dropped below thresholds
  • Review the specific component that failed
  • Add tests to bring coverage back up

Getting Help

  1. Codecov Documentation: docs.codecov.com
  2. GitHub Issues: Report integration issues
  3. Coverage Reports: Use detailed reports to identify gaps

Monitoring and Maintenance

Regular Tasks

  1. Review coverage trends monthly
  2. Update coverage targets as codebase matures
  3. Clean up excluded files list periodically
  4. Monitor component coverage for balance

Coverage Goals

  • Short-term: Maintain 80%+ overall coverage
  • Medium-term: Achieve 85%+ for core components
  • Long-term: Establish 90%+ coverage for critical paths

Integration Benefits

With Codecov properly configured, you get:

✅ Automated coverage reporting on every commit
✅ Pull request coverage analysis with detailed feedback
✅ Historical coverage tracking and trend analysis
✅ Component-based coverage goals for focused improvement
✅ Integration with GitHub status checks for quality gates
✅ Visual coverage reports with line-by-line analysis

This ensures LaxyFile maintains high code quality and comprehensive test coverage across all components and platforms.