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#
# 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 librariessrc/hooks/**/*.{js,ts,jsx,tsx}- React hookssrc/design-system/**/*.{js,ts,jsx,tsx}- Design system componentssrc/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 frameworksrc/services/**: Integration tests + E2E tests verify API integration
Best Practices#
1. Write Testable Code#
// ❌ 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#
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#
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#
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#
-
Run coverage report:
bashnpm run test:coverage -
Open HTML report:
bashopen coverage/index.html -
Identify uncovered lines (highlighted in red)
-
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#
# 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:
# 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):


Codecov Badges (dynamic, auto-updating):
[](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:
# 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:
- Codecov Dashboard: Automatic graphs and charts
- Local Data: Import
coverage-trend.jsonto spreadsheet - 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:
- 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:
- Runs Tests: Executes full test suite with coverage
- Generates Report: Creates detailed coverage data
- 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
- Checks Thresholds: Fails PR if coverage below 70%
- Shows Diff: Codecov shows coverage impact of changes
PR Comment Example:
## 📊 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:
- Sign up: Visit codecov.io and connect GitHub
- Get Token: Copy project token from Codecov dashboard
- Add Secret: Add
CODECOV_TOKENto GitHub repository secrets - 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#
# 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:
- Run
npm run coverage:report - Open
coverage/index.html - Find files with red highlights
- Add tests for uncovered code
Coverage Not Generating#
Problem: No coverage report created
Solution:
- Check Vitest is installed:
npm list vitest - Verify config:
cat vitest.config.ts - Run with verbose:
npm run test:coverage -- --reporter=verbose
Incorrect Coverage Numbers#
Problem: Coverage shows 100% but code isn't fully tested
Solution:
- Check coverage include/exclude patterns
- Verify test files aren't counted as source files
- Review
vitest.config.tscoverage settings
Threshold Failures#
Problem: Tests pass but coverage check fails
Solution:
# 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)#
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
reporterarray - 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:
/* 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.