Charon/.github/skills/test-frontend-coverage.SKILL.md

---
# agentskills.io specification v1.0
name: "test-frontend-coverage"
version: "1.0.0"
description: "Run frontend tests with coverage analysis and threshold validation (minimum 85%)"
author: "Charon Project"
license: "MIT"
tags:
  - "testing"
  - "coverage"
  - "frontend"
  - "vitest"
  - "validation"
compatibility:
  os:
    - "linux"
    - "darwin"
  shells:
    - "bash"
requirements:
  - name: "node"
    version: ">=18.0"
    optional: false
  - name: "npm"
    version: ">=9.0"
    optional: false
  - name: "python3"
    version: ">=3.8"
    optional: false
environment_variables:
  - 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
parameters:
  - name: "verbose"
    type: "boolean"
    description: "Enable verbose test output"
    default: "false"
    required: false
outputs:
  - name: "coverage-summary.json"
    type: "file"
    description: "JSON coverage summary generated by Vitest"
    path: "frontend/coverage/coverage-summary.json"
  - 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 Frontend Coverage

## Overview

Executes the frontend test suite using Vitest with coverage enabled, generates a JSON coverage summary, and validates that the total statements 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

- Node.js 18.0 or higher installed and in PATH
- npm 9.0 or higher installed and in PATH
- Python 3.8 or higher installed and in PATH
- Frontend dependencies installed (`cd frontend && npm install`)
- Write permissions in `frontend/coverage/` directory

## Usage

### Basic Usage

Run with default settings (85% minimum coverage):

```bash
cd /path/to/charon
.github/skills/scripts/skill-runner.sh test-frontend-coverage
```

### Custom Coverage Threshold

Set a custom minimum coverage percentage:

```bash
export CHARON_MIN_COVERAGE=90
.github/skills/scripts/skill-runner.sh test-frontend-coverage
```

### CI/CD Integration

For use in GitHub Actions or other CI/CD pipelines:

```yaml
- name: Run Frontend Tests with Coverage
  run: .github/skills/scripts/skill-runner.sh test-frontend-coverage
  env:
    CHARON_MIN_COVERAGE: 85
```

## Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| verbose   | boolean | No    | false   | Enable verbose test output |

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| CHARON_MIN_COVERAGE | No | 85 | Minimum coverage percentage required for success |
| CPM_MIN_COVERAGE | No | 85 | Legacy name for minimum coverage (fallback) |

## 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
- **frontend/coverage/coverage-summary.json**: Vitest coverage summary (JSON format)
- **frontend/coverage/index.html**: HTML coverage report (viewable in browser)

### Console Output
Example output:
```
Computed frontend coverage: 87.5% (minimum required 85%)
Frontend coverage requirement met
```

## Examples

### Example 1: Basic Execution

```bash
.github/skills/scripts/skill-runner.sh test-frontend-coverage
```

### Example 2: Higher Coverage Threshold

```bash
export CHARON_MIN_COVERAGE=90
.github/skills/scripts/skill-runner.sh test-frontend-coverage
```

### Example 3: View HTML Coverage Report

```bash
.github/skills/scripts/skill-runner.sh test-frontend-coverage
open frontend/coverage/index.html  # macOS
xdg-open frontend/coverage/index.html  # Linux
```

## Error Handling

### Common Errors

#### Error: Coverage summary file not found
**Solution**: Check that Vitest is configured with `--coverage` and `--reporter=json-summary`

#### Error: Frontend coverage X% is below required Y%
**Solution**: Add tests for uncovered components or adjust threshold

#### Error: npm ci failed
**Solution**: Clear node_modules and package-lock.json, then reinstall dependencies

## Related Skills

- test-frontend-unit - Fast unit tests without coverage
- test-backend-coverage - Backend Go coverage tests
- utility-cache-clear-go - Clear build caches

## Notes

- **Vitest Configuration**: Uses istanbul coverage provider for JSON summary reports
- **Coverage Directory**: Coverage artifacts are written to `frontend/coverage/`
- **Python Dependency**: Uses Python for decimal-precision coverage comparison
- **Idempotency**: Safe to run multiple times; cleans up old coverage files
- **CI Mode**: Runs `npm ci` in CI environments to ensure clean installs

---

**Last Updated**: 2025-12-20
**Maintained by**: Charon Project Team
**Source**: `scripts/frontend-test-coverage.sh`