express-api-stress-tester 2.0.0 → 2.0.2

package/src/core/runner.js

@@ -13,9 +13,11 @@ import { MetricsCollector } from '../metrics/metricsCollector.js';
 import { ReportWriter, log } from '../reporting/reportWriter.js';
 import { WorkerManager } from './workerManager.js';
 import { Scheduler } from './scheduler.js';
+import { CliDashboard } from '../dashboard/cliDashboard.js';
 
 const BATCH_SIZE = 200;
 const DEFAULT_NUM_WORKERS = Math.max(1, cpus().length - 1);
+const DEFAULT_ADAPTIVE_STEP_PERCENT = 0.05;
 
 /**
  * Run a stress test.
@@ -54,7 +56,8 @@ export async function runStressTest(config, options = {}) {
     }
   }
 
-  const concurrency = config.concurrency || 1;
+  const maxUsers = config.concurrency || config.maxUsers || 1;
+  const concurrency = maxUsers;
   const duration = config.duration || 10;
 
   const target = config.url || (hasRoutes ? `${config.routes.length} routes` : 'scenarios');
@@ -63,6 +66,18 @@ export async function runStressTest(config, options = {}) {
 
   // ── Setup ─────────────────────────────────────────────────────────
   const numWorkers = Math.min(DEFAULT_NUM_WORKERS, concurrency);
+  const startConcurrency = config.startConcurrency || 1;
+  const rampUp = config.rampUp || 0;
+  const rampDown = config.rampDown || 0;
+  const targetRPS = config.targetRPS;
+  const burst = config.burst || null;
+  const adaptiveStep = Math.max(
+    1,
+    Math.floor((config.adaptiveStep || maxUsers * DEFAULT_ADAPTIVE_STEP_PERCENT)),
+  );
+  const adaptiveIntervalMs = config.adaptiveIntervalMs || 1000;
+  let currentConcurrency = Math.min(maxUsers, startConcurrency);
+  let lastAdjustAt = 0;
   const scheduler = new Scheduler(config);
   const metrics = new MetricsCollector();
 
@@ -75,33 +90,78 @@ export async function runStressTest(config, options = {}) {
 
   await manager.start();
 
-  // ── Live dashboard (placeholder) ──────────────────────────────────
+  // ── Live dashboard ────────────────────────────────────────────────
   let dashboardInterval = null;
+  let dashboard = null;
   if (options.dashboard) {
+    dashboard = new CliDashboard();
+    dashboard.start();
     dashboardInterval = setInterval(() => {
       const snap = metrics.getSummary();
-      process.stdout.write(
-        `\r  RPS: ${snap.requestsPerSec} | Avg: ${snap.avgResponseTime}ms | Errors: ${snap.errorRate}%`,
-      );
+      dashboard.update({
+        activeUsers: currentConcurrency,
+        requestsPerSec: snap.requestsPerSec,
+        avgLatency: snap.avgResponseTime,
+        errorRate: snap.errorRate,
+        cpuPercent: snap.cpuPercent,
+        memoryMB: snap.memoryMB,
+        totalRequests: snap.totalRequests,
+        p95: snap.p95,
+        p99: snap.p99,
+        perEndpoint: snap.perEndpoint,
+      });
     }, 1000);
   }
 
   // ── Dispatch loop ─────────────────────────────────────────────────
   metrics.start();
   const endAt = Date.now() + duration * 1000;
-  const batchLimit = Math.min(BATCH_SIZE, Math.ceil(concurrency / numWorkers));
 
   while (Date.now() < endAt) {
     const batchPromises = [];
 
+    const now = Date.now();
+    const elapsedSeconds = (now - metrics.startTime) / 1000;
+    const { current, maxAllowed } = calculateConcurrency({
+      elapsedSeconds,
+      duration,
+      startConcurrency,
+      maxUsers,
+      rampUp,
+      rampDown,
+      burst,
+    });
+    currentConcurrency = current;
+
+    if (targetRPS && now - lastAdjustAt >= adaptiveIntervalMs) {
+      const elapsed = (Date.now() - metrics.startTime) / 1000 || 1;
+      const currentRps = Math.floor(metrics.totalRequests / elapsed);
+      if (currentRps < targetRPS * 0.98) {
+        currentConcurrency = Math.min(maxAllowed, currentConcurrency + adaptiveStep);
+      } else if (currentRps > targetRPS * 1.02) {
+        currentConcurrency = Math.max(1, currentConcurrency - adaptiveStep);
+      }
+      lastAdjustAt = now;
+    }
+
+    const batchLimit = Math.min(BATCH_SIZE, Math.ceil(currentConcurrency / numWorkers));
+
     for (let w = 0; w < numWorkers; w++) {
       // Build route assignments for this batch
       const routes = [];
       const tasks = [];
       for (let j = 0; j < batchLimit; j++) {
-        const route = scheduler.getNextRoute();
-        routes.push(route);
-        tasks.push(j);
+        if (hasScenarios) {
+          const scenario = scheduler.getNextScenario();
+          tasks.push({
+            steps: scenario.steps || [],
+            scenarioName: scenario.name,
+          });
+        } else {
+          const route = scheduler.getNextRoute();
+          routes.push(route);
+          tasks.push(j);
+        }
       }
 
       batchPromises.push(
@@ -116,7 +176,9 @@ export async function runStressTest(config, options = {}) {
 
   if (dashboardInterval) {
     clearInterval(dashboardInterval);
-    process.stdout.write('\n');
+  }
+  if (dashboard) {
+    dashboard.stop();
   }
 
   // ── Teardown ──────────────────────────────────────────────────────
@@ -170,3 +232,46 @@ function applyThresholds(summary, thresholds) {
 
   return 'PASSED';
 }
+
+function calculateConcurrency({
+  elapsedSeconds,
+  duration,
+  startConcurrency,
+  maxUsers,
+  rampUp,
+  rampDown,
+  burst,
+}) {
+  let desired = maxUsers;
+  const isBurstConfig = burst && typeof burst === 'object';
+  const burstStart = isBurstConfig ? (burst.start || 0) : 0;
+  const burstDuration = isBurstConfig ? (burst.duration || 0) : 0;
+  const burstMultiplier = isBurstConfig ? (burst.multiplier || 1) : 1;
+  const burstMax = isBurstConfig
+    ? burst.maxUsers || Math.round(maxUsers * burstMultiplier)
+    : maxUsers;
+  const inBurst =
+    isBurstConfig &&
+    elapsedSeconds >= burstStart &&
+    elapsedSeconds <= burstStart + burstDuration;
+  const maxAllowed = inBurst ? burstMax : maxUsers;
+  if (rampUp && elapsedSeconds < rampUp) {
+    const progress = elapsedSeconds / rampUp;
+    desired = Math.max(
+      1,
+      Math.round(startConcurrency + (maxUsers - startConcurrency) * progress),
+    );
+  }
+
+  if (rampDown && elapsedSeconds > duration - rampDown) {
+    const remaining = Math.max(0, duration - elapsedSeconds);
+    const progress = remaining / rampDown;
+    desired = Math.max(1, Math.round(startConcurrency + (maxUsers - startConcurrency) * progress));
+  }
+
+  if (inBurst) {
+    desired = Math.min(burstMax, Math.round(desired * burstMultiplier));
+  }
+
+  return { current: Math.min(maxAllowed, Math.max(1, desired)), maxAllowed };
+}

package/src/core/scheduler.js

@@ -18,6 +18,7 @@ export class Scheduler {
     this.scenarios = config.scenarios || [];
     this.weights = this._buildWeights();
     this.roundRobinIndex = 0;
+    this.scenarioIndex = 0;
   }
 
   // ── Route resolution ───────────────────────────────────────────────
@@ -155,4 +156,17 @@ export class Scheduler {
     if (this.scenarios.length === 0) return [];
     return this.scenarios[0].steps || [];
   }
+
+  /**
+   * Return the next scenario in round-robin order.
+   * @returns {object} scenario
+   */
+  getNextScenario() {
+    if (this.scenarios.length === 0) {
+      return { name: 'default', steps: [] };
+    }
+    const scenario = this.scenarios[this.scenarioIndex % this.scenarios.length];
+    this.scenarioIndex = (this.scenarioIndex + 1) % this.scenarios.length;
+    return scenario;
+  }
 }

package/src/core/worker.js

@@ -11,7 +11,11 @@
  *   worker → main : { type: 'result', metrics: { ... } }
  */
 import { parentPort, workerData } from 'node:worker_threads';
-import { request } from 'undici';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { PluginManager } from '../plugins/pluginManager.js';
+import { HttpEngine } from './httpEngine.js';
+import { DatasetLoader } from '../payload/datasetLoader.js';
 
 // Dynamic payload generation (best-effort import; fall back to identity)
 let resolvePayload = (v) => v;
@@ -25,6 +29,42 @@ try {
 }
 
 const config = workerData || {};
+const pluginManager = new PluginManager();
+const engineCache = new Map();
+let datasetLoader = null;
+let datasetIndex = 0;
+
+async function loadPlugins() {
+  const plugins = Array.isArray(config.plugins) ? config.plugins : [];
+  for (const entry of plugins) {
+    let moduleId = null;
+    try {
+      moduleId = typeof entry === 'string' ? entry : null;
+      if (!moduleId) continue;
+      const isPath = moduleId.startsWith('.') || moduleId.startsWith('/');
+      const pluginPath = resolve(process.cwd(), moduleId);
+      const resolved = isPath ? pathToFileURL(pluginPath).href : moduleId;
+      const mod = await import(resolved);
+      const pluginExport = mod.default || mod.plugin || mod.plugins;
+      if (Array.isArray(pluginExport)) {
+        for (const plugin of pluginExport) {
+          pluginManager.registerPlugin(plugin);
+        }
+      } else if (pluginExport) {
+        pluginManager.registerPlugin(pluginExport);
+      }
+    } catch (err) {
+      process.stderr.write(`[Worker] Failed to load plugin ${moduleId}: ${err.message}\n`);
+    }
+  }
+}
+
+await loadPlugins();
+
+if (config.payloadFile) {
+  datasetLoader = new DatasetLoader(config.payloadFile);
+  await datasetLoader.load();
+}
 
 // ── Reservoir sampling ─────────────────────────────────────────────
 const MAX_SAMPLE_SIZE = 1000;
@@ -49,29 +89,185 @@ let totalRequests = 0;
 let successCount = 0;
 let errorCount = 0;
 let totalResponseTime = 0;
+let minLatency = Infinity;
+let maxLatency = -Infinity;
 const statusCodes = {};
+const perEndpoint = {};
 
 /**
  * Resolve the full URL for a route.
  */
 function resolveUrl(route) {
   const base = route.baseUrl || config.baseUrl || config.url || '';
-  const path = route.path || '';
-
-  // If path is already a full URL, use it directly
+  const path = route.path || route.url || '';
+  try {
+    if (path) {
+      return new URL(path, base).toString();
+    }
+    if (base) {
+      return new URL(base).toString();
+    }
+  } catch {
+    // ignore
+  }
   if (path.startsWith('http://') || path.startsWith('https://')) {
     return path;
   }
+  const cleanBase = base.replace(/\/+$/, '');
+  const cleanPath = path.startsWith('/') ? path : `/${path}`;
+  return cleanBase ? `${cleanBase}${cleanPath}` : path;
+}
+
+function getEngine(baseUrl) {
+  if (!engineCache.has(baseUrl)) {
+    engineCache.set(
+      baseUrl,
+      new HttpEngine({
+        baseUrl,
+        connections: config.connections,
+        pipelining: config.pipelining,
+        timeout: config.timeout,
+        headers: config.headers || {},
+      }),
+    );
+  }
+  return engineCache.get(baseUrl);
+}
+
+function resolveEndpointKey(method, url, route) {
+  const path = route?.path || route?.url;
+  if (path && !path.startsWith('http://') && !path.startsWith('https://')) {
+    const cleanPath = path.split('?')[0];
+    return `${method} ${cleanPath}`;
+  }
+  try {
+    const parsed = new URL(url);
+    return `${method} ${parsed.pathname}`;
+  } catch {
+    return `${method} ${url}`;
+  }
+}
 
-  // If base already contains a path component and route.path is relative
-  if (base && path) {
-    // Strip trailing slash from base, ensure leading slash on path
-    const cleanBase = base.replace(/\/+$/, '');
-    const cleanPath = path.startsWith('/') ? path : `/${path}`;
-    return `${cleanBase}${cleanPath}`;
+function getEndpointMetrics(endpoint) {
+  if (!perEndpoint[endpoint]) {
+    perEndpoint[endpoint] = {
+      totalRequests: 0,
+      successCount: 0,
+      errorCount: 0,
+      totalResponseTime: 0,
+      minLatency: Infinity,
+      maxLatency: -Infinity,
+      responseTimes: [],
+      sampleCount: 0,
+    };
   }
+  return perEndpoint[endpoint];
+}
 
-  return base || path;
+function recordEndpoint(endpoint, elapsedMs, isError) {
+  const metrics = getEndpointMetrics(endpoint);
+  metrics.totalRequests++;
+  metrics.totalResponseTime += elapsedMs;
+  if (elapsedMs < metrics.minLatency) metrics.minLatency = elapsedMs;
+  if (elapsedMs > metrics.maxLatency) metrics.maxLatency = elapsedMs;
+  if (isError) {
+    metrics.errorCount++;
+  } else {
+    metrics.successCount++;
+  }
+  metrics.sampleCount++;
+  if (metrics.responseTimes.length < MAX_SAMPLE_SIZE) {
+    metrics.responseTimes.push(elapsedMs);
+  } else {
+    const idx = Math.floor(Math.random() * metrics.sampleCount);
+    if (idx < MAX_SAMPLE_SIZE) {
+      metrics.responseTimes[idx] = elapsedMs;
+    }
+  }
+}
+
+function recordRequestMetrics({ endpointKey, elapsedMs, isError, status }) {
+  totalRequests++;
+  totalResponseTime += elapsedMs;
+  reservoirSample(elapsedMs);
+  if (elapsedMs < minLatency) minLatency = elapsedMs;
+  if (elapsedMs > maxLatency) maxLatency = elapsedMs;
+
+  if (status) {
+    statusCodes[status] = (statusCodes[status] || 0) + 1;
+  }
+
+  if (isError) {
+    errorCount++;
+  } else {
+    successCount++;
+  }
+
+  recordEndpoint(endpointKey, elapsedMs, isError);
+}
+
+async function applyHeaderPlugins(headers) {
+  const plugins = [
+    ...pluginManager.getPlugins('authProvider'),
+    ...pluginManager.getPlugins('headerProvider'),
+  ];
+  for (const plugin of plugins) {
+    try {
+      const extra = await plugin.handler();
+      if (extra && typeof extra === 'object') {
+        Object.assign(headers, extra);
+      }
+    } catch (err) {
+      process.stderr.write(`[Worker] Header plugin error: ${err.message}\n`);
+    }
+  }
+}
+
+async function applyPayloadPlugins(payload) {
+  let merged = payload;
+  const plugins = pluginManager.getPlugins('payloadGenerator');
+  for (const plugin of plugins) {
+    try {
+      const generated = await plugin.handler();
+      if (generated !== undefined && generated !== null) {
+        if (merged && typeof merged === 'object' && typeof generated === 'object') {
+          merged = { ...merged, ...generated };
+        } else if (merged === null || merged === undefined) {
+          merged = generated;
+        }
+      }
+    } catch (err) {
+      process.stderr.write(`[Worker] Payload plugin error: ${err.message}\n`);
+    }
+  }
+  return merged;
+}
+
+async function applyRequestInterceptors(context) {
+  let ctx = { ...context };
+  const plugins = pluginManager.getPlugins('requestInterceptor');
+  for (const plugin of plugins) {
+    try {
+      const result = await plugin.handler(ctx);
+      if (result && typeof result === 'object') {
+        ctx = { ...ctx, ...result };
+      }
+    } catch (err) {
+      process.stderr.write(`[Worker] Request interceptor error: ${err.message}\n`);
+    }
+  }
+  return ctx;
+}
+
+async function applyMetricsPlugins(data) {
+  const plugins = pluginManager.getPlugins('metricsCollector');
+  for (const plugin of plugins) {
+    try {
+      await plugin.handler(data);
+    } catch (err) {
+      process.stderr.write(`[Worker] Metrics plugin error: ${err.message}\n`);
+    }
+  }
 }
 
 /**
@@ -89,26 +285,59 @@ async function executeRequest(task) {
   const method = (route.method || config.method || 'GET').toUpperCase();
   const headers = { ...(config.headers || {}), ...(route.headers || {}) };
 
+  await applyHeaderPlugins(headers);
+
+  let payload = route.payload ?? null;
+  if (payload == null && datasetLoader) {
+    payload = datasetLoader.getRecord(datasetIndex++);
+  }
+  payload = await applyPayloadPlugins(payload);
+
   let body = null;
-  if (route.payload != null && method !== 'GET' && method !== 'HEAD') {
-    const resolved = resolvePayload(route.payload);
+  if (payload != null && method !== 'GET' && method !== 'HEAD') {
+    const resolved = resolvePayload(payload);
     body = typeof resolved === 'string' ? resolved : JSON.stringify(resolved);
   }
 
+  const context = await applyRequestInterceptors({
+    url,
+    method,
+    headers,
+    body,
+    route,
+  });
+
+  const targetUrl = context.url || url;
+  const targetMethod = (context.method || method).toUpperCase();
+  const targetHeaders = context.headers || headers;
+  const targetBody = context.body ?? body;
+
   const startNs = process.hrtime.bigint();
   let isError = false;
   let status = 0;
 
   try {
-    const res = await request(url, {
-      method,
-      headers,
-      body,
+    let parsed;
+    try {
+      parsed = new URL(targetUrl);
+    } catch {
+      try {
+        parsed = new URL(targetUrl, config.baseUrl || config.url);
+      } catch (err) {
+        throw new Error(
+          `Failed to resolve URL "${targetUrl}" with base "${config.baseUrl || config.url}": ${err.message}`,
+        );
+      }
+    }
+    const engine = getEngine(parsed.origin);
+    const res = await engine.request({
+      method: targetMethod,
+      path: `${parsed.pathname}${parsed.search}`,
+      headers: targetHeaders,
+      body: targetBody,
     });
 
     status = res.statusCode;
-    // Consume body to free the socket (undici requirement)
-    await res.body.text();
 
     if (status >= 400) {
       isError = true;
@@ -119,18 +348,22 @@ async function executeRequest(task) {
 
   const elapsedMs = Number(process.hrtime.bigint() - startNs) / 1e6;
 
-  totalRequests++;
-  totalResponseTime += elapsedMs;
-  reservoirSample(elapsedMs);
-
-  if (status) {
-    statusCodes[status] = (statusCodes[status] || 0) + 1;
-  }
+  const endpointKey = resolveEndpointKey(targetMethod, targetUrl, route);
+  recordRequestMetrics({ endpointKey, elapsedMs, isError, status });
+  await applyMetricsPlugins({
+    responseTime: elapsedMs,
+    statusCode: status,
+    isError,
+    route,
+    url: targetUrl,
+    method: targetMethod,
+  });
+}
 
-  if (isError) {
-    errorCount++;
-  } else {
-    successCount++;
+async function executeScenario(task) {
+  const steps = task.steps || [];
+  for (const step of steps) {
+    await executeRequest({ route: step });
   }
 }
 
@@ -142,8 +375,11 @@ parentPort.on('message', async (msg) => {
     successCount = 0;
     errorCount = 0;
     totalResponseTime = 0;
+    minLatency = Infinity;
+    maxLatency = -Infinity;
     // Keep the reservoir across batches for better sampling
     Object.keys(statusCodes).forEach((k) => { statusCodes[k] = 0; });
+    Object.keys(perEndpoint).forEach((k) => { delete perEndpoint[k]; });
 
     // Build task objects from the incoming message
     const tasks = (msg.tasks || []).map((t, i) => {
@@ -161,7 +397,12 @@ parentPort.on('message', async (msg) => {
     });
 
     // Execute all tasks concurrently
-    await Promise.all(tasks.map((task) => executeRequest(task)));
+    await Promise.all(tasks.map((task) => {
+      if (Array.isArray(task.steps)) {
+        return executeScenario(task);
+      }
+      return executeRequest(task);
+    }));
 
     // Report metrics back to the main thread
     parentPort.postMessage({
@@ -172,7 +413,19 @@ parentPort.on('message', async (msg) => {
         errorCount,
         totalResponseTime,
         responseTimes: [...reservoir],
+        minLatency: minLatency === Infinity ? 0 : minLatency,
+        maxLatency: maxLatency === -Infinity ? 0 : maxLatency,
         statusCodes: { ...statusCodes },
+        perEndpoint: Object.fromEntries(
+          Object.entries(perEndpoint).map(([key, metrics]) => [
+            key,
+            {
+              ...metrics,
+              minLatency: metrics.minLatency === Infinity ? 0 : metrics.minLatency,
+              maxLatency: metrics.maxLatency === -Infinity ? 0 : metrics.maxLatency,
+            },
+          ]),
+        ),
       },
     });
   }

package/src/dashboard/cliDashboard.js

@@ -28,6 +28,7 @@ export class CliDashboard {
       totalRequests: 0,
       p95: 0,
       p99: 0,
+      perEndpoint: {},
     };
     this.rpsHistory = [];
     this.startTime = null;
@@ -84,6 +85,7 @@ export class CliDashboard {
     output += `${BOLD}${CYAN}═══════════════════════════════════════════════${RESET}\n`;
     output += `${DIM}  Elapsed: ${elapsed}s${RESET}\n\n`;
     output += table.toString() + '\n\n';
+    output += this._renderEndpointTable();
     output += this._renderBarChart();
     output += `\n  ${BOLD}Total Requests:${RESET} ${m.totalRequests}\n`;
 
@@ -111,6 +113,38 @@ export class CliDashboard {
     chart += `  ${DIM}     0${RESET} └${'─'.repeat(history.length)}\n`;
     return chart;
   }
+
+  _renderEndpointTable() {
+    const endpoints = this.metrics.perEndpoint || {};
+    const entries = Object.entries(endpoints);
+    if (entries.length === 0) return '';
+
+    const table = new Table({
+      head: [
+        `${CYAN}Endpoint${RESET}`,
+        `${CYAN}RPS${RESET}`,
+        `${CYAN}Avg Lat${RESET}`,
+        `${CYAN}Errors${RESET}`,
+      ],
+      colWidths: [30, 8, 12, 10],
+      style: { head: [], border: [] },
+    });
+
+    const sorted = entries.sort(
+      (a, b) => (b[1].requestsPerSec || 0) - (a[1].requestsPerSec || 0),
+    );
+
+    for (const [endpoint, metrics] of sorted.slice(0, 10)) {
+      table.push([
+        endpoint,
+        metrics.requestsPerSec || 0,
+        `${metrics.avgResponseTime || 0}ms`,
+        `${metrics.errorRate || 0}%`,
+      ]);
+    }
+
+    return `${BOLD}${CYAN}Per-Endpoint Metrics${RESET}\n${table.toString()}\n\n`;
+  }
 }
 
 function formatLatency(val) {

package/src/index.js

@@ -21,6 +21,7 @@ export { DatasetLoader } from './payload/datasetLoader.js';
 
 // Metrics
 export { MetricsCollector } from './metrics/metricsCollector.js';
+export { ApiMetrics } from './metrics/apiMetrics.js';
 export { SystemMetrics } from './metrics/systemMetrics.js';
 
 // Reporting