# Code Coverage Documentation

## Overview

This project uses Vitest with v8 coverage provider to track code coverage. The coverage configuration ensures high code quality with a minimum threshold of 70% across all metrics.

## Quick Start

```bash
# Run tests with coverage
npm run test:coverage

# Watch mode with coverage
npm run test:coverage:watch

# UI mode with coverage
npm run test:coverage:ui

# Generate HTML coverage report
npm run coverage:report

# Quick coverage check
npm run coverage:check

# Generate coverage badges
npm run coverage:badges

# Track coverage trends
npm run coverage:trend
npm run coverage:trend -- --report  # with trend report
```

## Coverage Reports

After running tests with coverage, reports are generated in multiple formats:

### Console Output
- **text**: Detailed console table showing coverage per file
- **text-summary**: Brief summary with overall percentages

### HTML Report
- **Location**: `./coverage/index.html`
- **Usage**: Open in browser to explore coverage interactively
- **Features**: File-by-file breakdown, uncovered lines highlighted

### Machine-Readable Formats
- **json**: `./coverage/coverage-final.json` - Complete coverage data
- **json-summary**: `./coverage/coverage-summary.json` - Summary data
- **lcov**: `./coverage/lcov.info` - For CI/CD integration

## Coverage Thresholds

All code must meet minimum coverage thresholds:

| Metric | Threshold |
|--------|-----------|
| Lines | 70% |
| Functions | 70% |
| Branches | 70% |
| Statements | 70% |

### What This Means

- **Lines**: Percentage of executable lines that are tested
- **Functions**: Percentage of functions that are called in tests
- **Branches**: Percentage of conditional branches (if/else) that are tested
- **Statements**: Percentage of statements that are executed

### Threshold Enforcement

- Tests will fail if coverage drops below 70% for any metric
- Use this to prevent untested code from being merged
- Thresholds apply globally, not per-file

## Coverage Scope

### Included Files

Coverage tracking includes:
- `src/lib/**/*.{js,ts,jsx,tsx}` - Utility libraries
- `src/hooks/**/*.{js,ts,jsx,tsx}` - React hooks
- `src/design-system/**/*.{js,ts,jsx,tsx}` - Design system components
- `src/components/**/*.{js,ts,jsx,tsx}` - React components

### Excluded Files

The following are excluded from coverage with documented rationale:

| Pattern | Reason |
|---------|--------|
| `*.test.{js,ts,jsx,tsx}`, `*.spec.{js,ts,jsx,tsx}` | Test files test other code, not themselves |
| `*.stories.{js,ts,jsx,tsx}` | Storybook stories are visual documentation, not business logic |
| `__tests__/**`, `__mocks__/**`, `fixtures/**` | Test infrastructure and fixtures |
| `*.config.{js,ts}`, `*.d.ts` | Configuration and type definitions |
| `src/app/**` | Next.js app router routes - tested via E2E, not unit tests |
| `src/components/metaverse/**` | Experimental 3D/WebXR prototypes - pending stabilization |
| `src/i18n/**` | Translation strings and locale configuration |
| `src/services/**` | API client wrappers - mocked in tests, real calls tested in E2E |
| `src/styles/**` | CSS/styling - visual testing via Storybook/Chromatic |

**Note**: Excluded paths should still be tested via alternative means:
- `src/app/**`: Playwright E2E tests in `/tests/`
- `src/components/metaverse/**`: Manual QA + future WebXR testing framework
- `src/services/**`: Integration tests + E2E tests verify API integration

## Best Practices

### 1. Write Testable Code

```typescript
// ❌ Hard to test
function processUser() {
  const user = fetchUserFromGlobalState();
  const data = transformUser(user);
  saveToDatabase(data);
}

// ✅ Easy to test
function transformUser(user: User): TransformedUser {
  return {
    id: user.id,
    name: user.name.toUpperCase(),
  };
}
```

### 2. Test Edge Cases

```typescript
describe('calculateDiscount', () => {
  it('handles zero price', () => {
    expect(calculateDiscount(0, 10)).toBe(0);
  });

  it('handles 100% discount', () => {
    expect(calculateDiscount(100, 100)).toBe(0);
  });

  it('handles negative values', () => {
    expect(calculateDiscount(-10, 10)).toBe(0);
  });
});
```

### 3. Cover All Branches

```typescript
function getUserStatus(user: User): string {
  if (user.isPremium) {
    return 'premium'; // ✅ Test this
  } else if (user.isActive) {
    return 'active'; // ✅ Test this too
  } else {
    return 'inactive'; // ✅ And this
  }
}
```

### 4. Test Error Paths

```typescript
describe('api.fetchData', () => {
  it('succeeds with valid data', async () => {
    // Happy path
  });

  it('handles network errors', async () => {
    // Error path ✅
  });

  it('handles invalid responses', async () => {
    // Error path ✅
  });
});
```

## Improving Coverage

### Find Untested Code

1. **Run coverage report**:
   ```bash
   npm run test:coverage
   ```

2. **Open HTML report**:
   ```bash
   open coverage/index.html
   ```

3. **Identify uncovered lines** (highlighted in red)

4. **Write tests** for those lines

### Coverage Gaps

Common areas that often lack coverage:
- Error handling paths
- Edge cases and boundary conditions
- Async operation failures
- User input validation
- Conditional logic branches

### Incremental Improvement

```bash
# Check current coverage
npm run coverage:check

# Write tests for uncovered code

# Verify improvement
npm run test:coverage
```

## Coverage Badges

Generate visual coverage badges for README:

```bash
# Generate local SVG badges
npm run coverage:badges

# Badges created in: coverage/badges/
# - lines.svg
# - statements.svg
# - functions.svg
# - branches.svg
# - overall.svg
```

### Using Badges in README

**Local Badges** (static, must be regenerated):
```markdown
![Lines](./web/coverage/badges/lines.svg)
![Statements](./web/coverage/badges/statements.svg)
```

**Codecov Badges** (dynamic, auto-updating):
```markdown
[![codecov](https://codecov.io/gh/USERNAME/REPO/branch/main/graph/badge.svg)](https://codecov.io/gh/USERNAME/REPO)
```

Codecov badges update automatically on each commit and provide:
- Click-through to detailed coverage reports
- Coverage percentage displayed in real-time
- Consistent styling with other project badges

## Coverage Trends

Track coverage changes over time:

```bash
# Track current coverage (stores in coverage-trend.json)
npm run coverage:trend

# Generate trend report
npm run coverage:trend -- --report
```

### Trend Data

- Tracks coverage metrics for each test run
- Stores last 100 entries with timestamps and git info
- Shows improvement or regression trends
- Generates markdown reports with historical data

### Trend Visualization

For visual trend analysis:
1. **Codecov Dashboard**: Automatic graphs and charts
2. **Local Data**: Import `coverage-trend.json` to spreadsheet
3. **Custom Tools**: Use gnuplot, matplotlib, or similar

## CI/CD Integration

### GitHub Actions

A comprehensive coverage workflow runs on every PR and push to main/master:

**Location**: `.github/workflows/web-coverage.yml`

**Features**:
- Runs tests with coverage on every PR
- Uploads coverage to Codecov for trend tracking
- Posts coverage summary as PR comment
- Checks coverage thresholds (fails if below 70%)
- Uploads coverage artifacts for download

**Workflow Triggers**:
- Pull requests to main/master
- Pushes to main/master
- Changes to web source files

**Codecov Integration**:
```yaml
- uses: codecov/codecov-action@v4
  with:
    token: ${{ secrets.CODECOV_TOKEN }}
    files: ./coverage/lcov.info
    flags: web-client
```

### Pull Request Checks

On every PR, the coverage workflow:

1. **Runs Tests**: Executes full test suite with coverage
2. **Generates Report**: Creates detailed coverage data
3. **Posts Comment**: Adds coverage table to PR with:
   - Coverage percentage for each metric
   - Color-coded indicators (🟢 ≥80%, 🟡 ≥70%, 🔴 <70%)
   - Covered/total counts for each metric
   - Link to detailed Codecov report
4. **Checks Thresholds**: Fails PR if coverage below 70%
5. **Shows Diff**: Codecov shows coverage impact of changes

**PR Comment Example**:
```markdown
## 📊 Code Coverage Report

| Metric | Coverage | Covered | Total |
|--------|----------|---------|-------|
| Lines | 🟢 85.32% | 1234 | 1447 |
| Statements | 🟢 84.91% | 1456 | 1715 |
| Functions | 🟡 72.45% | 345 | 476 |
| Branches | 🟡 71.23% | 234 | 328 |

✅ All coverage thresholds met!
```

### Codecov Setup

To enable Codecov integration:

1. **Sign up**: Visit [codecov.io](https://codecov.io/) and connect GitHub
2. **Get Token**: Copy project token from Codecov dashboard
3. **Add Secret**: Add `CODECOV_TOKEN` to GitHub repository secrets
4. **Verify**: Push code and check Codecov dashboard

Codecov provides:
- Historical coverage trends with graphs
- File-by-file coverage analysis
- Pull request coverage diff
- Coverage sunburst charts
- Team analytics and insights

## Viewing Coverage

### Local Development

```bash
# Generate and view HTML report
npm run coverage:report
open coverage/index.html
```

### Coverage Report Structure

```
coverage/
├── index.html           # Main coverage report
├── lcov-report/         # HTML report files
│   ├── index.html
│   ├── src/
│   └── ...
├── coverage-final.json  # Complete coverage data
├── coverage-summary.json # Summary statistics
└── lcov.info           # LCOV format for CI
```

## Troubleshooting

### Low Coverage Warnings

**Problem**: Tests pass but coverage is below 70%

**Solution**:
1. Run `npm run coverage:report`
2. Open `coverage/index.html`
3. Find files with red highlights
4. Add tests for uncovered code

### Coverage Not Generating

**Problem**: No coverage report created

**Solution**:
1. Check Vitest is installed: `npm list vitest`
2. Verify config: `cat vitest.config.ts`
3. Run with verbose: `npm run test:coverage -- --reporter=verbose`

### Incorrect Coverage Numbers

**Problem**: Coverage shows 100% but code isn't fully tested

**Solution**:
1. Check coverage include/exclude patterns
2. Verify test files aren't counted as source files
3. Review `vitest.config.ts` coverage settings

### Threshold Failures

**Problem**: Tests pass but coverage check fails

**Solution**:
```bash
# See which threshold failed
npm run test:coverage

# Output shows:
# ERROR: Coverage for lines (65%) does not meet threshold (70%)

# Add tests to improve coverage
```

## Configuration

### Vitest Config (`vitest.config.ts`)

```typescript
coverage: {
  provider: 'v8',
  reporter: ['text', 'html', 'json', 'lcov'],
  thresholds: {
    lines: 70,
    functions: 70,
    branches: 70,
    statements: 70,
  },
  // ... more config
}
```

### Customizing Coverage

To modify coverage settings, edit `vitest.config.ts`:

- **Change thresholds**: Adjust `thresholds.lines`, `functions`, etc.
- **Add reporters**: Add to `reporter` array
- **Include more files**: Add patterns to `include`
- **Exclude files**: Add patterns to `exclude`

## Resources

- [Vitest Coverage Documentation](https://vitest.dev/guide/coverage.html)
- [V8 Coverage Provider](https://vitest.dev/guide/coverage.html#coverage-providers)
- [Istanbul Coverage Reports](https://istanbul.js.org/)
- [LCOV Format](http://ltp.sourceforge.net/coverage/lcov.php)

## FAQ

### Q: Why 70% threshold?

A: 70% is a balance between quality and practicality:
- **60%**: Too low, allows too much untested code
- **70%**: Good balance, ensures most code is tested
- **80%+**: Ideal but can be difficult to maintain
- **100%**: Often impractical and not always valuable

### Q: What counts towards coverage?

A: Only source code files that match the `include` patterns and don't match `exclude` patterns.

### Q: Why exclude test files?

A: Test files should test source code, not be tested themselves. Including them inflates coverage numbers artificially.

### Q: Can I have different thresholds per file?

A: Yes, set `perFile: true` in coverage config, but global thresholds are often more practical.

### Q: How do I ignore specific lines?

A: Use coverage comments:
```typescript
/* c8 ignore next */
const unreachableCode = () => {};

/* c8 ignore start */
function debugOnly() {
  console.log('debug');
}
/* c8 ignore stop */
```

### Q: What's the difference between v8 and istanbul?

A:
- **v8**: Faster, uses V8 engine's native coverage
- **istanbul**: Slower, more configurable, industry standard

We use v8 for speed while maintaining accuracy.
