express-api-stress-tester 2.0.0 → 2.0.2

package/README.md

@@ -14,8 +14,10 @@
 - 🔀 **Distributed architecture** — master/worker TCP coordination for horizontal scaling
 - 📊 **Real-time terminal dashboard** — live RPS, latency, error rate, CPU, and memory graphs
 - 🎯 **Multi-route testing** — test multiple endpoints with weighted traffic distribution
+- 🧭 **Per-endpoint analytics** — separate metrics per API route
 - 🎭 **Scenario testing** — simulate real user flows across sequential API calls
 - 📈 **Advanced metrics** — P95, P99, min, max latency with reservoir sampling
+- 📶 **Adaptive load engine** — ramp-up, ramp-down, target RPS, burst traffic
 - 📝 **Multi-format reports** — TXT, JSON, and HTML reports with pass/fail status
 - 🔌 **Plugin system** — payload generators, auth providers, header providers, interceptors, and custom metrics collectors
 - 🧪 **Express integration** — auto-detect routes and stress test Express apps directly
@@ -142,11 +144,19 @@ console.log(result);
 | `payloads`            | array    | —         | Bulk payloads — array of objects distributed round-robin        |
 | `payloadFile`         | string   | —         | Path to a CSV or JSON dataset file                              |
 | `concurrency`         | number   | `1`       | Number of concurrent virtual users                              |
+| `maxUsers`            | number   | —         | Alias for `concurrency` when using adaptive ramping             |
+| `startConcurrency`    | number   | `1`       | Initial concurrency for ramp-up                                 |
+| `rampUp`              | number   | `0`       | Ramp-up time in seconds (linear)                                |
+| `rampDown`            | number   | `0`       | Ramp-down time in seconds (linear)                              |
+| `targetRPS`           | number   | —         | Adaptive target requests/sec                                    |
+| `adaptiveIntervalMs`  | number   | `1000`    | Minimum interval between adaptive adjustments (ms)             |
+| `burst`               | object   | —         | Burst traffic config: `{ start, duration, multiplier, maxUsers }` |
 | `duration`            | number   | `10`      | Test duration in seconds                                        |
 | `routes`              | array    | —         | Array of route objects for multi-route testing                  |
 | `trafficDistribution` | array    | —         | Weighted traffic distribution across routes                     |
 | `scenarios`           | array    | —         | Scenario definitions for user flow simulation                   |
 | `thresholds`          | object   | —         | Pass/fail thresholds                                            |
+| `plugins`             | array    | —         | Plugin module paths to load in worker threads                   |
 
 ### Single URL Config
 
@@ -203,6 +213,22 @@ Test multiple API endpoints simultaneously with optional weighted traffic distri
 
 ---
 
+## Per-Endpoint Metrics
+
+When multiple routes or scenarios are tested, the report and dashboard include **separate metrics per API endpoint** (RPS, latency, error rate).
+
+Example snippet from the TXT report:
+
+```
+Per-Endpoint Metrics:
+Endpoint                               RPS   Avg(ms)   P95(ms)   Errors(%)
+----------------------------------------------------------------------------
+GET /login                             5200     120       210      0.5
+POST /orders                           3100     210       410      1.3
+```
+
+---
+
 ## Scenario Testing
 
 Simulate real user flows by defining sequential steps that execute in order.
@@ -234,6 +260,25 @@ Each virtual user executes the steps sequentially, simulating a realistic browsi
 
 ---
 
+## Adaptive Load & Burst Traffic
+
+Use ramp-up, ramp-down, target RPS, and burst windows to shape traffic patterns.
+
+```json
+{
+  "baseUrl": "https://api.example.com",
+  "routes": [{ "path": "/login", "method": "POST" }],
+  "maxUsers": 100000,
+  "startConcurrency": 1000,
+  "rampUp": 30,
+  "rampDown": 10,
+  "targetRPS": 50000,
+  "burst": { "start": 20, "duration": 5, "multiplier": 2 }
+}
+```
+
+---
+
 ## Dynamic Payloads
 
 Use placeholders in your payload values. They are replaced with fresh random data for **every request**.
@@ -382,6 +427,16 @@ When thresholds are set, the summary `result` field returns `PASSED` or `FAILED`
 
 Scale horizontally across multiple machines using the built-in TCP-based master/worker coordination.
 
+### CLI Usage
+
+```bash
+# Start master with config
+npx express-api-stress-tester master config.json --port 7654 --workers 3
+
+# Start workers (run on other machines)
+npx express-api-stress-tester worker --host 127.0.0.1 --port 7654
+```
+
 ### Master Node
 
 ```js
@@ -547,6 +602,18 @@ const headers = authPlugins[0].handler();
 console.log(headers); // { Authorization: 'Bearer my-secret-token' }
 ```
 
+### Loading Plugins via Config
+
+```json
+{
+  "url": "https://api.example.com/users",
+  "method": "GET",
+  "concurrency": 100,
+  "duration": 10,
+  "plugins": ["./plugins/authPlugin.js", "./plugins/requestLogger.js"]
+}
+```
+
 ---
 
 ## Real-Time Dashboard
@@ -574,6 +641,7 @@ The dashboard displays:
 - Updates every 1 second
 - Color-coded indicators: 🟢 green (healthy), 🟡 yellow (warning), 🔴 red (critical)
 - 60-second RPS history with ASCII bar chart
+- Per-endpoint table with live RPS, latency, and error rate
 - Clean exit on test completion
 
 ---
@@ -640,7 +708,15 @@ Result:             PASSED
     "maxLatency": 320,
     "errorRate": 0.3,
     "successRate": 99.7,
-    "result": "PASSED"
+    "result": "PASSED",
+    "perEndpoint": {
+      "GET /users": {
+        "requestsPerSec": 620,
+        "avgResponseTime": 35,
+        "p95": 80,
+        "errorRate": 0.2
+      }
+    }
   }
 }
 ```
@@ -652,6 +728,8 @@ The HTML report is a self-contained file with:
 - Status badge (✓ PASSED or ✗ FAILED)
 - Test configuration table
 - Results summary table with all metrics
+- Latency, request rate, and error distribution charts
+- Per-endpoint metrics table
 - Timestamp of generation
 - Embedded CSS — no external dependencies
 
@@ -690,6 +768,7 @@ express-api-stress-tester/
 │   │
 │   ├── metrics/
 │   │   ├── metricsCollector.js           # Metrics aggregation + percentiles
+│   │   ├── apiMetrics.js                 # Per-endpoint metrics collector
 │   │   └── systemMetrics.js              # CPU & memory monitoring
 │   │
 │   ├── reporting/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "express-api-stress-tester",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "High-performance distributed API stress testing platform for Express.js APIs — simulate up to 10M concurrent virtual users",
   "type": "module",
   "main": "src/index.js",

package/src/cli.js

@@ -13,10 +13,12 @@ import { createRequire } from 'node:module';
 import { Command } from 'commander';
 import chalk from 'chalk';
 import { runStressTest } from './core/runner.js';
-import { CliDashboard } from './dashboard/cliDashboard.js';
+import { MasterNode, WorkerNode } from './core/distributedCoordinator.js';
+import { ReportWriter } from './reporting/reportWriter.js';
 
 const require = createRequire(import.meta.url);
 const pkg = require('../package.json');
+const DEFAULT_MAX_ERROR_RATE_PERCENT = 5;
 
 function loadConfig(configPath) {
   const fullPath = resolve(configPath);
@@ -51,12 +53,6 @@ function printSummary(summary) {
 async function runCommand(configPath, opts) {
   const config = loadConfig(configPath);
 
-  let dashboard = null;
-  if (opts.dashboard) {
-    dashboard = new CliDashboard();
-    dashboard.start();
-  }
-
   try {
     const summary = await runStressTest(config, {
       reportPath: opts.output || 'stress-test-report.txt',
@@ -64,19 +60,95 @@ async function runCommand(configPath, opts) {
       dashboard: opts.dashboard,
     });
 
-    if (dashboard) {
-      dashboard.stop();
-    }
-
     printSummary(summary);
     process.exit(summary.result === 'PASSED' ? 0 : 1);
   } catch (err) {
-    if (dashboard) dashboard.stop();
     console.error(chalk.red(`Stress test failed: ${err.message}`));
     process.exit(1);
   }
 }
 
+async function masterCommand(configPath, opts) {
+  const config = loadConfig(configPath);
+  const master = new MasterNode({ port: Number(opts.port) || 7654 });
+  await master.start();
+  console.log(chalk.green(`Master listening on port ${master.port}`));
+
+  const expected = Number(opts.workers || config.distributed?.workers || 0);
+  if (expected > 0) {
+    await waitForWorkers(master, expected, opts.timeout ? Number(opts.timeout) * 1000 : 60_000);
+  }
+
+  const results = await master.distributeWork(config);
+  const summary = await master.collectResults(results);
+  summary.result = applyThresholds(summary, config.thresholds);
+
+  const reportPath = opts.output || 'stress-test-report.txt';
+  const reportFormat = opts.format || 'txt';
+  const writer = new ReportWriter(config, summary);
+  writer.write(reportPath, reportFormat);
+
+  printSummary(summary);
+  await master.stop();
+  process.exit(summary.result === 'PASSED' ? 0 : 1);
+}
+
+async function workerCommand(opts) {
+  const worker = new WorkerNode({
+    masterHost: opts.host || '127.0.0.1',
+    masterPort: Number(opts.port) || 7654,
+  });
+  await worker.connect();
+  console.log(chalk.green(`Worker connected to ${worker.masterHost}:${worker.masterPort}`));
+  await new Promise((resolve) => {
+    if (worker.socket) {
+      worker.socket.on('close', resolve);
+    } else {
+      resolve();
+    }
+  });
+  process.exit(0);
+}
+
+async function waitForWorkers(master, count, timeoutMs) {
+  const start = Date.now();
+  while (master.workers.size < count) {
+    if (timeoutMs && Date.now() - start > timeoutMs) {
+      throw new Error(`Timed out waiting for ${count} workers to connect`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, 500));
+  }
+}
+
+function applyThresholds(summary, thresholds) {
+  if (!thresholds) {
+    return summary.errorRate < DEFAULT_MAX_ERROR_RATE_PERCENT ? 'PASSED' : 'FAILED';
+  }
+
+  if (
+    thresholds.maxErrorRate != null &&
+    summary.errorRate > thresholds.maxErrorRate
+  ) {
+    return 'FAILED';
+  }
+
+  if (
+    thresholds.maxAvgLatency != null &&
+    summary.avgResponseTime > thresholds.maxAvgLatency
+  ) {
+    return 'FAILED';
+  }
+
+  if (
+    thresholds.minRPS != null &&
+    summary.requestsPerSec < thresholds.minRPS
+  ) {
+    return 'FAILED';
+  }
+
+  return 'PASSED';
+}
+
 async function main() {
   const program = new Command();
 
@@ -93,9 +165,35 @@ async function main() {
     .option('--output <path>', 'Report output file path')
     .action(runCommand);
 
+  program
+    .command('master <config>')
+    .description('Run a distributed master and coordinate connected workers')
+    .option('--port <port>', 'Master listen port', '7654')
+    .option('--workers <count>', 'Number of workers to wait for')
+    .option('--timeout <seconds>', 'Wait timeout for workers', '60')
+    .option('--format <format>', 'Report format: txt, json, html', 'txt')
+    .option('--output <path>', 'Report output file path')
+    .action(masterCommand);
+
+  program
+    .command('worker')
+    .description('Start a worker node and connect to a master')
+    .option('--host <host>', 'Master host', '127.0.0.1')
+    .option('--port <port>', 'Master port', '7654')
+    .action(workerCommand);
+
   // Backward compatibility: if first arg is not a known command, treat as config path
   const args = process.argv.slice(2);
-  const knownCommands = ['run', 'help', '--help', '-h', '--version', '-V'];
+  const knownCommands = [
+    'run',
+    'master',
+    'worker',
+    'help',
+    '--help',
+    '-h',
+    '--version',
+    '-V',
+  ];
   if (args.length > 0 && !knownCommands.includes(args[0])) {
     // Rewrite argv to include 'run' subcommand
     const configArg = args[0];

package/src/core/distributedCoordinator.js

@@ -150,6 +150,7 @@ export class MasterNode {
       errorRate: 0,
       successRate: 0,
       result: 'PASSED',
+      perEndpoint: {},
     };
 
     let totalResponseTimeWeighted = 0;
@@ -158,6 +159,9 @@ export class MasterNode {
       combined.totalRequests += r.totalRequests || 0;
       combined.requestsPerSec += r.requestsPerSec || 0;
       totalResponseTimeWeighted += (r.avgResponseTime || 0) * (r.totalRequests || 0);
+      if (r.perEndpoint) {
+        mergeEndpointSummaries(combined.perEndpoint, r.perEndpoint);
+      }
     }
 
     if (combined.totalRequests > 0) {
@@ -307,3 +311,51 @@ export class WorkerNode {
     });
   }
 }
+
+function mergeEndpointSummaries(target, source) {
+  for (const [endpoint, metrics] of Object.entries(source)) {
+    if (!target[endpoint]) {
+      target[endpoint] = {
+        totalRequests: 0,
+        requestsPerSec: 0,
+        avgResponseTime: 0,
+        errorRate: 0,
+        successRate: 0,
+        p95: 0,
+        p99: 0,
+        minLatency: metrics.minLatency ?? 0,
+        maxLatency: metrics.maxLatency ?? 0,
+      };
+    }
+
+    const current = target[endpoint];
+    const totalBefore = current.totalRequests;
+    const totalAfter = totalBefore + (metrics.totalRequests || 0);
+
+    current.totalRequests = totalAfter;
+    current.requestsPerSec += metrics.requestsPerSec || 0;
+    current.avgResponseTime =
+      totalAfter > 0
+        ? Math.round(
+          ((current.avgResponseTime || 0) * totalBefore +
+            (metrics.avgResponseTime || 0) * (metrics.totalRequests || 0)) / totalAfter,
+        )
+        : 0;
+    current.errorRate =
+      totalAfter > 0
+        ? parseFloat(
+          (
+            (((current.errorRate || 0) / 100) * totalBefore +
+              ((metrics.errorRate || 0) / 100) * (metrics.totalRequests || 0)) /
+              totalAfter *
+              100
+          ).toFixed(1),
+        )
+        : 0;
+    current.successRate = parseFloat((100 - current.errorRate).toFixed(1));
+    current.p95 = Math.max(current.p95 || 0, metrics.p95 || 0);
+    current.p99 = Math.max(current.p99 || 0, metrics.p99 || 0);
+    current.minLatency = Math.min(current.minLatency ?? Infinity, metrics.minLatency ?? Infinity);
+    current.maxLatency = Math.max(current.maxLatency ?? 0, metrics.maxLatency ?? 0);
+  }
+}

package/src/core/httpEngine.js

@@ -6,6 +6,9 @@
  */
 import { Pool } from 'undici';
 
+const CONTROL_CHARS_REGEX = /[\0\r\n]/g;
+const MAX_WARNED_HEADER_VALUES = 100;
+
 export class HttpEngine {
   /**
    * @param {object} options
@@ -31,6 +34,7 @@ export class HttpEngine {
     this.baseUrl = baseUrl;
     this.defaultHeaders = headers;
     this.timeout = timeout;
+    this.invalidHeaderWarningCache = { map: new Map(), queue: [] };
 
     this.pool = new Pool(baseUrl, {
       connections,
@@ -53,7 +57,10 @@ export class HttpEngine {
    * @returns {Promise<{ statusCode: number, headers: object, body: string, responseTime: number }>}
    */
   async request({ method = 'GET', path = '/', headers = {}, body = null } = {}) {
-    const mergedHeaders = { ...this.defaultHeaders, ...headers };
+    const mergedHeaders = normalizeHeaders(
+      { ...this.defaultHeaders, ...headers },
+      this.invalidHeaderWarningCache,
+    );
 
     const start = process.hrtime.bigint();
 
@@ -88,3 +95,95 @@ export class HttpEngine {
     await this.pool.close();
   }
 }
+
+function normalizeHeaders(headers, warningCache) {
+  const normalized = {};
+  for (const [key, value] of Object.entries(headers || {})) {
+    if (value === undefined || value === null) {
+      continue;
+    }
+    const normalizedKey = normalizeHeaderKey(key);
+    if (normalizedKey === null) {
+      continue;
+    }
+    if (Array.isArray(value)) {
+      const cleaned = [];
+      for (const entry of value) {
+        if (entry === undefined || entry === null) {
+          continue;
+        }
+        if (isValidHeaderValue(entry)) {
+          const cleanedEntry = normalizeHeaderValue(entry);
+          if (cleanedEntry !== null) {
+            cleaned.push(cleanedEntry);
+          }
+        } else {
+          warnInvalidHeaderValue(normalizedKey, entry, warningCache);
+        }
+      }
+      if (cleaned.length > 0) {
+        normalized[normalizedKey] = cleaned;
+      }
+      continue;
+    }
+
+    if (!isValidHeaderValue(value)) {
+      warnInvalidHeaderValue(normalizedKey, value, warningCache);
+      continue;
+    }
+
+    const cleanedValue = normalizeHeaderValue(value);
+    if (cleanedValue === null) {
+      continue;
+    }
+    normalized[normalizedKey] = cleanedValue;
+  }
+  return normalized;
+}
+
+function normalizeHeaderKey(value) {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const cleaned = value.replace(CONTROL_CHARS_REGEX, '');
+  return cleaned.length > 0 ? cleaned : null;
+}
+
+function normalizeHeaderValue(value) {
+  if (typeof value === 'string') {
+    const cleaned = value.replace(CONTROL_CHARS_REGEX, '');
+    return cleaned.length > 0 ? cleaned : null;
+  }
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value);
+  }
+  return null;
+}
+
+function isValidHeaderValue(value) {
+  return (
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  );
+}
+
+function warnInvalidHeaderValue(key, value, warningCache) {
+  const type = typeof value;
+  const safeKey = key;
+  const signature = `${safeKey}::${type}`;
+  if (warningCache.map.has(signature)) {
+    return;
+  }
+  warningCache.map.set(signature, true);
+  warningCache.queue.push(signature);
+  if (warningCache.queue.length > MAX_WARNED_HEADER_VALUES) {
+    const oldest = warningCache.queue.shift();
+    if (oldest) {
+      warningCache.map.delete(oldest);
+    }
+  }
+  process.stderr.write(
+    `[HttpEngine] Dropping header "${safeKey}" with unsupported value type "${type}".\n`,
+  );
+}