@forgeframework/perf

Performance testing framework for the Forge Framework.

Part of the Forge Framework — a TypeScript framework for backend microservices and web applications.

Installation

npm install @forgeframework/perf

Usage

import { PerfTestRunner, PerfReporter } from '@forgeframework/perf';

const runner = new PerfTestRunner({
  concurrentUsers: 100,
  duration: 120,
  rampUp: 30,
  baseUrl: 'https://api.staging.example.com',
  thresholds: {
    maxP95ResponseTime: 500,
    minSuccessRate: 99.5,
    minThroughput: 200,
  },
  resourceMonitor: true,
  reportFormats: ['console', 'html', 'json'],
  outputDir: './perf-results',
  keepAlive: true,
});

const report = await runner.run([
  {
    name: 'List Products',
    request: {
      url: '/api/v1/products',
      method: 'GET',
      headers: { Authorization: `Bearer ${process.env.API_TOKEN}` },
    },
    weight: 5,
    thresholds: {
      maxP95ResponseTime: 300,
      minSuccessRate: 99.9,
    },
  },
  {
    name: 'Get Product Detail',
    request: {
      url: '/api/v1/products/123',
      method: 'GET',
    },
    weight: 3,
  },
  {
    name: 'Create Order',
    request: {
      url: '/api/v1/orders',
      method: 'POST',
      body: { productId: '123', quantity: 1 },
    },
    weight: 1,
    thresholds: {
      maxP95ResponseTime: 800,
    },
    loadProfile: {
      type: 'ramp',
      startUsers: 10,
      endUsers: 50,
      rampDuration: 60,
      holdDuration: 60,
    },
  },
  {
    name: 'Search Products',
    request: {
      url: '/api/v1/products/search?q=widget',
      method: 'GET',
    },
    weight: 2,
  },
]);

console.log(PerfReporter.console(report));

if (!report.passed) {
  const failed = report.thresholdResults.filter((t) => !t.passed);
  failed.forEach((t) => {
    console.error(
      `Threshold failed: ${t.assertion.metric} ${t.assertion.operator} ${t.assertion.value} (actual: ${t.actual})`,
    );
  });
  process.exit(1);
}

Documentation

Full API reference and guides: https://carbonforge.io/framework/docs/test/perf

(Documentation site launching soon.)

License

MIT © Carbon Forge