Eve library

Code Coverage Documentation

Other

Revision 1

On this page

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

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 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#

text
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#

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.