word-stress 1.0.0

package/src/main.js

@@ -0,0 +1,75 @@
+/**
+ * Main application entry point
+ * Orchestrates the stress testing workflow
+ */
+
+const logger = require('./logger');
+const { buildConfig, validate } = require('./config');
+const { getTestMode } = require('./test-modes/factory');
+const { getFormatter } = require('./formatters/factory');
+const { buildUrl } = require('./utils');
+const { makeRequest } = require('./http/client');
+const MetricsCollector = require('./metrics/MetricsCollector');
+const { resolveUserAgent } = require('./user-agent');
+
+/**
+ * Main application function
+ * @param {Object} args - Parsed CLI arguments
+ */
+async function main(args) {
+  try {
+    // Build and validate configuration
+    const config = buildConfig(args);
+    validate(config);
+
+    // Log test configuration
+    logger.log(`\nStarting stress test...`);
+    const url = buildUrl(config);
+    logger.log(`Target: ${url}`);
+
+    if (config.mode === 'steady-state') {
+      logger.log(`Mode: Steady-State`);
+      logger.log(`Clients: ${config.clients}`);
+      logger.log(`Interval: ${config.interval}ms`);
+      logger.log(`Duration: ${config.duration}s`);
+    } else if (config.mode === 'burst') {
+      logger.log(`Mode: Burst`);
+      logger.log(`Simultaneous Requests: ${config.burstClients}`);
+    }
+
+    logger.log(`Method: ${config.method}`);
+    logger.log(`Output Format: ${config.output}`);
+    logger.log('');
+
+    // Resolve user agent
+    const userAgent = resolveUserAgent(config);
+    if (config.customUserAgent) {
+      logger.log(`User-Agent: ${config.customUserAgent} (custom)`);
+    } else {
+      logger.log(`User-Agent: ${config.browser}`);
+    }
+    logger.log('');
+
+    // Create instances for test execution
+    const testMode = getTestMode(config);
+    const metricsCollector = new MetricsCollector();
+    const formatter = getFormatter(config.output);
+
+    // Run the test with user agent
+    const results = await testMode.run(
+      { makeRequest: (url, options) => makeRequest(url, { ...options, userAgent }) },
+      metricsCollector
+    );
+
+    // Format and output results
+    const output = formatter.format(results);
+    logger.log(output);
+  } catch (error) {
+    logger.error(error.message);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  main,
+};

package/src/metrics/MetricsCollector.js

@@ -0,0 +1,169 @@
+/**
+ * Metrics Collector
+ * Aggregates and calculates statistics from test requests
+ */
+
+const { calculatePercentile, calculateMedian } = require('../utils');
+
+/**
+ * MetricsCollector class
+ * Collects per-request metrics and calculates aggregates
+ */
+class MetricsCollector {
+  constructor() {
+    this.requests = [];
+    this.startTime = Date.now();
+    this.endTime = null;
+  }
+
+  /**
+   * Record a single request result
+   * @param {Object} result - Request result object
+   * @param {number} result.responseTime - Response time in milliseconds
+   * @param {number} result.statusCode - HTTP status code
+   * @param {number} result.size - Response size in bytes
+   * @param {string|null} result.error - Error type (null if successful)
+   */
+  recordRequest(result) {
+    this.requests.push({
+      responseTime: result.responseTime || 0,
+      statusCode: result.statusCode || 0,
+      size: result.size || 0,
+      error: result.error || null,
+    });
+  }
+
+  /**
+   * Mark test as complete and set end time
+   */
+  complete() {
+    this.endTime = Date.now();
+  }
+
+  /**
+   * Get test duration in seconds
+   * @returns {number} Duration in seconds
+   */
+  getDuration() {
+    const end = this.endTime || Date.now();
+    return (end - this.startTime) / 1000;
+  }
+
+  /**
+   * Get aggregated metrics
+   * @returns {Object} Aggregated metrics
+   */
+  getAggregateMetrics() {
+    if (this.requests.length === 0) {
+      return this._getEmptyMetrics();
+    }
+
+    const responseTimes = this.requests
+      .filter(r => !r.error)
+      .map(r => r.responseTime)
+      .sort((a, b) => a - b);
+
+    const duration = this.getDuration();
+
+    // Count status codes
+    const statusCounts = {};
+    const errorCounts = {};
+
+    this.requests.forEach(r => {
+      if (r.error) {
+        errorCounts[r.error] = (errorCounts[r.error] || 0) + 1;
+      } else {
+        const statusCategory = `${Math.floor(r.statusCode / 100)}xx`;
+        statusCounts[statusCategory] = (statusCounts[statusCategory] || 0) + 1;
+      }
+    });
+
+    // Calculate response time percentiles
+    const minResponseTime = responseTimes.length > 0 ? responseTimes[0] : 0;
+    const maxResponseTime = responseTimes.length > 0 ? responseTimes[responseTimes.length - 1] : 0;
+    const avgResponseTime =
+      responseTimes.length > 0
+        ? responseTimes.reduce((a, b) => a + b, 0) / responseTimes.length
+        : 0;
+
+    // Calculate total data transferred
+    const totalDataTransferred = this.requests.reduce((sum, r) => sum + (r.size || 0), 0);
+
+    // Calculate throughput
+    const throughput = duration > 0 ? this.requests.length / duration : 0;
+
+    return {
+      // Test metadata
+      totalRequests: this.requests.length,
+      duration: parseFloat(duration.toFixed(2)),
+
+      // Status code distribution
+      statusCodes: {
+        '2xx': statusCounts['2xx'] || 0,
+        '3xx': statusCounts['3xx'] || 0,
+        '4xx': statusCounts['4xx'] || 0,
+        '5xx': statusCounts['5xx'] || 0,
+      },
+
+      // Error counts
+      errors: errorCounts,
+      errorTotal: Object.values(errorCounts).reduce((a, b) => a + b, 0),
+
+      // Response time statistics
+      responseTime: {
+        min: parseFloat(minResponseTime.toFixed(2)),
+        max: parseFloat(maxResponseTime.toFixed(2)),
+        avg: parseFloat(avgResponseTime.toFixed(2)),
+        median: parseFloat(calculateMedian(responseTimes).toFixed(2)),
+        p95: parseFloat(calculatePercentile(responseTimes, 95).toFixed(2)),
+        p99: parseFloat(calculatePercentile(responseTimes, 99).toFixed(2)),
+      },
+
+      // Throughput metrics
+      throughput: parseFloat(throughput.toFixed(2)),
+      dataTransferred: totalDataTransferred,
+
+      // Success rate
+      successRate: parseFloat(
+        (
+          ((this.requests.length - Object.values(errorCounts).reduce((a, b) => a + b, 0)) /
+            this.requests.length) *
+          100
+        ).toFixed(2)
+      ),
+    };
+  }
+
+  /**
+   * Get empty metrics object (for when no requests were made)
+   * @private
+   * @returns {Object}
+   */
+  _getEmptyMetrics() {
+    return {
+      totalRequests: 0,
+      duration: 0,
+      statusCodes: {
+        '2xx': 0,
+        '3xx': 0,
+        '4xx': 0,
+        '5xx': 0,
+      },
+      errors: {},
+      errorTotal: 0,
+      responseTime: {
+        min: 0,
+        max: 0,
+        avg: 0,
+        median: 0,
+        p95: 0,
+        p99: 0,
+      },
+      throughput: 0,
+      dataTransferred: 0,
+      successRate: 0,
+    };
+  }
+}
+
+module.exports = MetricsCollector;

package/src/test-modes/BurstTestMode.js

@@ -0,0 +1,68 @@
+/**
+ * Burst Test Mode
+ * Sends simultaneous requests to measure peak capacity
+ */
+
+const logger = require('../logger');
+const { buildUrl } = require('../utils');
+
+/**
+ * BurstTestMode class
+ * Launches N simultaneous requests and measures aggregate performance
+ */
+class BurstTestMode {
+  constructor(config) {
+    this.config = config;
+  }
+
+  /**
+   * Run the burst test
+   * Launches burstClients simultaneous requests
+   *
+   * @param {Object} client - HTTP client with makeRequest() function
+   * @param {Object} metricsCollector - MetricsCollector instance
+   * @returns {Promise<Object>} Test results (MetricsCollector summary)
+   */
+  async run(client, metricsCollector) {
+    const { burstClients, method, timeout, followRedirects } = this.config;
+    const url = buildUrl(this.config);
+
+    logger.log(`Starting burst test: ${burstClients} simultaneous requests`);
+
+    const startTime = Date.now();
+
+    // Create array of N simultaneous requests
+    const requests = [];
+    for (let i = 0; i < burstClients; i++) {
+      requests.push(
+        client.makeRequest(url, {
+          method,
+          timeout,
+          followRedirects,
+        })
+      );
+    }
+
+    // Execute all requests in parallel
+    try {
+      const results = await Promise.all(requests);
+
+      // Record all results in metrics collector
+      results.forEach((result, index) => {
+        metricsCollector.recordRequest(result);
+        logger.debug(`Burst request ${index + 1}: ${result.statusCode || 'ERROR'}`);
+      });
+    } catch (err) {
+      logger.error(`Burst test error: ${err.message}`);
+    }
+
+    metricsCollector.complete();
+    const elapsed = Date.now() - startTime;
+
+    logger.log(`Burst test complete after ${(elapsed / 1000).toFixed(2)}s`);
+
+    return metricsCollector.getAggregateMetrics();
+  }
+}
+
+module.exports = BurstTestMode;

package/src/test-modes/SteadyStateTestMode.js

@@ -0,0 +1,102 @@
+/**
+ * Steady-State Test Mode
+ * Runs multiple clients making periodic requests at fixed intervals
+ */
+
+const logger = require('../logger');
+const { sleep, buildUrl } = require('../utils');
+
+/**
+ * SteadyStateTestMode class
+ * Creates multiple concurrent clients, each making requests at a fixed interval
+ */
+class SteadyStateTestMode {
+  constructor(config) {
+    this.config = config;
+  }
+
+  /**
+   * Run the steady-state test
+   * Spawns N clients that each make requests at the specified interval
+   * for the specified duration
+   *
+   * @param {Object} client - HTTP client with makeRequest() function
+   * @param {Object} metricsCollector - MetricsCollector instance
+   * @returns {Promise<Object>} Test results (MetricsCollector summary)
+   */
+  async run(client, metricsCollector) {
+    const { clients: numClients, interval, duration } = this.config;
+
+    const testDurationMs = duration * 1000;
+    const url = buildUrl(this.config);
+
+    logger.log(
+      `Starting steady-state test: ${numClients} clients, ${interval}ms interval, ${duration}s duration`
+    );
+
+    const startTime = Date.now();
+    const clientPromises = [];
+
+    // Spawn N client tasks
+    for (let i = 0; i < numClients; i++) {
+      const clientId = i + 1;
+      clientPromises.push(this._runClient(clientId, client, metricsCollector, url, testDurationMs));
+    }
+
+    // Wait for all clients to finish
+    try {
+      await Promise.all(clientPromises);
+    } catch (err) {
+      logger.error(`Test error: ${err.message}`);
+    }
+
+    metricsCollector.complete();
+    const elapsed = Date.now() - startTime;
+
+    logger.log(`Steady-state test complete after ${(elapsed / 1000).toFixed(2)}s`);
+
+    return metricsCollector.getAggregateMetrics();
+  }
+
+  /**
+   * Run a single client: make requests at the specified interval until duration is reached
+   * @private
+   */
+  async _runClient(clientId, client, metricsCollector, url, testDurationMs) {
+    const { interval, method, timeout, followRedirects } = this.config;
+    const startTime = Date.now();
+    let requestCount = 0;
+
+    while (Date.now() - startTime < testDurationMs) {
+      try {
+        const result = await client.makeRequest(url, {
+          method,
+          timeout,
+          followRedirects,
+        });
+
+        metricsCollector.recordRequest(result);
+        requestCount++;
+
+        logger.debug(
+          `Client ${clientId}: Request ${requestCount} - ${result.statusCode || 'ERROR'}`
+        );
+
+        // Wait for the interval before next request
+        const elapsedSinceStart = Date.now() - startTime;
+        const nextRequestTime = (requestCount + 1) * interval;
+
+        if (nextRequestTime > elapsedSinceStart && nextRequestTime <= testDurationMs) {
+          const waitTime = nextRequestTime - elapsedSinceStart;
+          await sleep(waitTime);
+        }
+      } catch (err) {
+        logger.debug(`Client ${clientId}: Request error - ${err.message}`);
+      }
+    }
+
+    logger.debug(`Client ${clientId} completed ${requestCount} requests`);
+  }
+}
+
+module.exports = SteadyStateTestMode;

package/src/test-modes/factory.js

@@ -0,0 +1,28 @@
+/**
+ * Test Mode Factory
+ * Instantiates the appropriate test mode based on configuration
+ */
+
+const SteadyStateTestMode = require('./SteadyStateTestMode');
+const BurstTestMode = require('./BurstTestMode');
+
+/**
+ * Get test mode instance
+ * @param {Object} config - Configuration object
+ * @returns {Object} Test mode instance with run() method
+ * @throws {Error} if mode is not recognized
+ */
+function getTestMode(config) {
+  switch (config.mode.toLowerCase()) {
+    case 'steady-state':
+      return new SteadyStateTestMode(config);
+    case 'burst':
+      return new BurstTestMode(config);
+    default:
+      throw new Error(`Unknown test mode: ${config.mode}. Valid modes: steady-state, burst`);
+  }
+}
+
+module.exports = {
+  getTestMode,
+};

package/src/user-agent.js

@@ -0,0 +1,51 @@
+/**
+ * User Agent resolver
+ * Translates browser names to realistic user agent strings
+ */
+
+const UserAgent = require('user-agents');
+
+/**
+ * Get a user agent string based on browser preference
+ *
+ * @param {string} browser - Browser name: firefox, chrome, safari, or null for default
+ * @returns {string} User agent string
+ */
+function getUserAgent(browser = 'chrome') {
+  const ua = new UserAgent();
+
+  switch (browser) {
+    case 'firefox':
+      return ua.toString({ ua: 'Firefox' });
+    case 'chrome':
+      return ua.toString({ ua: 'Chrome' });
+    case 'safari':
+      return ua.toString({ ua: 'Safari' });
+    default:
+      return ua.toString();
+  }
+}
+
+/**
+ * Get a custom user agent or default based on browser preference
+ *
+ * @param {Object} config - Configuration object
+ * @param {string} config.customUserAgent - Custom UA string (takes precedence)
+ * @param {string} config.browser - Browser name (firefox, chrome, safari)
+ * @returns {string} User agent string
+ */
+function resolveUserAgent(config) {
+  // Custom UA takes precedence
+  if (config.customUserAgent) {
+    return config.customUserAgent;
+  }
+
+  // Use browser preference, default to chrome
+  const browser = config.browser || 'chrome';
+  return getUserAgent(browser);
+}
+
+module.exports = {
+  getUserAgent,
+  resolveUserAgent,
+};

package/src/utils.js

@@ -0,0 +1,99 @@
+/**
+ * Utility functions for the application
+ */
+
+/**
+ * Calculate percentile from sorted array
+ * @param {number[]} sortedArray - Array of values, sorted in ascending order
+ * @param {number} percentile - Percentile to calculate (0-100)
+ * @returns {number} Percentile value
+ */
+function calculatePercentile(sortedArray, percentile) {
+  if (sortedArray.length === 0) {
+    return 0;
+  }
+  if (percentile === 50) {
+    return calculateMedian(sortedArray);
+  }
+
+  const index = (percentile / 100) * (sortedArray.length - 1);
+  const lower = Math.floor(index);
+  const upper = Math.ceil(index);
+  const weight = index % 1;
+
+  if (lower === upper) {
+    return sortedArray[lower];
+  }
+
+  return sortedArray[lower] * (1 - weight) + sortedArray[upper] * weight;
+}
+
+/**
+ * Calculate median from sorted array
+ * @param {number[]} sortedArray - Array of values, sorted in ascending order
+ * @returns {number} Median value
+ */
+function calculateMedian(sortedArray) {
+  if (sortedArray.length === 0) {
+    return 0;
+  }
+  const mid = Math.floor(sortedArray.length / 2);
+  if (sortedArray.length % 2 === 1) {
+    return sortedArray[mid];
+  }
+  return (sortedArray[mid - 1] + sortedArray[mid]) / 2;
+}
+
+/**
+ * Build full URL from configuration
+ * @param {Object} config - Configuration object
+ * @returns {string} Full URL
+ */
+function buildUrl(config) {
+  const protocol = config.https ? 'https' : 'http';
+  const domain = config.domain.replace(/^(https?:\/\/)/, ''); // Remove protocol if present
+  const endpoint = config.endpoint.startsWith('/') ? config.endpoint : `/${config.endpoint}`;
+  return `${protocol}://${domain}${endpoint}`;
+}
+
+/**
+ * Format bytes to human-readable format
+ * @param {number} bytes - Number of bytes
+ * @returns {string} Formatted string
+ */
+function formatBytes(bytes) {
+  if (bytes === 0) {
+    return '0 B';
+  }
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return (bytes / Math.pow(k, i)).toFixed(2) + ' ' + sizes[i];
+}
+
+/**
+ * Format milliseconds to seconds
+ * @param {number} ms - Milliseconds
+ * @returns {string} Formatted string
+ */
+function formatDuration(ms) {
+  return (ms / 1000).toFixed(2) + 's';
+}
+
+/**
+ * Sleep for specified milliseconds
+ * @param {number} ms - Milliseconds to sleep
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+module.exports = {
+  calculatePercentile,
+  calculateMedian,
+  buildUrl,
+  formatBytes,
+  formatDuration,
+  sleep,
+};