onvif-go/docs/testing/COVERAGE_SETUP.md

Code Quality & Coverage Setup Guide

This guide explains how to set up CodeCov and SonarCloud integration for the onvif-go project.

Overview

The project uses two code quality platforms:

• CodeCov - Code coverage tracking and visualization
• SonarCloud - Code quality, security vulnerabilities, and technical debt analysis

CodeCov Integration

What is CodeCov?

CodeCov provides code coverage reports and metrics to help ensure your tests cover your codebase effectively.

Setup Steps

1. Sign up for CodeCov

   • Go to https://codecov.io/
   • Sign in with your GitHub account
   • Authorize CodeCov to access your repositories

2. Add Repository

   • Navigate to https://codecov.io/gh/0x524a
   • Click "Add new repository"
   • Select onvif-go from the list

3. Get Upload Token

   • In the repository settings on CodeCov, find your upload token
   • Copy the token (format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)

4. Add Secret to GitHub

   • Go to https://github.com/0x524a/onvif-go/settings/secrets/actions
   • Click "New repository secret"
   • Name: CODECOV_TOKEN
   • Value: Paste your CodeCov upload token
   • Click "Add secret"

Configuration Files

The following files configure CodeCov:

.codecov.yml - CodeCov configuration

codecov:
  require_ci_to_pass: yes

coverage:
  precision: 2
  round: down
  range: "70...100"
  status:
    project:
      default:
        target: 45%        # Current coverage target
        threshold: 1%      # Allow 1% decrease
    patch:
      default:
        target: 80%        # New code should have 80% coverage
        threshold: 5%

Key Settings:

• Project target: 45% (matches current coverage)
• Patch target: 80% (new code should be well-tested)
• Threshold: 1% decrease allowed to prevent flaky failures
• Excluded: Examples, commands, test files

Viewing Reports

After setup, coverage reports will be available at:

• Main dashboard: https://codecov.io/gh/0x524a/onvif-go
• Pull request comments will show coverage changes
• Commit-level coverage available in GitHub checks

Coverage Badges

The README includes a CodeCov badge:

[![codecov](https://codecov.io/gh/0x524a/onvif-go/branch/master/graph/badge.svg)](https://codecov.io/gh/0x524a/onvif-go)

SonarCloud Integration

What is SonarCloud?

SonarCloud provides continuous code quality analysis, detecting bugs, vulnerabilities, code smells, and security hotspots.

Setup Steps

1. Sign up for SonarCloud

   • Go to https://sonarcloud.io/
   • Click "Log in" and sign in with GitHub
   • Authorize SonarCloud to access your repositories

2. Import Repository

   • Click the "+" button in the top right
   • Select "Analyze new project"
   • Choose 0x524a/onvif-go
   • Click "Set Up"

3. Configure Organization

   • Organization key: 0x524a
   • Project key: 0x524a_onvif-go
   • These are already set in sonar-project.properties

4. Get Authentication Token

   • Go to https://sonarcloud.io/account/security
   • Generate a new token
   • Name it "GitHub Actions - onvif-go"
   • Copy the token

5. Add Secret to GitHub

   • Go to https://github.com/0x524a/onvif-go/settings/secrets/actions
   • Click "New repository secret"
   • Name: SONAR_TOKEN
   • Value: Paste your SonarCloud token
   • Click "Add secret"

Configuration Files

sonar-project.properties - SonarCloud configuration

sonar.projectKey=0x524a_onvif-go
sonar.organization=0x524a
sonar.projectName=onvif-go

# Source and test locations
sonar.sources=.
sonar.tests=.
sonar.test.inclusions=**/*_test.go

# Coverage report
sonar.go.coverage.reportPaths=coverage.out

# Exclusions
sonar.exclusions=**/vendor/**,**/*_test.go,**/examples/**,**/cmd/**
sonar.coverage.exclusions=**/cmd/**,**/examples/**,**/*_test.go

Key Settings:

• Language: Go
• Coverage: Uses Go's native coverage.out format
• Exclusions: Examples, commands, and test files excluded from analysis
• Source encoding: UTF-8

Quality Gates

SonarCloud will check:

• Bugs: Serious coding errors
• Vulnerabilities: Security issues
• Code Smells: Maintainability issues
• Coverage: Test coverage percentage
• Duplications: Copy-pasted code
• Security Hotspots: Potential security risks

Viewing Reports

After setup, reports will be available at:

• Main dashboard: https://sonarcloud.io/project/overview?id=0x524a_onvif-go
• Pull request decoration shows issues inline
• Quality gate status in GitHub checks

SonarCloud Badges

The README includes SonarCloud badges:

[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=0x524a_onvif-go&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=0x524a_onvif-go)

Additional badges available:

[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=0x524a_onvif-go&metric=bugs)](https://sonarcloud.io/summary/new_code?id=0x524a_onvif-go)
[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=0x524a_onvif-go&metric=code_smells)](https://sonarcloud.io/summary/new_code?id=0x524a_onvif-go)
[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=0x524a_onvif-go&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=0x524a_onvif-go)
[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=0x524a_onvif-go&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=0x524a_onvif-go)

GitHub Actions Workflows

Coverage Workflow

File: .github/workflows/coverage.yml

Runs on:

• Push to master/main/develop branches
• Pull requests to master/main/develop

Steps:

1. Checkout code with full history (required for SonarCloud)
2. Set up Go 1.21
3. Install dependencies
4. Run tests with race detector and coverage
5. Upload coverage to CodeCov
6. Run SonarCloud analysis
7. Generate HTML coverage report
8. Archive coverage artifacts

Test Workflow

File: .github/workflows/test.yml

Runs on:

• Push to master/main/develop branches
• Pull requests to master/main/develop

Matrix testing:

• Operating Systems: Ubuntu, macOS, Windows
• Go Versions: 1.21, 1.22, 1.23

Includes:

• Unit tests with race detector
• Build verification
• golangci-lint code quality checks

Required GitHub Secrets

Set up these secrets in your GitHub repository:

Secret Name	Source	Purpose
CODECOV_TOKEN	CodeCov dashboard	Upload coverage reports
SONAR_TOKEN	SonarCloud account security	Run code quality analysis

How to Add Secrets

1. Go to repository settings: https://github.com/0x524a/onvif-go/settings/secrets/actions
2. Click "New repository secret"
3. Enter name and value
4. Click "Add secret"

Note: GITHUB_TOKEN is automatically provided by GitHub Actions and doesn't need to be added manually.

Local Testing

Run Coverage Locally

# Generate coverage report
go test -v -race -covermode=atomic -coverprofile=coverage.out ./...

# View coverage in terminal
go tool cover -func=coverage.out

# Generate HTML report
go tool cover -html=coverage.out -o coverage.html

# Open in browser
open coverage.html  # macOS
xdg-open coverage.html  # Linux
start coverage.html  # Windows

Test CodeCov Upload (requires token)

# Install codecov CLI
go install github.com/codecov/codecov-cli@latest

# Upload coverage
codecov upload-process --file coverage.out --token YOUR_CODECOV_TOKEN

Run SonarCloud Locally (requires Docker)

# Using sonar-scanner Docker image
docker run --rm \
  -e SONAR_HOST_URL="https://sonarcloud.io" \
  -e SONAR_TOKEN="YOUR_SONAR_TOKEN" \
  -v "$(pwd):/usr/src" \
  sonarsource/sonar-scanner-cli

Troubleshooting

CodeCov Issues

Problem: Coverage upload fails

Error: No coverage reports found

Solution:

• Ensure coverage.out is generated: go test -coverprofile=coverage.out ./...
• Check the file exists: ls -la coverage.out
• Verify the workflow has the correct path

Problem: Coverage percentage is 0%

Coverage: 0.00%

Solution:

• Ensure tests are actually running: go test -v ./...
• Check coverage mode is set: -covermode=atomic
• Verify exclusions in .codecov.yml aren't too broad

SonarCloud Issues

Problem: Analysis fails with authentication error

Error: Invalid authentication token

Solution:

• Regenerate token in SonarCloud account security
• Update SONAR_TOKEN secret in GitHub
• Ensure token has project analysis permissions

Problem: No coverage data in SonarCloud

Warning: No coverage information

Solution:

• Verify coverage.out exists before SonarCloud scan
• Check sonar.go.coverage.reportPaths=coverage.out in properties
• Ensure coverage file is in Go format (not HTML)

GitHub Actions Issues

Problem: Workflow doesn't run

No checks ran on this commit

Solution:

• Check workflow triggers match your branch name
• Verify YAML syntax is valid
• Look at Actions tab for error messages

Problem: Secrets not found

Error: CODECOV_TOKEN is not set

Solution:

• Add secret in repository settings
• Check secret name matches exactly (case-sensitive)
• Verify you have repository admin permissions

Coverage Goals

Current Status

• Overall Coverage: 44.6%
• Device Management: 100% API implementation
• New Code: 88-100% per file

Improvement Plan

1. Short-term (Target: 50%)

   • Add integration tests for Media service
   • Expand PTZ control testing
   • Test error scenarios more thoroughly

2. Medium-term (Target: 60%)

   • Add end-to-end tests with mock camera
   • Test concurrent operations
   • Expand discovery testing

3. Long-term (Target: 70%+)

   • Integration tests with real devices
   • Stress testing and edge cases
   • Performance benchmarks

Coverage Exclusions

The following are excluded from coverage metrics:

• Examples (examples/) - Demonstration code
• Commands (cmd/) - CLI tools
• Server (server/) - Mock server implementation
• Test utilities (testing/) - Test helpers
• Test files (*_test.go) - Test code itself

Best Practices

Writing Testable Code

1. Use interfaces for dependencies
2. Inject dependencies via constructors
3. Keep functions focused - single responsibility
4. Avoid global state - use struct methods
5. Mock external services - don't rely on real cameras for unit tests

Maintaining Coverage

1. Write tests first (TDD) when adding features
2. Test happy path and errors for each function
3. Use table-driven tests for multiple scenarios
4. Mock HTTP clients with httptest
5. Check coverage locally before pushing

Code Quality

1. Fix issues early - address SonarCloud findings promptly
2. Keep functions small - easier to test and maintain
3. Document public APIs - helps maintain quality
4. Use golangci-lint - catches issues before they reach SonarCloud
5. Review coverage reports - identify untested code paths

Monitoring & Reporting

Regular Checks

• Weekly: Review coverage trends on CodeCov
• Per PR: Check coverage changes and SonarCloud findings
• Monthly: Review quality gate trends on SonarCloud
• Quarterly: Update coverage targets based on progress

Metrics to Track

Metric	Tool	Target	Current
Overall Coverage	CodeCov	45%	44.6%
New Code Coverage	CodeCov	80%	88-100%
Quality Gate	SonarCloud	Pass	TBD
Code Smells	SonarCloud	<50	TBD
Security Rating	SonarCloud	A	TBD
Maintainability	SonarCloud	A	TBD

References

• CodeCov Documentation: https://docs.codecov.com/
• SonarCloud Documentation: https://docs.sonarcloud.io/
• GitHub Actions: https://docs.github.com/en/actions
• Go Testing: https://pkg.go.dev/testing
• Go Coverage: https://go.dev/blog/cover

Support

If you encounter issues with the coverage setup:

1. Check the troubleshooting section above
2. Review GitHub Actions logs in the repository
3. Check CodeCov/SonarCloud status pages
4. Open an issue on GitHub with:
   • Error message
   • Workflow run link
   • Steps to reproduce

---

Setup Status: ⚠️ Requires manual configuration

Next Steps:

1. ✅ Configuration files created
2. ⏳ Sign up for CodeCov and SonarCloud
3. ⏳ Add repository secrets to GitHub
4. ⏳ Push changes to trigger first workflow run
5. ⏳ Verify badges appear in README

Once setup is complete, coverage and quality metrics will be automatically tracked for all commits and pull requests!