@web-engine-dev/benchmark

Performance benchmarking and regression detection for web-engine.

Features

• Micro-Benchmarks: Measure specific operations
• Frame Timing: FPS and frame time analysis
• Memory Profiling: Heap usage tracking
• Regression Detection: Detect performance regressions
• Reporting: HTML/JSON reports

Installation

npm install @web-engine-dev/benchmark
# or
pnpm add @web-engine-dev/benchmark

Quick Start

import { Benchmark, BenchmarkSuite } from '@web-engine-dev/benchmark';

// Create benchmark suite
const suite = new BenchmarkSuite('ECS Performance');

suite.add('spawn 10k entities', () => {
  for (let i = 0; i < 10000; i++) {
    world.spawn().with(Position).with(Velocity);
  }
});

suite.add('query iteration', () => {
  for (const [pos, vel] of query) {
    pos.x += vel.x;
  }
});

// Run benchmarks
const results = await suite.run();
console.log(results.format());

API Overview

Benchmark Suite

const suite = new BenchmarkSuite('My Benchmarks', {
  warmupIterations: 5,
  iterations: 100,
  timeout: 10000,
});

suite.add('test name', fn, {
  setup: () => {
    /* setup */
  },
  teardown: () => {
    /* cleanup */
  },
});

const results = await suite.run();

Frame Timing

import { FrameTimer } from '@web-engine-dev/benchmark';

const timer = new FrameTimer();

// In game loop
timer.begin();
// ... game logic ...
timer.end();

// Get stats
const stats = timer.getStats();
console.log(stats.fps);
console.log(stats.avgFrameTime);
console.log(stats.p99FrameTime);

Regression Detection

const baseline = await loadBaseline('baseline.json');
const current = await suite.run();

const regressions = detectRegressions(baseline, current, {
  threshold: 0.1, // 10% regression threshold
});

if (regressions.length > 0) {
  console.error('Performance regressions detected!');
}

Reporting

const results = await suite.run();

// Console output
console.log(results.format());

// JSON export
await results.saveJSON('benchmark-results.json');

// HTML report
await results.saveHTML('benchmark-report.html');