p3cov

Generate comprehensive HTML coverage reports from Jest test results with detailed visualizations, statistics, and insights.

✨ Features

• 📊 Comprehensive Coverage Statistics - Statements, branches, functions, and lines with visual indicators
• 🎯 Detailed File Analysis - Coverage breakdown by file and category (components, services, etc.)
• 🐌 Performance Insights - Identify slowest tests and suites
• ❌ Failed Test Reports - Detailed error messages with code context
• 📈 Coverage Distribution - Visual histogram showing coverage spread
• 🏆 Top/Bottom Files - Highlight best and worst covered files
• 🎨 Customizable Styling - Fully configurable colors, sections, and labels
• 📄 HTML Output - Fast, shareable report format
• 🌙 Dark Theme - Modern design

📦 Installation

Global Installation (Recommended)

npm install -g p3cov

Project Installation

npm install --save-dev p3cov

🚀 Quick Start

1. Run the command in your project directory:

   p3cov

2. First time? The tool will automatically create a p3cov.config.js file with default settings.

3. Customize the config to match your project structure and preferences.

4. Run again to generate your reports!

📖 Usage

Navigate to your project directory and run:

p3cov

The tool will:

• ✅ Check for p3cov.config.js in your current directory
• ✅ Create it automatically if missing (with sensible defaults)
• ✅ Run your Jest tests with coverage
• ✅ Generate a beautiful HTML report

Output

Reports are generated in your coverage/ directory:

• coverage-report.html - Interactive HTML report

⚙️ Configuration

On first run, p3cov.config.js is automatically created. Customize it for your project:

module.exports = {
  // Your Jest test command
  testCommand: 'npm test -- --coverage --coverageReporters=json --coverageReporters=html --json --outputFile=coverage/jest-results.json',
  
  paths: {
    // Set to 0 if config is in workspace root
    workspaceRootLevelsUp: 0,
    coverageDir: 'coverage',
  },
  
  labels: {
    title: 'My Project - Jest Coverage',
  },
  
  thresholds: {
    high: 80,    // >= 80% = green  
    medium: 50,  // >= 50% = yellow
  },
  
  // Customize colors, sections, and much more...
};

Key Settings

| Setting | Description | Default | |---------|-------------|---------| | testCommand | Jest command to run | npm test -- --coverage ... | | paths.workspaceRootLevelsUp | Levels up to workspace root | 0 | | paths.coverageDir | Coverage output directory | coverage | | thresholds.high | High coverage threshold | 80 | | thresholds.medium | Medium coverage threshold | 50 | | labels.title | Report title | Jest Coverage Report |

Customization Options

• 🎨 Colors - Full color scheme customization
• 📊 Sections - Choose which sections to include and their order
• 🏷️ Labels - Translate or customize all text
• 📈 Thresholds - Define your coverage quality levels
• 📁 Categories - Configure file categorization patterns
• ⚡ Display - Control what statistics to show

See the full configuration guide for all options.

📊 Report Contents

Your generated report includes:

📈 Overview

• Coverage Metrics - Statements, branches, functions, lines
• Test Summary - Total tests, suites, pass/fail counts
• Runtime Stats - Execution time and performance metrics

🎯 Detailed Analysis

• Coverage Distribution - Histogram of file coverage ranges
• Coverage by Category - Breakdown by file type (components, services, etc.)
• Top/Bottom Files - Best and worst covered files
• Slowest Tests - Performance bottlenecks

❌ Test Failures

• Failed Tests - Detailed error messages
• Code Context - Source code frames showing failure locations
• Suite Information - Which test suites failed

📊 Visualizations

• Pie Charts - Overall and per-category coverage
• Bar Charts - Slowest tests comparison
• Histograms - Coverage distribution

🎨 Screenshots

• dark-themed reports with comprehensive statistics visualizations*

📋 Requirements

• Node.js >= 14.0.0
• Jest configured with coverage enabled

Jest Configuration

Your Jest command must output:

--coverageReporters=json        # Creates coverage-final.json
--coverageReporters=html        # Creates lcov-report/index.html
--json                          # JSON output
--outputFile=coverage/jest-results.json  # Test results

🔧 Advanced Usage

Custom Config Location

# Use a specific config file
P3_COV_CONFIG_PATH=/path/to/p3cov.config.js p3cov

Programmatic Usage

const { execSync } = require('child_process');
const config = require('./p3cov.config.js');

// Run from Node.js
process.env.P3_COV_CONFIG_PATH = '/path/to/p3cov.config.js';
require('p3cov/generate-coverage-html.js');

NPM Scripts

Add to your package.json:

{
  "scripts": {
    "test:coverage": "p3cov",
    "coverage:html": "p3cov"
  }
}

🐛 Troubleshooting

"Cannot find lcov-report" Error

Make sure Jest generates the required files:

npm test -- --coverage --coverageReporters=html --coverageReporters=json --json --outputFile=coverage/jest-results.json

Config Not Found After First Run

The config is created in the directory where you run the command. Make sure you're in the right directory.

Wrong Workspace Root

Adjust paths.workspaceRootLevelsUp in your config:

• 0 = config is in workspace root
• 1 = config is one level down from root
• 2 = config is two levels down, etc.

🤝 Contributing

Contributions are welcome! Feel free to submit issues and pull requests.

📄 License

ISC License

🔗 Links

• npm package