tgreport

v0.1.4

Published

8 months ago

Beautiful, framework-agnostic test reporter for Mocha, Playwright, WebdriverIO, and Jasmine. Features HTML/PDF/CSV exports, screenshot support, test history tracking, and interactive React viewer. Works with both JavaScript and TypeScript projects.

📊 TGReport

Beautiful, framework-agnostic test reporter with HTML/PDF/CSV exports, screenshot support, test history tracking, and interactive React viewer

✨ Features

🎯 Framework-Agnostic - Works with Mocha, Playwright, WebdriverIO, and Jasmine
🎨 Beautiful UI - Apple-quality design with professional aesthetics
📄 Multiple Exports - HTML, JSON, PDF, and CSV formats
📸 Media Support - Screenshots, videos with lightbox viewer
📊 Test History - SQLite-based trend analysis and tracking
🔍 Advanced Filtering - Search, filter by status, file navigation
⚡ Parallel Support - Proper timing for parallel test execution
🎭 Custom Branding - Logo, colors, project name customization
💻 React Viewer - Interactive web app for viewing reports
🛠️ CLI Tools - Manage test history from command line
🟢 JavaScript & TypeScript - Works with both!
🚀 Zero Config - Works out of the box with sensible defaults

📸 Features Preview

Test History & Trends

📉 Trends (Last 7 days)

────────────────────────────────────────────────────────────
Date            Runs     Tests      Pass%      Avg Duration
────────────────────────────────────────────────────────────
2025-11-04      4        20         100.0%     1.23s
2025-11-03      3        15         95.0%      1.18s
2025-11-02      2        10         100.0%     1.15s
────────────────────────────────────────────────────────────

🚀 Quick Start

Installation

npm install tgreport --save-dev

Mocha

// .mocharc.json
{
  "reporter": "tgreport/reporters/MochaReporter",
  "reporter-options": {
    "reportTitle": "My Test Report",
    "autoOpen": true,
    "exportCSV": true
  }
}

// test/example.test.js
const { testContext } = require('tgreport/context');
const assert = require('assert');

describe('My Tests', function() {
  it('should work', function() {
    testContext(this, 'Test completed successfully');
    assert.strictEqual(2 + 2, 4);
  });
});

Playwright

// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  reporter: [['tgreport/reporters/PlaywrightReporter', {
    reportTitle: 'E2E Tests',
    exportPDF: true,
    exportCSV: true,
    enableHistory: true,
  }]]
});

// tests/example.spec.ts
import { test, expect } from '@playwright/test';

test('homepage works', async ({ page }) => {
  await page.goto('https://example.com');
  await expect(page).toHaveTitle(/Example/);
});

WebdriverIO

// wdio.conf.js
const TGWebdriverIOReporter = require('tgreport/reporters/WebdriverIOReporter');

exports.config = {
  reporters: [
    ['spec'],
    [TGWebdriverIOReporter, {
      reportTitle: 'WebdriverIO Tests',
      exportCSV: true,
      enableHistory: true,
    }]
  ],
};

Jasmine

// run-tests.js
const Jasmine = require('jasmine');
const TGJasmineReporter = require('tgreport/reporters/JasmineReporter');

const jasmine = new Jasmine();
jasmine.loadConfigFile('spec/support/jasmine.json');

jasmine.addReporter(new TGJasmineReporter({
  reportTitle: 'Jasmine Test Report',
  exportCSV: true,
  enableHistory: true,
  branding: {
    headerColor: '#8A4182' // Jasmine purple
  }
}));

jasmine.execute();

📖 Usage

Context API

Add screenshots, videos, JSON data, and more to your tests:

const { testContext } = require('tgreport/context');

it('should demonstrate context API', async function() {
  // Add text
  testContext(this, {
    type: 'text',
    title: 'Info',
    value: 'Additional test information'
  });
  
  // Add screenshot
  await testContext.screenshot(this, './screenshot.png', 'Page Screenshot');
  
  // Add JSON data
  testContext(this, {
    type: 'json',
    title: 'Response Data',
    value: { status: 200, data: {...} }
  });
  
  // Add code snippet
  testContext(this, {
    type: 'code',
    title: 'Test Code',
    value: 'const result = await api.fetch();'
  });
});

Configuration Options

{
  // Basic
  reportDir: './test-reports',
  reportTitle: 'My Test Report',
  reportFilename: 'report-[datetime]',
  autoOpen: true,
  
  // Exports
  exportPDF: true,
  exportCSV: true,
  
  // History
  enableHistory: true,
  historyOptions: {
    maxRecords: 100,
    retentionDays: 30,
    autoCleanup: true
  },
  
  // Branding
  branding: {
    projectName: 'My Project',
    headerColor: '#007aff',
    logo: './logo.png'
  },
  
  // Features
  charts: true,
  code: true,
  showHooks: 'context'
}

🎨 Report Formats

HTML Report

Interactive UI with filters and search
Expandable test suites
Screenshot/video lightbox viewer
Syntax-highlighted code and errors
Custom branding support
Responsive design

PDF Export

Full styling preserved
Professional layout
Configurable format (A4/Letter/Legal)
Requires: playwright or puppeteer

{
  exportPDF: true,
  pdfOptions: {
    format: 'A4',
    landscape: false
  }
}

CSV Export

Flattened test data
Excel/Google Sheets compatible
Suite hierarchy preserved
Error messages included

{
  exportCSV: true,
  csvOptions: {
    delimiter: ',',
    includeHeader: true
  }
}

JSON Export

Complete test data
Machine-readable
Includes configuration and metadata
Perfect for custom processing

📊 Test History Tracking

Track test results over time with SQLite storage:

// Enable in config
{
  enableHistory: true,
  historyOptions: {
    enabled: true,
    maxRecords: 100,
    retentionDays: 30,
    autoCleanup: true
  }
}

CLI Commands

# List recent test runs
tgreport-history list 20

# Show statistics
tgreport-history stats

# View trends
tgreport-history trends 30

# Delete old records
tgreport-history delete --days=60

# Export/import
tgreport-history export backup.json
tgreport-history import backup.json

# Cleanup
tgreport-history cleanup --max=50

Output Example:

📊 Test History

────────────────────────────────────────────────────────────
Date                   Framework    Tests    Pass%    Duration
────────────────────────────────────────────────────────────
11/4/2025, 11:14 PM   playwright   5        100.0%   1.24s
11/4/2025, 10:30 PM   mocha        15       93.3%    2.10s
────────────────────────────────────────────────────────────

🖥️ React Viewer

Interactive web application for viewing test reports:

# Development
npm run dev:viewer

# Build
npm run build:viewer

# Use
# 1. Drag & drop JSON report
# 2. Or open: http://localhost:3001/?report=path/to/report.json

Features:

Drag & drop JSON reports
Real-time filtering and search
Beautiful dashboard
Expandable test details
Media viewer
Responsive design

🎯 Framework Compatibility

| Framework | Version | Status | Reporter Path | |-----------|---------|--------|---------------| | Mocha | ≥10.0.0 | ✅ Full Support | tgreport/reporters/MochaReporter | | Playwright | ≥1.40.0 | ✅ Full Support | tgreport/reporters/PlaywrightReporter | | WebdriverIO | ≥8.0.0 | ✅ Full Support | tgreport/reporters/WebdriverIOReporter | | Jasmine | ≥4.0.0 | ✅ Full Support | tgreport/reporters/JasmineReporter |

💻 JavaScript & TypeScript

Works with BOTH!

Pure JavaScript ✅

// No TypeScript required!
const { testContext } = require('tgreport/context');

describe('JS Tests', function() {
  it('works', function() {
    testContext(this, 'Pure JavaScript!');
  });
});

TypeScript ✅

// Full type support!
import { testContext } from 'tgreport/context';
import type { TestResults } from 'tgreport';

describe('TS Tests', function() {
  it('works', function() {
    testContext(this, 'TypeScript with types!');
  });
});

No TypeScript installation required for JavaScript projects!

📦 What You Get

tgreport/
├── dist/
│   ├── reporters/
│   │   ├── MochaReporter.js          (93KB)
│   │   ├── PlaywrightReporter.js     (89KB)
│   │   ├── WebdriverIOReporter.js    (85KB)
│   │   └── JasmineReporter.js        (68KB)
│   ├── context/index.js              (5KB)
│   ├── cli/history.js                (20KB)
│   ├── index.js                      (115KB)
│   └── *.d.ts                        (Type definitions)
├── viewer-dist/                      (React viewer)
├── README.md
└── Documentation files

All JavaScript - works everywhere!

🔧 Advanced Features

Custom Branding

{
  branding: {
    projectName: 'My Project',
    companyName: 'ACME Corp',
    logo: './path/to/logo.png',
    headerColor: '#1a1a1a',
    accentColor: '#007aff'
  }
}

Parallel Execution

{
  reportStrategy: 'unified',  // Single report for all files
  groupByFile: true,          // Group tests by file
}

Media Handling

// Screenshots
await testContext.screenshot(this, './screenshot.png', 'My Screenshot');
await testContext.screenshot(this, base64Data, 'Base64 Screenshot');
await testContext.screenshot(this, 'https://example.com/image.png', 'URL Screenshot');

// Videos
await testContext.video(this, './video.mp4', 'Test Recording');

Auto-Capture on Failure

Playwright:

use: {
  screenshot: 'only-on-failure',
  video: 'retain-on-failure',
}

Screenshots automatically added to failed tests!

📚 Documentation

README.md (this file) - Quick start and overview
GETTING_STARTED.md - Detailed setup guide
HISTORY_STORAGE.md - SQLite history features
VIEWER_USAGE.md - React viewer documentation
Examples - Demo projects for each framework (Mocha, Playwright, WebdriverIO, Jasmine)

🎯 Use Cases

CI/CD Integration

# .github/workflows/test.yml
- name: Run Tests
  run: npm test
  
- name: Upload Reports
  uses: actions/upload-artifact@v3
  with:
    name: test-reports
    path: test-reports/

Quality Tracking

# Track test quality over time
tgreport-history trends 30

# Export for analysis
tgreport-history export monthly-report.json

Team Reporting

{
  exportPDF: true,  // Share with stakeholders
  exportCSV: true,  // Analyze in Excel
  branding: {
    projectName: 'Q4 Release Testing',
    companyName: 'Your Company'
  }
}

🆚 Comparison

| Feature | TGReport | Mochawesome | Allure | Jest HTML Reporter | |---------|----------|-------------|--------|-------------------| | Mocha | ✅ | ✅ | ✅ | ❌ | | Playwright | ✅ | ❌ | ✅ | ❌ | | WebdriverIO | ✅ | ❌ | ✅ | ❌ | | Jasmine | ✅ | ❌ | ✅ | ❌ | | PDF Export | ✅ | ❌ | ✅ | ❌ | | CSV Export | ✅ | ❌ | ❌ | ❌ | | Test History | ✅ | ❌ | ✅ | ❌ | | React Viewer | ✅ | ❌ | ❌ | ❌ | | CLI Tools | ✅ | ❌ | ✅ | ❌ | | JavaScript Support | ✅ | ✅ | ✅ | ✅ | | TypeScript Support | ✅ | ❌ | ✅ | ✅ | | Custom Branding | ✅ | ✅ | ✅ | ❌ | | Setup Complexity | Low | Low | Medium | Low |

🎓 Examples

Example 1: Basic Mocha Test

const { expect } = require('chai');
const { testContext } = require('tgreport/context');

describe('Calculator', function() {
  it('should add numbers', function() {
    const result = 2 + 2;
    
    testContext(this, {
      type: 'text',
      title: 'Calculation',
      value: `2 + 2 = ${result}`
    });
    
    expect(result).to.equal(4);
  });
});

Example 2: Playwright with Screenshots

import { test, expect } from '@playwright/test';

test('homepage test', async ({ page }) => {
  await page.goto('https://example.com');
  
  // Screenshot automatically captured on failure
  await expect(page).toHaveTitle(/Example Domain/);
});

Example 3: Jasmine with Custom Branding

// spec/calculator.spec.js
describe('Calculator', function() {
  it('should add two numbers', function() {
    const calculator = {
      add: (a, b) => a + b
    };
    expect(calculator.add(2, 3)).toBe(5);
  });
  
  it('should handle async operations', async function() {
    const result = await Promise.resolve(42);
    expect(result).toBe(42);
  });
});

// run-tests.js
const Jasmine = require('jasmine');
const TGJasmineReporter = require('tgreport/reporters/JasmineReporter');

const jasmine = new Jasmine();
jasmine.addReporter(new TGJasmineReporter({
  reportTitle: 'Calculator Tests',
  branding: {
    projectName: 'Calculator App',
    headerColor: '#8A4182',
    accentColor: '#8A4182'
  }
}));
jasmine.execute();

Example 4: WebdriverIO with Context

const { testContext } = require('tgreport/context');

describe('Login Tests', function() {
  it('should login successfully', async function() {
    await browser.url('/login');
    
    // Add browser info
    testContext(this.test, {
      type: 'json',
      title: 'Browser',
      value: await browser.getCapabilities()
    });
    
    // Take screenshot
    const screenshot = await browser.takeScreenshot();
    await testContext.screenshot(this.test, screenshot, 'Login Page');
  });
});

📋 Requirements

Node.js: ≥ 18.0.0
npm: ≥ 8.0.0
Framework: Mocha ≥10 OR Playwright ≥1.40 OR WebdriverIO ≥8 OR Jasmine ≥4
Optional (for PDF): playwright or puppeteer

🛠️ Configuration

All Available Options

{
  // Output
  reportDir: './test-reports',
  reportTitle: 'Test Report',
  reportFilename: 'report-[datetime]',
  reportPageTitle: 'Test Results',
  autoOpen: false,
  
  // Exports
  exportPDF: false,
  exportCSV: false,
  pdfOptions: {
    format: 'A4',
    landscape: false,
    margin: { top: '0.5in', right: '0.5in', bottom: '0.5in', left: '0.5in' }
  },
  csvOptions: {
    includeHeader: true,
    delimiter: ','
  },
  
  // History
  enableHistory: false,
  historyOptions: {
    enabled: false,
    dbPath: './.tgreport/history.db',
    maxRecords: 100,
    retentionDays: 30,
    autoCleanup: true,
    saveFullResults: false
  },
  
  // Branding
  branding: {
    projectName: 'My Project',
    companyName: 'My Company',
    logo: './logo.png',
    headerColor: '#1a1a1a',
    accentColor: '#007aff'
  },
  
  // Parallel Runs
  reportStrategy: 'unified',  // 'unified' | 'separate' | 'per-file'
  groupByFile: true,
  
  // Display
  charts: true,
  code: true,
  showHooks: 'context',  // 'always' | 'failed' | 'context' | 'never'
  showPassed: true,
  showFailed: true,
  showPending: true,
  showSkipped: true,
  
  // Other
  inline: false,
  quiet: false,
  saveJson: true,
  saveHtml: true
}

🎨 Customization

Custom Colors

branding: {
  headerColor: '#2563eb',    // Header background
  accentColor: '#3b82f6',    // Buttons, links
}

File Naming

reportFilename: 'test-report-[datetime]'
// Tokens: [datetime], [date], [time], [timestamp], [status]

Themes

The report automatically uses your brand colors throughout the UI.

📸 Screenshots & Media

Supported Formats

Screenshots:

File paths: ./screenshot.png
Base64: data:image/png;base64,...
URLs: https://example.com/image.png

Videos:

File paths: ./video.mp4
URLs: https://example.com/video.mp4

Auto-Copy to Report

Files are automatically copied to the report directory:

testContext.screenshot(this, './local/screenshot.png', 'My Screenshot');
// Copied to: test-reports/media/screenshot-abc123.png

🔍 Advanced Features

History Trends

# View pass rate trends
tgreport-history trends 30

# Filter by project
tgreport-history list 20 --project="My Project"

# Export for analysis
tgreport-history export history.json

Parallel Execution

TGReport properly handles parallel test runs:

Accurate timing for each suite
File-based grouping
Interactive file navigation
Collapsible sections

Media Lightbox

Click any screenshot or video to open fullscreen viewer:

Keyboard navigation (ESC to close)
Smooth animations
Touch-friendly on mobile

🤝 Contributing

We welcome contributions! See our contributing guide for details.

📄 License

🔗 Links

npm: https://www.npmjs.com/package/tgreport
GitHub: https://github.com/testgrid/tgreport
Issues: https://github.com/testgrid/tgreport/issues
Documentation: https://github.com/testgrid/tgreport#readme

⭐ Support

If you find TGReport useful, please consider:

⭐ Star the project on GitHub
📢 Share with your team
🐛 Report issues
💡 Suggest features
🤝 Contribute code

🚀 Get Started Now!

npm install tgreport --save-dev

Choose your framework and check the Quick Start section above!

Made with ❤️ by TestGrid Team

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

📊 TGReport

✨ Features

📸 Features Preview

Test History & Trends

🚀 Quick Start

Installation

Mocha

Playwright

WebdriverIO

Jasmine

📖 Usage

Context API

Configuration Options

🎨 Report Formats

HTML Report

PDF Export

CSV Export

JSON Export

📊 Test History Tracking

CLI Commands

🖥️ React Viewer

🎯 Framework Compatibility

💻 JavaScript & TypeScript

Pure JavaScript ✅

TypeScript ✅

📦 What You Get

🔧 Advanced Features

Custom Branding

Parallel Execution

Media Handling

Auto-Capture on Failure

📚 Documentation

🎯 Use Cases

CI/CD Integration

Quality Tracking

Team Reporting

🆚 Comparison

🎓 Examples

Example 1: Basic Mocha Test

Example 2: Playwright with Screenshots

Example 3: Jasmine with Custom Branding

Example 4: WebdriverIO with Context

📋 Requirements

🛠️ Configuration

All Available Options

🎨 Customization

Custom Colors

File Naming

Themes

📸 Screenshots & Media

Supported Formats

Auto-Copy to Report

🔍 Advanced Features

History Trends

Parallel Execution

Media Lightbox

🤝 Contributing

📄 License

🔗 Links

⭐ Support

🚀 Get Started Now!