k6-insight-reporter

🚀 Comprehensive HTML reporter for k6 with interactive visualizations, historical tracking, and seamless CI/CD integration

Transform your k6 test results into beautiful, actionable insights with interactive charts, performance grading, historical trend analysis, and automatic CI/CD integration.

⚠️ Beta Release Notice

This is a beta release (1.0.3-beta). While functional and tested, some features are being refined:

• ✅ Stable: HTML report generation, interactive charts, historical tracking, CI/CD integration
• ⚠️ Beta: Advanced filtering, comparison features, URL metrics
• 🚧 Planned: PDF export, webhook notifications, regression detection

We welcome feedback! Please report issues and suggestions.

📋 Table of Contents

• Features
• Installation
• Quick Start
• Usage Methods
• CLI Reference
• History Database
• CI/CD Integration
• Windows Support
• Examples
• Troubleshooting

✨ Features

📊 Interactive Visualizations

• Chart.js-powered interactive charts with zoom, pan, and hover details
• Time-series charts showing metrics over test duration
• URL-level metrics with per-endpoint performance analysis
• Distribution histograms for response time analysis
• Performance grading (A-F scale) with visual indicators
• Responsive design - works on desktop, tablet, and mobile

🗄️ Historical Tracking (SQLite-based)

• Automatic persistence of test results across runs
• Project grouping for multi-project environments
• Environment filtering (dev, staging, production)
• Git metadata tracking (commit, branch, build number)
• CI/CD detection - auto-detects GitHub Actions, GitLab CI, Jenkins
• Retention policies - automatic cleanup of old data
• Trend analysis - compare current vs historical performance

🎯 CI/CD Ready

• Artifact-friendly database location in CI environments
• GitLab CI integration with artifacts and caching

🎨 Professional Themes

• Default theme: Clean, modern design
• Dark theme: Eye-friendly dark mode
• Customizable: Extend with your own themes

🔧 Installation

Global Installation (Recommended)

npm install -g k6-insight-reporter

Provides CLI commands:

• k6-insight-reporter - Generate reports with full control
• k6-with-trends - Wrapper that runs k6 and generates report automatically

Local Installation

npm install --save-dev k6-insight-reporter

Requirements

• Node.js: >= 16.0.0
• k6: Latest version (install k6)
• OS: macOS, Linux, Windows (with Git Bash or WSL)

🚀 Quick Start

Option 1: One-Command Wrapper (Linux/Mac)

k6-with-trends test.js

Option 2: Manual Two-Step (All Platforms)

# Step 1: Run k6 test
k6 run test.js --summary-export=summary.json --out json=metrics.json

# Step 2: Generate report
k6-insight-reporter summary.json --url-metrics metrics.json

This generates:

• report.html - Interactive HTML report
• .k6-insight-reporter/history.db - Test history (in CI)
• ~/.k6-insight-reporter/history.db - Test history (local)

📖 Usage Methods

Method 1: k6-with-trends (Wrapper Script)

The k6-with-trends wrapper automatically runs k6 and generates the report.

Linux/macOS:

# Basic usage
k6-with-trends test.js

# With k6 options (passed through to k6)
k6-with-trends test.js --vus 10 --duration 30s --iterations 100

What it does:

1. Runs k6 with --summary-export and --out json
2. Automatically calls k6-insight-reporter with time-series data
3. Saves results to history database
4. Cleans up temporary files
5. Preserves k6's exit code

Limitations:

• ❌ Reporter flags (--title, --commit, --env, etc.) are NOT supported
• ❌ History control flags (--no-save-history, --retention) won't work
• ✅ All k6 flags work normally (--vus, --duration, etc.)

For full control, use Method 2.

Method 2: Manual Two-Step (Recommended for CI/CD)

For complete control over reporter options and metadata:

# Step 1: Run k6 test
k6 run test.js \
  --summary-export=summary.json \
  --out json=metrics.json \
  --vus 10 \
  --duration 30s

# Step 2: Generate report with full metadata
k6-insight-reporter summary.json \
  --url-metrics metrics.json \
  --title "API Performance Test - Build #42" \
  --env production \
  --commit abc123 \
  --branch main \
  --build 42 \
  --project my-api \
  --retention 90

# Step 3: Cleanup (optional)
rm -f metrics.json summary.json

Method 3: Programmatic API (In k6 Test Script)

Use in k6's handleSummary() callback for automatic report generation when running k6 run test.js.

Import the htmlReport function

Option 1: CDN Import (Recommended for k6 scripts)

// Use latest version (automatically updates to newest release)
import { htmlReport } from 'https://cdn.jsdelivr.net/npm/k6-insight-reporter@latest/dist/k6-reporter.bundle.js';

// Pin to specific version (recommended for production - ensures consistency)
import { htmlReport } from 'https://cdn.jsdelivr.net/npm/[email protected]/dist/k6-reporter.bundle.js';

// Use main branch (development version - may be unstable or broken)
import { htmlReport } from 'https://cdn.jsdelivr.net/npm/k6-insight-reporter@main/dist/k6-reporter.bundle.js';

📌 Version Pinning Best Practices:

• Production/CI: Pin to specific version (e.g., @1.0.3) for stability and reproducibility
• Development: Use @latest to get new features automatically
• Testing: Avoid @main unless testing unreleased features - it may break your tests
• Check releases: See available versions

Option 2: Local npm package (Node.js projects)

import { htmlReport } from 'k6-insight-reporter';

Complete Example

import { htmlReport } from 'https://cdn.jsdelivr.net/npm/k6-insight-reporter@latest/dist/k6-reporter.bundle.js';
import { textSummary } from 'https://jslib.k6.io/k6-summary/0.0.2/index.js';

export default function() {
  // Your k6 test code here
}

export function handleSummary(data) {
  return {
    'report.html': htmlReport(data, {
      title: 'My Performance Test',
      environment: 'production',
      saveHistory: true,
      project: 'my-api',
      retentionDays: 90,
      metadata: {
        gitCommit: 'abc123',
        gitBranch: 'main',
        buildNumber: '42'
      }
    }),
    stdout: textSummary(data, { indent: ' ', enableColors: true })
  };
}

Then run:

k6 run test.js

This automatically generates report.html and saves to history database.

📚 CLI Reference

Main Command: k6-insight-reporter

k6-insight-reporter <input.json> [options]

Basic Options

| Option | Description | Default | Example | |--------|-------------|---------|---------| | <input.json> | k6 summary JSON file (required) | - | summary.json | | -o, --output <file> | Output HTML file path | report.html | -o my-report.html | | -t, --title <title> | Report title | k6 Performance Report | --title "API Test" | | --theme <theme> | Theme (default, dark, minimal) | default | --theme dark | | --url-metrics <file> | URL-level metrics from k6 | - | --url-metrics metrics.json | | --metrics <file> | Time-series metrics file | - | --metrics processed.json |

Metadata Options

| Option | Description | Example | |--------|-------------|---------| | --env <environment> | Environment name | --env production | | --commit <hash> | Git commit hash | --commit $CI_COMMIT_SHA | | --branch <branch> | Git branch name | --branch main | | --build <number> | Build/pipeline number | --build $CI_PIPELINE_ID | | --project <name> | Project name for history grouping | --project my-api |

History Options

| Option | Description | Default | |--------|-------------|---------| | --save-history | Enable history saving (default) | true | | --no-save-history | Disable history saving | - | | --retention <days> | Auto-cleanup runs older than N days | 90 |

Examples

# Basic report
k6-insight-reporter summary.json

# With URL metrics
k6-insight-reporter summary.json --url-metrics metrics.json

# Full metadata for CI/CD
k6-insight-reporter summary.json \
  --url-metrics metrics.json \
  --title "API Load Test - Build #${CI_PIPELINE_ID}" \
  --env production \
  --commit "${CI_COMMIT_SHA:0:8}" \
  --branch "${CI_COMMIT_BRANCH}" \
  --build "${CI_PIPELINE_ID}" \
  --project my-api

# Disable history
k6-insight-reporter summary.json --no-save-history

# Custom retention (30 days)
k6-insight-reporter summary.json --retention 30

# Dark theme
k6-insight-reporter summary.json --theme dark

History Commands

List Historical Runs

k6-insight-reporter history list [options]

Options:

• -p, --project <name> - Filter by project
• -e, --environment <env> - Filter by environment
• -n, --limit <number> - Number of results (default: 20)
• --all - Show all runs (no limit)

Examples:

# List recent runs
k6-insight-reporter history list

# List for specific project
k6-insight-reporter history list --project my-api

# Filter by environment
k6-insight-reporter history list --project my-api --environment production

# Show all runs
k6-insight-reporter history list --all

# Limit results
k6-insight-reporter history list --limit 10

Show Database Information

k6-insight-reporter history info

Clear Old Runs

k6-insight-reporter history clear --days 30

Export History

k6-insight-reporter history export --output history.json

🗄️ History Database

How History Works

History is saved automatically when you generate a report (unless --no-save-history is used).

# ❌ This does NOT save history
k6 run test.js

# ✅ This DOES save history
k6 run test.js --summary-export=summary.json
k6-insight-reporter summary.json

What gets saved:

• Test run metadata (timestamp, environment, git info)
• Core metrics (response times, throughput, error rates)
• URL-level metrics (per-endpoint performance)
• Custom metrics (Counter, Rate, Gauge, Trend)
• Performance grade (A-F based on thresholds)

Database Location

The database location is automatically determined:

| Environment | Location | When Used | |-------------|----------|-----------| | CI/CD | ./.k6-insight-reporter/history.db | When CI=true env var is set | | Local | ~/.k6-insight-reporter/history.db | Development/local testing |

GitLab CI, GitHub Actions, Jenkins automatically set CI=true, so the database is created in your project directory for easy artifact upload.

🔄 CI/CD Integration

GitLab CI (Complete Example)

stages:
  - test
  - deploy

variables:
  K6_HISTORY_FILE: ".k6-insight-reporter/history.db"
  PROJECT_NAME: "my-api"

k6-performance-test:
  stage: test
  image: node:20
  before_script:
    - apt-get update && apt-get install -y sqlite3 curl
    - npm install -g k6 k6-insight-reporter
    - mkdir -p .k6-insight-reporter

    # Restore history from previous pipeline
    - |
      echo "📥 Restoring test history from artifacts..."

      HTTP_CODE=$(curl --silent --write-out "%{http_code}" --location --output "$K6_HISTORY_FILE" \
        --header "PRIVATE-TOKEN: $CI_JOB_TOKEN" \
        "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/jobs/artifacts/main/raw/${K6_HISTORY_FILE}?job=k6-performance-test")

  script:
    # Run k6 test
    - |
      k6 run test.js \
        --summary-export=summary.json \
        --out json=metrics.json \
        --vus 10 \
        --duration 30s \
        || true

    # Generate report with full metadata
    - |
      k6-insight-reporter summary.json \
        --url-metrics metrics.json \
        --title "🚀 ${PROJECT_NAME} - Build #${CI_PIPELINE_ID}" \
        --env "${CI_ENVIRONMENT_NAME:-production}" \
        --commit "${CI_COMMIT_SHA:0:8}" \
        --branch "${CI_COMMIT_BRANCH}" \
        --build "${CI_PIPELINE_ID}" \
        --project "${PROJECT_NAME}" \
        --retention 90

    # Cleanup temp files
    - rm -f metrics.json summary.json

  artifacts:
    name: "k6-report-$CI_COMMIT_REF_NAME-$CI_PIPELINE_ID"
    paths:
      - report.html
      - .k6-insight-reporter/history.db
    expire_in: 90 days
    when: always

  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
    - if: $CI_PIPELINE_SOURCE == "schedule"

🪟 Windows Support

k6-with-trends on Windows

The k6-with-trends wrapper is a bash script and requires a bash environment.

Option 1: Git Bash (Recommended)

1. Install Git for Windows (most developers already have this)
2. Open Git Bash terminal
3. Run: k6-with-trends test.js

Option 2: WSL (Windows Subsystem for Linux)

# Install WSL
wsl --install

# Inside WSL terminal
npm install -g k6-insight-reporter
k6-with-trends test.js

Option 3: Manual Commands (PowerShell/CMD)

# Run k6
k6 run test.js --summary-export=summary.json --out json=metrics.json

# Generate report
k6-insight-reporter summary.json --url-metrics metrics.json

# Cleanup
Remove-Item metrics.json, summary.json -ErrorAction SilentlyContinue

💡 Examples

Basic Report Generation

k6 run test.js --summary-export=summary.json
k6-insight-reporter summary.json

With URL-Level Metrics

k6 run test.js --summary-export=summary.json --out json=metrics.json
k6-insight-reporter summary.json --url-metrics metrics.json

Full Metadata for Production

k6-insight-reporter summary.json \
  --url-metrics metrics.json \
  --title "Production API Load Test" \
  --env production \
  --commit $(git rev-parse --short HEAD) \
  --branch $(git branch --show-current) \
  --build ${BUILD_NUMBER} \
  --project ecommerce-api \
  --theme dark \
  --retention 180

Disable History Saving

k6-insight-reporter summary.json --no-save-history

In-Script Report Generation (CDN Import)

// test.js
import http from 'k6/http';
import { check, sleep } from 'k6';
import { htmlReport } from 'https://cdn.jsdelivr.net/npm/[email protected]/dist/k6-reporter.bundle.js';
import { textSummary } from 'https://jslib.k6.io/k6-summary/0.0.2/index.js';

export const options = {
  vus: 10,
  duration: '30s',
};

export default function() {
  const res = http.get('https://api.example.com/users');
  check(res, {
    'status is 200': (r) => r.status === 200,
    'response time < 500ms': (r) => r.timings.duration < 500,
  });
  sleep(1);
}

export function handleSummary(data) {
  return {
    'report.html': htmlReport(data, {
      title: 'API Performance Test',
      environment: 'production',
      project: 'my-api',
      saveHistory: true,
    }),
    stdout: textSummary(data, { indent: ' ', enableColors: true }),
  };
}

Run with:

k6 run test.js

Output:

• report.html - Generated automatically
• .k6-insight-reporter/history.db - History saved (in CI)
• ~/.k6-insight-reporter/history.db - History saved (local)

🔍 Troubleshooting

History database not created

Problem: No history.db file appears.

Solution:

• If using CLI: Ensure you're running k6-insight-reporter summary.json (not just k6 run test.js)
• If using programmatic API: Ensure your test script has handleSummary() with htmlReport() and saveHistory: true
• Check that --no-save-history is not set (CLI) or saveHistory: false (API)
• Verify directory permissions

Note:

• k6 run test.js alone does NOT save history
• k6 run test.js with handleSummary(data) { return { 'report.html': htmlReport(data) } } DOES save history

Artifacts 404 error in CI

Problem: curl: (22) The requested URL returned error: 404

Solution:

• This is normal on the first pipeline run (no previous artifacts exist)
• The pipeline will work correctly from the second run onwards
• The error is handled gracefully with || echo "First run"

k6-with-trends not working on Windows

Problem: /bin/bash: No such file or directory

Solution:

• Install Git for Windows and use Git Bash terminal
• Or use WSL
• Or run commands manually (see Windows Support)

Permission denied on history.db

Problem: SQLITE_CANTOPEN or permission errors

Solution:

# Fix permissions
chmod 755 .k6-insight-reporter
chmod 644 .k6-insight-reporter/history.db

# Or recreate directory
rm -rf .k6-insight-reporter
mkdir -p .k6-insight-reporter

Flags not working with k6-with-trends

Problem: --title, --commit, --no-save-history flags don't work

Solution:

• These are reporter flags, not k6 flags
• k6-with-trends only passes flags to k6, not to the reporter
• Use the manual two-step approach for full control:

  k6 run test.js --summary-export=summary.json
  k6-insight-reporter summary.json --title "My Test" --commit abc123

📄 License

MIT License - see LICENSE file for details.

🙏 Credits

• Inspired by benc-uk/k6-reporter
• Built with Chart.js
• Powered by k6 by Grafana Labs

📣 Feedback & Contributions

This is a beta release. We value your feedback!

• 🐛 Found a bug? Open an issue
• 💡 Have a suggestion? Start a discussion
• 🤝 Want to contribute? PRs welcome!

Made with ❤️ for the k6 community

⭐ Star this project if you find it useful!

Version: 1.0.3-beta Last Updated: 2026-02-11 Status: Beta - Stable for production use