218 lines
6.4 KiB
Markdown
218 lines
6.4 KiB
Markdown
---
|
|
# agentskills.io specification v1.0
|
|
name: "test-backend-coverage"
|
|
version: "1.0.0"
|
|
description: "Run Go backend tests with coverage analysis and threshold validation (minimum 85%)"
|
|
author: "Charon Project"
|
|
license: "MIT"
|
|
tags:
|
|
- "testing"
|
|
- "coverage"
|
|
- "go"
|
|
- "backend"
|
|
- "validation"
|
|
compatibility:
|
|
os:
|
|
- "linux"
|
|
- "darwin"
|
|
shells:
|
|
- "bash"
|
|
requirements:
|
|
- name: "go"
|
|
version: ">=1.23"
|
|
optional: false
|
|
- name: "python3"
|
|
version: ">=3.8"
|
|
optional: false
|
|
environment_variables:
|
|
- name: "CHARON_ENCRYPTION_KEY"
|
|
description: "Encryption key for backend test runtime. Auto-generated ephemerally by the script if missing/invalid."
|
|
default: "(auto-generated for test run)"
|
|
required: false
|
|
- name: "CHARON_MIN_COVERAGE"
|
|
description: "Minimum coverage percentage required (overrides default)"
|
|
default: "85"
|
|
required: false
|
|
- name: "CPM_MIN_COVERAGE"
|
|
description: "Alternative name for minimum coverage threshold (legacy)"
|
|
default: "85"
|
|
required: false
|
|
- name: "PERF_MAX_MS_GETSTATUS_P95"
|
|
description: "Maximum P95 latency for GetStatus endpoint (ms)"
|
|
default: "25ms"
|
|
required: false
|
|
- name: "PERF_MAX_MS_GETSTATUS_P95_PARALLEL"
|
|
description: "Maximum P95 latency for parallel GetStatus calls (ms)"
|
|
default: "50ms"
|
|
required: false
|
|
- name: "PERF_MAX_MS_LISTDECISIONS_P95"
|
|
description: "Maximum P95 latency for ListDecisions endpoint (ms)"
|
|
default: "75ms"
|
|
required: false
|
|
parameters:
|
|
- name: "verbose"
|
|
type: "boolean"
|
|
description: "Enable verbose test output"
|
|
default: "false"
|
|
required: false
|
|
outputs:
|
|
- name: "coverage.txt"
|
|
type: "file"
|
|
description: "Go coverage profile in text format"
|
|
path: "backend/coverage.txt"
|
|
- name: "coverage_summary"
|
|
type: "stdout"
|
|
description: "Summary of coverage statistics and validation result"
|
|
metadata:
|
|
category: "test"
|
|
subcategory: "coverage"
|
|
execution_time: "medium"
|
|
risk_level: "low"
|
|
ci_cd_safe: true
|
|
requires_network: false
|
|
idempotent: true
|
|
---
|
|
|
|
# Test Backend Coverage
|
|
|
|
## Overview
|
|
|
|
Executes the Go backend test suite with race detection enabled, generates a coverage profile, filters excluded packages, and validates that the total coverage meets or exceeds the configured threshold (default: 85%).
|
|
|
|
This skill is designed for continuous integration and pre-commit hooks to ensure code quality standards are maintained.
|
|
|
|
## Prerequisites
|
|
|
|
- Go 1.23 or higher installed and in PATH
|
|
- Python 3.8 or higher installed and in PATH
|
|
- Backend dependencies installed (`cd backend && go mod download`)
|
|
- Write permissions in `backend/` directory (for coverage.txt)
|
|
|
|
## Usage
|
|
|
|
### Basic Usage
|
|
|
|
Run with default settings (85% minimum coverage):
|
|
|
|
```bash
|
|
cd /path/to/charon
|
|
.github/skills/scripts/skill-runner.sh test-backend-coverage
|
|
```
|
|
|
|
### Custom Coverage Threshold
|
|
|
|
Set a custom minimum coverage percentage:
|
|
|
|
```bash
|
|
export CHARON_MIN_COVERAGE=90
|
|
.github/skills/scripts/skill-runner.sh test-backend-coverage
|
|
```
|
|
|
|
### CI/CD Integration
|
|
|
|
For use in GitHub Actions or other CI/CD pipelines:
|
|
|
|
```yaml
|
|
- name: Run Backend Tests with Coverage
|
|
run: .github/skills/scripts/skill-runner.sh test-backend-coverage
|
|
env:
|
|
CHARON_MIN_COVERAGE: 85
|
|
```
|
|
|
|
## Parameters
|
|
|
|
| Parameter | Type | Required | Default | Description |
|
|
|-----------|------|----------|---------|-------------|
|
|
| verbose | boolean | No | false | Enable verbose test output (-v flag) |
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Required | Default | Description |
|
|
|----------|----------|---------|-------------|
|
|
| CHARON_ENCRYPTION_KEY | No | auto-generated for test run | Backend test encryption key. If missing/invalid, an ephemeral 32-byte base64 key is generated for the run. |
|
|
| CHARON_MIN_COVERAGE | No | 85 | Minimum coverage percentage required for success |
|
|
| CPM_MIN_COVERAGE | No | 85 | Legacy name for minimum coverage (fallback) |
|
|
| PERF_MAX_MS_GETSTATUS_P95 | No | 25ms | Max P95 latency for GetStatus endpoint |
|
|
| PERF_MAX_MS_GETSTATUS_P95_PARALLEL | No | 50ms | Max P95 latency for parallel GetStatus |
|
|
| PERF_MAX_MS_LISTDECISIONS_P95 | No | 75ms | Max P95 latency for ListDecisions endpoint |
|
|
|
|
## Outputs
|
|
|
|
### Success Exit Code
|
|
- **0**: All tests passed and coverage meets threshold
|
|
|
|
### Error Exit Codes
|
|
- **1**: Coverage below threshold or coverage file generation failed
|
|
- **Non-zero**: Tests failed or other error occurred
|
|
|
|
### Output Files
|
|
- **backend/coverage.txt**: Go coverage profile (text format)
|
|
|
|
### Console Output
|
|
Example output:
|
|
```
|
|
Filtering excluded packages from coverage report...
|
|
Coverage filtering complete
|
|
total: (statements) 87.4%
|
|
Computed coverage: 87.4% (minimum required 85%)
|
|
Coverage requirement met
|
|
```
|
|
|
|
## Examples
|
|
|
|
### Example 1: Basic Execution
|
|
|
|
```bash
|
|
.github/skills/scripts/skill-runner.sh test-backend-coverage
|
|
```
|
|
|
|
### Example 2: Higher Coverage Threshold
|
|
|
|
```bash
|
|
export CHARON_MIN_COVERAGE=90
|
|
.github/skills/scripts/skill-runner.sh test-backend-coverage
|
|
```
|
|
|
|
## Excluded Packages
|
|
|
|
The following packages are excluded from coverage analysis:
|
|
- `github.com/Wikid82/charon/backend/cmd/api` - API server entrypoint
|
|
- `github.com/Wikid82/charon/backend/cmd/seed` - Database seeding tool
|
|
- `github.com/Wikid82/charon/backend/internal/logger` - Logging infrastructure
|
|
- `github.com/Wikid82/charon/backend/internal/metrics` - Metrics infrastructure
|
|
- `github.com/Wikid82/charon/backend/internal/trace` - Tracing infrastructure
|
|
- `github.com/Wikid82/charon/backend/integration` - Integration test utilities
|
|
|
|
## Error Handling
|
|
|
|
### Common Errors
|
|
|
|
#### Error: coverage file not generated by go test
|
|
**Solution**: Review test output for failures; fix failing tests
|
|
|
|
#### Error: go tool cover failed or timed out
|
|
**Solution**: Clear Go cache and re-run tests
|
|
|
|
#### Error: Coverage X% is below required Y%
|
|
**Solution**: Add tests for uncovered code paths or adjust threshold
|
|
|
|
## Related Skills
|
|
|
|
- test-backend-unit - Fast unit tests without coverage
|
|
- security-check-govulncheck - Go vulnerability scanning
|
|
- utility-cache-clear-go - Clear Go build cache
|
|
|
|
## Notes
|
|
|
|
- **Race Detection**: Always runs with `-race` flag enabled (adds ~30% overhead)
|
|
- **Coverage Filtering**: Excluded packages are defined in the script itself
|
|
- **Python Dependency**: Uses Python for decimal-precision coverage comparison
|
|
- **Timeout Protection**: Coverage generation has a 60-second timeout
|
|
- **Idempotency**: Safe to run multiple times; cleans up old coverage files
|
|
|
|
---
|
|
|
|
**Last Updated**: 2025-12-20
|
|
**Maintained by**: Charon Project Team
|
|
**Source**: `scripts/go-test-coverage.sh`
|