express-api-stress-tester 2.0.0 → 2.0.2

package/src/metrics/apiMetrics.js

@@ -0,0 +1,116 @@
+/**
+ * Per-endpoint metrics collector with percentile support.
+ */
+const RESERVOIR_SIZE = 5_000;
+
+export class ApiMetrics {
+  constructor() {
+    this.totalRequests = 0;
+    this.successCount = 0;
+    this.errorCount = 0;
+    this.totalResponseTime = 0;
+    this.minLatency = Infinity;
+    this.maxLatency = -Infinity;
+    this.responseTimes = [];
+    this._sampleCount = 0;
+  }
+
+  record(responseTimeMs, isError) {
+    this.totalRequests++;
+    this.totalResponseTime += responseTimeMs;
+
+    if (responseTimeMs < this.minLatency) this.minLatency = responseTimeMs;
+    if (responseTimeMs > this.maxLatency) this.maxLatency = responseTimeMs;
+
+    if (isError) {
+      this.errorCount++;
+    } else {
+      this.successCount++;
+    }
+
+    this._sampleCount++;
+    if (this.responseTimes.length < RESERVOIR_SIZE) {
+      this.responseTimes.push(responseTimeMs);
+    } else {
+      const j = Math.floor(Math.random() * this._sampleCount);
+      if (j < RESERVOIR_SIZE) {
+        this.responseTimes[j] = responseTimeMs;
+      }
+    }
+  }
+
+  merge(partial) {
+    this.totalRequests += partial.totalRequests || 0;
+    this.successCount += partial.successCount || 0;
+    this.errorCount += partial.errorCount || 0;
+    this.totalResponseTime += partial.totalResponseTime || 0;
+
+    if (partial.minLatency !== undefined && partial.minLatency < this.minLatency) {
+      this.minLatency = partial.minLatency;
+    }
+    if (partial.maxLatency !== undefined && partial.maxLatency > this.maxLatency) {
+      this.maxLatency = partial.maxLatency;
+    }
+
+    if (partial.responseTimes) {
+      this.mergeResponseTimes(partial.responseTimes);
+    }
+  }
+
+  mergeResponseTimes(times) {
+    if (!Array.isArray(times) || times.length === 0) return;
+    for (const t of times) {
+      this._sampleCount++;
+      if (this.responseTimes.length < RESERVOIR_SIZE) {
+        this.responseTimes.push(t);
+      } else {
+        const j = Math.floor(Math.random() * this._sampleCount);
+        if (j < RESERVOIR_SIZE) {
+          this.responseTimes[j] = t;
+        }
+      }
+    }
+  }
+
+  _percentile(sorted, p) {
+    if (sorted.length === 0) return 0;
+    const idx = Math.ceil((p / 100) * sorted.length) - 1;
+    return sorted[Math.max(0, idx)];
+  }
+
+  getSummary(elapsedSeconds = 1) {
+    const elapsed = elapsedSeconds || 1;
+    const rps = (this.totalRequests / elapsed).toFixed(0);
+    const avgResponse =
+      this.totalRequests > 0
+        ? (this.totalResponseTime / this.totalRequests).toFixed(0)
+        : 0;
+    const errorRate =
+      this.totalRequests > 0
+        ? ((this.errorCount / this.totalRequests) * 100).toFixed(1)
+        : '0.0';
+    const successRate =
+      this.totalRequests > 0
+        ? ((this.successCount / this.totalRequests) * 100).toFixed(1)
+        : '0.0';
+
+    const sorted = [...this.responseTimes].sort((a, b) => a - b);
+    const p95 = this._percentile(sorted, 95);
+    const p99 = this._percentile(sorted, 99);
+
+    const minLat = this.minLatency === Infinity ? 0 : this.minLatency;
+    const maxLat = this.maxLatency === -Infinity ? 0 : this.maxLatency;
+
+    return {
+      totalRequests: this.totalRequests,
+      requestsPerSec: Number(rps),
+      avgResponseTime: Number(avgResponse),
+      p95,
+      p99,
+      minLatency: minLat,
+      maxLatency: maxLat,
+      errorRate: parseFloat(errorRate),
+      successRate: parseFloat(successRate),
+    };
+  }
+}

package/src/metrics/metricsCollector.js

@@ -3,6 +3,7 @@
  * Backward-compatible with v1 API, adds reservoir sampling for latency percentiles.
  */
 import { cpus } from 'node:os';
+import { ApiMetrics } from './apiMetrics.js';
 
 const RESERVOIR_SIZE = 10_000;
 
@@ -19,6 +20,7 @@ export class MetricsCollector {
     // Reservoir sampling for percentile calculation
     this.responseTimes = [];
     this._sampleCount = 0;
+    this.perEndpoint = new Map();
   }
 
   start() {
@@ -70,6 +72,12 @@ export class MetricsCollector {
     if (partial.responseTimes) {
       this.mergeResponseTimes(partial.responseTimes);
     }
+
+    if (partial.perEndpoint) {
+      for (const [endpoint, metrics] of Object.entries(partial.perEndpoint)) {
+        this._getEndpointMetrics(endpoint).merge(metrics);
+      }
+    }
   }
 
   mergeResponseTimes(times) {
@@ -87,6 +95,13 @@ export class MetricsCollector {
     }
   }
 
+  _getEndpointMetrics(endpoint) {
+    if (!this.perEndpoint.has(endpoint)) {
+      this.perEndpoint.set(endpoint, new ApiMetrics());
+    }
+    return this.perEndpoint.get(endpoint);
+  }
+
   static getResourceUsage() {
     const mem = process.memoryUsage();
     const cpuArray = cpus();
@@ -109,7 +124,8 @@ export class MetricsCollector {
   }
 
   getSummary(thresholds) {
-    const elapsed = (this.endTime - this.startTime) / 1000 || 1;
+    const endTime = this.endTime || Date.now();
+    const elapsed = (endTime - this.startTime) / 1000 || 1;
     const rps = (this.totalRequests / elapsed).toFixed(0);
     const avgResponse =
       this.totalRequests > 0
@@ -169,6 +185,15 @@ export class MetricsCollector {
       memoryMB,
       result: passed ? 'PASSED' : 'FAILED',
       elapsedSeconds: elapsed.toFixed(1),
+      perEndpoint: this._buildEndpointSummaries(elapsed),
     };
   }
+
+  _buildEndpointSummaries(elapsed) {
+    const summaries = {};
+    for (const [endpoint, metrics] of this.perEndpoint.entries()) {
+      summaries[endpoint] = metrics.getSummary(elapsed);
+    }
+    return summaries;
+  }
 }

package/src/reporting/htmlReport.js

@@ -39,6 +39,30 @@ export function generateHtmlReport(config, summary) {
     ...(config.totalRequests ? [['Total Requests', config.totalRequests]] : []),
   ];
 
+  const perEndpointRows = Object.entries(summary.perEndpoint || {}).map(
+    ([endpoint, metrics]) => [
+      endpoint,
+      metrics.requestsPerSec ?? 0,
+      `${metrics.avgResponseTime ?? 0} ms`,
+      `${metrics.p95 ?? 0} ms`,
+      `${metrics.errorRate ?? 0}%`,
+    ],
+  );
+
+  const successRate = summary.successRate || 0;
+  const errorRate = summary.errorRate || 0;
+  const maxLatency = Math.max(summary.p99 || 0, summary.maxLatency || 0, 1);
+  const maxRps = Math.max(
+    summary.requestsPerSec || 0,
+    ...perEndpointRows.map(([, rps]) => Number(rps) || 0),
+    1,
+  );
+  const latencyBars = [
+    { label: 'Avg', value: summary.avgResponseTime || 0 },
+    { label: 'P95', value: summary.p95 || 0 },
+    { label: 'P99', value: summary.p99 || 0 },
+  ];
+
   return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -58,6 +82,14 @@ export function generateHtmlReport(config, summary) {
   th { font-weight: 600; color: #64748b; width: 40%; }
   td { color: #1e293b; font-variant-numeric: tabular-nums; }
   tr:last-child th, tr:last-child td { border-bottom: none; }
+  .chart { margin-top: 1rem; }
+  .chart h3 { font-size: 1rem; color: #334155; margin: 0.75rem 0; }
+  .bar { display: flex; align-items: center; margin-bottom: 0.5rem; gap: 0.5rem; }
+  .bar-label { width: 60px; font-size: 0.85rem; color: #64748b; }
+  .bar-track { flex: 1; height: 10px; background: #e2e8f0; border-radius: 9999px; overflow: hidden; }
+  .bar-fill { height: 100%; background: #38bdf8; }
+  .bar-fill.error { background: #f87171; }
+  .bar-fill.success { background: #22c55e; }
   .timestamp { color: #94a3b8; font-size: 0.8rem; margin-top: 1rem; text-align: center; }
 </style>
 </head>
@@ -78,8 +110,44 @@ ${configRows.map(([k, v]) => `      <tr><th>${esc(k)}</th><td>${esc(v)}</td></tr
     <table>
 ${metricRows.map(([k, v]) => `      <tr><th>${esc(k)}</th><td>${esc(v)}</td></tr>`).join('\n')}
     </table>
+    <div class="chart">
+      <h3>Latency Graph</h3>
+${latencyBars.map((bar) => `
+      <div class="bar">
+        <div class="bar-label">${esc(bar.label)}</div>
+        <div class="bar-track"><div class="bar-fill" style="width:${Math.min(100, (bar.value / maxLatency) * 100)}%"></div></div>
+      </div>`).join('')}
+    </div>
+    <div class="chart">
+      <h3>Request Rate</h3>
+      <div class="bar">
+        <div class="bar-label">RPS</div>
+        <div class="bar-track"><div class="bar-fill" style="width:${Math.min(100, (summary.requestsPerSec / maxRps) * 100)}%"></div></div>
+      </div>
+    </div>
+    <div class="chart">
+      <h3>Error Distribution</h3>
+      <div class="bar">
+        <div class="bar-label">Success</div>
+        <div class="bar-track"><div class="bar-fill success" style="width:${Math.min(100, successRate)}%"></div></div>
+      </div>
+      <div class="bar">
+        <div class="bar-label">Error</div>
+        <div class="bar-track"><div class="bar-fill error" style="width:${Math.min(100, errorRate)}%"></div></div>
+      </div>
+    </div>
   </div>
 
+  ${perEndpointRows.length > 0 ? `
+  <div class="section">
+    <h2>Per-Endpoint Metrics</h2>
+    <table>
+      <tr><th>Endpoint</th><th>RPS</th><th>Avg Latency</th><th>P95</th><th>Error Rate</th></tr>
+${perEndpointRows.map(([endpoint, rps, avg, p95, err]) => `
+      <tr><td>${esc(endpoint)}</td><td>${esc(rps)}</td><td>${esc(avg)}</td><td>${esc(p95)}</td><td>${esc(err)}</td></tr>`).join('\n')}
+    </table>
+  </div>` : ''}
+
   <p class="timestamp">Generated at ${new Date().toISOString()}</p>
 </div>
 </body>

package/src/reporting/reportWriter.js

@@ -47,11 +47,52 @@ function buildTxtReport(config, summary) {
     `Memory Usage:       ${summary.memoryMB}MB`,
     `Result:             ${summary.result}`,
     divider,
+    ...(buildEndpointLines(summary.perEndpoint) || []),
     '',
   ];
   return lines.join('\n');
 }
 
+function buildEndpointLines(perEndpoint) {
+  if (!perEndpoint || Object.keys(perEndpoint).length === 0) {
+    return [];
+  }
+
+  const lines = [];
+  lines.push('Per-Endpoint Metrics:');
+
+  const entries = Object.entries(perEndpoint).sort(
+    (a, b) => (b[1].requestsPerSec || 0) - (a[1].requestsPerSec || 0),
+  );
+  const maxEndpointLength = Math.min(
+    50,
+    Math.max(8, ...entries.map(([endpoint]) => endpoint.length)),
+  );
+  lines.push(
+    `${'Endpoint'.padEnd(maxEndpointLength)}  RPS   Avg(ms)   P95(ms)   Errors(%)`,
+  );
+  lines.push('-'.repeat(maxEndpointLength + 38));
+  for (const [endpoint, metrics] of entries) {
+    const displayEndpoint =
+      endpoint.length > maxEndpointLength
+        ? `${endpoint.slice(0, maxEndpointLength - 3)}...`
+        : endpoint;
+    const rps = String(metrics.requestsPerSec ?? 0).padStart(5);
+    const avg = String(metrics.avgResponseTime ?? 0).padStart(7);
+    const p95 = String(metrics.p95 ?? 0).padStart(7);
+    const errValue =
+      typeof metrics.errorRate === 'string'
+        ? parseFloat(metrics.errorRate)
+        : (metrics.errorRate ?? 0);
+    const err = `${errValue.toFixed(1)}%`.padStart(8);
+    lines.push(
+      `${displayEndpoint.padEnd(maxEndpointLength)} ${rps} ${avg} ${p95} ${err}`,
+    );
+  }
+  lines.push('');
+  return lines;
+}
+
 export class ReportWriter {
   constructor(config, summary) {
     this.config = config;