BunCover CLI

A cross-platform CLI tool for collecting, analyzing, and reporting test coverage data for Bun projects. BunCover helps you track and improve your test coverage with real-time reporting and historical data analysis.

Features

• Real-time Coverage Analysis: Instantly analyze test coverage as you run your tests
• Detailed Reports: Get comprehensive coverage reports including:
  • Function coverage percentage
  • Line coverage percentage
  • Uncovered line numbers
  • File-by-file breakdown
• Real-time Coverage Server: Serve source files for real-time coverage visualization
• Flexible Authentication: Browser-based authentication for interactive use and access keys for CI/CD
• Cross-Platform: Supports Linux, macOS, and Windows
• Full Bun Test Compatibility: Pass any Bun test arguments directly to customize test execution
• Project Validation: Ensures commands run in valid JavaScript/TypeScript projects

Installation

Using npm:

npm install -g @qualipsolutions/buncover

Using yarn:

yarn global add @qualipsolutions/buncover

Using pnpm:

pnpm add -g @qualipsolutions/buncover

Using bun:

bun install -g @qualipsolutions/buncover

Usage Guide

A cross-platform coverage reporting tool for Bun

Usage: buncover <COMMAND>

Commands:
  login   Login using browser authentication or access key
  logout  Logout and remove stored token
  status  Display current configuration status
  run     Run tests with coverage reporting
  serve   Serve source files for a project
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

1. Authentication

BunCover supports two authentication methods:

Browser Authentication (Interactive)

For interactive development, use browser-based authentication:

# Login using browser authentication (default)
buncover login

# Specify environment
buncover login --env dev

# Skip automatic browser opening
buncover login --no-browser

Access Key Authentication (CI/CD)

For automated environments and CI/CD pipelines:

# Login with access key parameter
buncover login --access-key buncover_live_your_access_key

# Or use environment variable (recommended for CI/CD)
export BUNCOVER_ACCESS_KEY=buncover_live_your_access_key
buncover login

Note: Environment variables take precedence over command parameters for security.

2. Check Authentication Status

Verify your authentication and configuration:

# Display current status
buncover status

3. Running Tests with Coverage

BunCover runs your Bun tests with coverage enabled and reports the results. You can pass any Bun test arguments directly to customize test execution.

Basic Usage:

# Run tests and collect coverage
buncover run

# Run with specific project ID
buncover run --project-id <project_id>

Passing Arguments to Bun Test:

All arguments after buncover run [OPTIONS] are passed directly to bun test. BunCover always includes --coverage --coverage-reporter=text automatically.

# Run specific test files or directories
buncover run src/utils/*.test.ts
buncover run tests/integration/

# Control test execution
buncover run --bail                    # Stop after first failure
buncover run --timeout 10000           # Set timeout to 10 seconds
buncover run --preload ./setup.ts      # Preload setup file

# Filter tests by name pattern
buncover run --test-name-pattern "user.*"

# Combine multiple arguments
buncover run --bail --timeout 5000 src/**/*.test.ts

# Combine with BunCover options
buncover run --project-id abc123 --bail tests/
buncover run --log-level debug --timeout 10000

Available Bun Test Arguments:

All Bun test CLI arguments are supported, including:

• --bail - Stop after first test failure
• --timeout <ms> - Set test timeout (default: 5000)
• --preload <file> - Preload a script before running tests
• --test-name-pattern <pattern> - Only run tests matching the pattern
• --rerun-each <n> - Run each test n times
• File/directory paths - Specify which test files to run

Note: BunCover must be run from a JavaScript/TypeScript project root (directory containing package.json).

4. Coverage Server

Start a local server for real-time coverage visualization:

# Start server with default settings
buncover serve

# Specify custom directory
buncover serve --dir ./src

# Use specific project ID
buncover serve --project-id <project_id>

5. Logout

Remove stored authentication:

# Logout and clear stored tokens
buncover logout

Configuration

Environment Variables

For CI/CD and automated environments:

# Access key for authentication
export BUNCOVER_ACCESS_KEY=buncover_live_your_access_key

Configuration File

BunCover automatically creates and manages a configuration file at .buncover/config.json:

{
  "project_id": "your_project_id",
}

Configuration Options

• project_id (string): Your project identifier (set automatically after first run)

CI/CD Integration

GitHub Actions

name: Coverage Report
on: [push, pull_request]

jobs:
  coverage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v1

      - name: Install dependencies
        run: bun install

      - name: Install BunCover CLI
        run: bun install -g @qualipsolutions/buncover

      - name: Login and run tests with coverage
        run: |
          buncover login --env prod
          buncover run
        env:
          BUNCOVER_ACCESS_KEY: ${{ secrets.BUNCOVER_ACCESS_KEY }}

Docker

FROM oven/bun:latest

# Install BunCover CLI
RUN bun install -g @qualipsolutions/buncover

# Set access key via environment variable
ENV BUNCOVER_ACCESS_KEY=buncover_live_your_access_key

# Login and run tests with coverage
CMD ["sh", "-c", "buncover login --env prod && buncover run"]

Other CI Systems

For other CI systems, simply:

1. Install BunCover CLI
2. Set BUNCOVER_ACCESS_KEY environment variable
3. Run buncover login --env prod
4. Run buncover run

Requirements

• Node.js ≥ 18.0.0
• Bun runtime installed

Support

Supported Platforms

• Linux
• macOS
• Windows

Getting Help

For support inquiries and access to BunCover, please contact:

• Email: [email protected]
• Website: https://www.buncover.dev

Copyright

© 2025 BunCover. All rights reserved.

This software is proprietary and confidential. Unauthorized copying, transferring or reproduction of this software, via any medium is strictly prohibited. The software is provided under a license agreement with BunCover and contains valuable trade secrets and intellectual property.