word-stress 1.0.0

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "word-stress",
+  "version": "1.0.0",
+  "description": "A command-line tool for stress-testing WordPress and WooCommerce sites",
+  "main": "src/main.js",
+  "bin": {
+    "word-stress": "./bin/word-stress"
+  },
+  "scripts": {
+    "start": "node bin/word-stress",
+    "dev": "node bin/word-stress",
+    "format": "prettier --write \"src/**/*.js\" \"bin/word-stress\"",
+    "format:check": "prettier --check \"src/**/*.js\" \"bin/word-stress\"",
+    "lint": "eslint src bin/word-stress",
+    "lint:fix": "eslint src bin/word-stress --fix",
+    "test": "node bin/word-stress --help && echo 'CLI help test passed'"
+  },
+  "keywords": [
+    "wordpress",
+    "woocommerce",
+    "stress-testing",
+    "load-testing",
+    "performance",
+    "cli"
+  ],
+  "author": "headwall",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/headwalluk/word-stress.git"
+  },
+  "homepage": "https://github.com/headwalluk/word-stress#readme",
+  "bugs": {
+    "url": "https://github.com/headwalluk/word-stress/issues"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=21.0.0"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "cli-table3": "^0.6.5",
+    "commander": "^14.0.2",
+    "dotenv": "^17.2.3",
+    "ora": "^9.0.0",
+    "user-agents": "^1.1.669"
+  },
+  "devDependencies": {
+    "eslint": "^9.39.2",
+    "prettier": "^3.7.4"
+  }
+}

package/src/cli/commands.js

@@ -0,0 +1,57 @@
+/**
+ * CLI command definitions using commander.js
+ */
+
+const { Command } = require('commander');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Set up CLI commands
+ * @returns {Command} commander program
+ */
+function setupCli() {
+  // Read package.json for version
+  const packageJsonPath = path.join(__dirname, '../../package.json');
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+
+  const program = new Command();
+
+  program
+    .name('word-stress')
+    .description('Stress-testing CLI tool for WordPress and WooCommerce sites')
+    .version(packageJson.version);
+
+  program
+    .argument('<domain>', 'Domain to test (e.g., example.com)')
+    .option('--clients <n>', 'Number of parallel clients for steady-state mode (default: 5)', '5')
+    .option('--interval <ms>', 'Milliseconds between each client request (default: 1000)', '1000')
+    .option('--duration <s>', 'Test duration in seconds (default: 60)', '60')
+    .option(
+      '--mode <mode>',
+      'Test mode: steady-state or burst (default: steady-state)',
+      'steady-state'
+    )
+    .option(
+      '--burst-clients <n>',
+      'Number of simultaneous requests for burst mode (required for burst)'
+    )
+    .option('--endpoint <path>', 'URL path/endpoint to test (default: /)', '/')
+    .option('--method <METHOD>', 'HTTP method: GET, POST, PUT, DELETE, PATCH (default: GET)', 'GET')
+    .option('--https <on|off>', 'Use HTTPS (default: on)', 'on')
+    .option('--timeout <ms>', 'Request timeout in milliseconds (default: 30000)', '30000')
+    .option('--follow-redirects <on|off>', 'Follow HTTP redirects (default: on)', 'on')
+    .option(
+      '--browser <name>',
+      'Browser type for user agent: firefox, chrome, safari (default: chrome)'
+    )
+    .option('--user-agent <string>', 'Custom user agent string (overrides --browser)')
+    .option('--output <format>', 'Output format: table, json, csv (default: table)', 'table')
+    .option('--verbose', 'Enable verbose logging', false);
+
+  return program;
+}
+
+module.exports = {
+  setupCli,
+};

package/src/config.js

@@ -0,0 +1,159 @@
+/**
+ * Centralized configuration module
+ * Loads and normalizes all configuration from CLI arguments and environment variables
+ */
+
+require('dotenv').config();
+
+/**
+ * Default configuration values
+ */
+const defaults = {
+  // Test parameters - Steady-State mode
+  clients: 5,
+  interval: 1000, // milliseconds
+  duration: 60, // seconds
+
+  // Test parameters - Burst mode
+  burstClients: null,
+
+  // Common parameters
+  domain: null,
+  endpoint: '/',
+  method: 'GET',
+  https: true,
+  timeout: 30000,
+  followRedirects: true,
+  output: 'table', // table, json, csv
+
+  // User agent
+  browser: 'chrome', // firefox, chrome, safari
+  customUserAgent: null,
+
+  // Test mode
+  mode: 'steady-state', // steady-state or burst
+
+  // Logging
+  logLevel: process.env.LOG_LEVEL || 'INFO',
+};
+
+/**
+ * Build configuration from CLI arguments
+ * @param {Object} args - Parsed command line arguments
+ * @returns {Object} Configuration object
+ */
+function buildConfig(args) {
+  const config = { ...defaults };
+
+  // Domain is required positional argument
+  if (args.domain) {
+    config.domain = args.domain;
+  }
+
+  // Steady-state parameters
+  if (args.clients !== undefined) {
+    config.clients = parseInt(args.clients, 10);
+  }
+  if (args.interval !== undefined) {
+    config.interval = parseInt(args.interval, 10);
+  }
+  if (args.duration !== undefined) {
+    config.duration = parseInt(args.duration, 10);
+  }
+
+  // Burst parameters
+  if (args.mode === 'burst') {
+    config.mode = 'burst';
+    if (args.burstClients !== undefined) {
+      config.burstClients = parseInt(args.burstClients, 10);
+    }
+  }
+
+  // Common parameters
+  if (args.endpoint !== undefined) {
+    config.endpoint = args.endpoint;
+  }
+  if (args.method !== undefined) {
+    config.method = args.method.toUpperCase();
+  }
+  if (args.https !== undefined) {
+    config.https = args.https === 'on' || args.https === true;
+  }
+  if (args.timeout !== undefined) {
+    config.timeout = parseInt(args.timeout, 10);
+  }
+  if (args.followRedirects !== undefined) {
+    config.followRedirects = args.followRedirects === 'on' || args.followRedirects === true;
+  }
+  if (args.output !== undefined) {
+    config.output = args.output.toLowerCase();
+  }
+
+  // User agent parameters
+  if (args.userAgent !== undefined) {
+    config.customUserAgent = args.userAgent;
+  }
+  if (args.browser !== undefined) {
+    config.browser = args.browser.toLowerCase();
+  }
+
+  return config;
+}
+
+/**
+ * Validate configuration
+ * @param {Object} config
+ * @throws {Error} if configuration is invalid
+ */
+function validate(config) {
+  if (!config.domain) {
+    throw new Error('Domain is required');
+  }
+
+  if (config.mode === 'burst') {
+    if (!config.burstClients) {
+      throw new Error('--burst-clients is required for burst mode');
+    }
+    if (config.burstClients < 1) {
+      throw new Error('--burst-clients must be greater than 0');
+    }
+  } else {
+    if (config.clients < 1) {
+      throw new Error('--clients must be greater than 0');
+    }
+    if (config.interval < 1) {
+      throw new Error('--interval must be greater than 0');
+    }
+    if (config.duration < 1) {
+      throw new Error('--duration must be greater than 0');
+    }
+  }
+
+  const validMethods = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'];
+  if (!validMethods.includes(config.method)) {
+    throw new Error(`--method must be one of: ${validMethods.join(', ')}`);
+  }
+
+  const validOutputs = ['table', 'json', 'csv'];
+  if (!validOutputs.includes(config.output)) {
+    throw new Error(`--output must be one of: ${validOutputs.join(', ')}`);
+  }
+
+  if (config.timeout < 1) {
+    throw new Error('--timeout must be greater than 0');
+  }
+
+  // Validate browser if not using custom user agent
+  if (!config.customUserAgent) {
+    const validBrowsers = ['firefox', 'chrome', 'safari'];
+    if (!validBrowsers.includes(config.browser)) {
+      throw new Error(`--browser must be one of: ${validBrowsers.join(', ')}`);
+    }
+  }
+}
+
+module.exports = {
+  buildConfig,
+  validate,
+  defaults,
+};

package/src/formatters/CsvFormatter.js

@@ -0,0 +1,72 @@
+/**
+ * CSV Formatter
+ * Outputs results as CSV for spreadsheet import
+ */
+
+/**
+ * Escape CSV field value
+ * @param {string|number} value - Value to escape
+ * @returns {string} CSV-escaped value
+ */
+function escapeCsvField(value) {
+  const stringValue = String(value);
+
+  // If contains comma, newline, or quote, wrap in quotes and escape quotes
+  if (stringValue.includes(',') || stringValue.includes('\n') || stringValue.includes('"')) {
+    return `"${stringValue.replace(/"/g, '""')}"`;
+  }
+
+  return stringValue;
+}
+
+/**
+ * Format results as CSV
+ * @param {Object} results - Test results
+ * @returns {string} CSV formatted output
+ */
+function format(results) {
+  const rows = [];
+
+  // Header row
+  rows.push('Metric,Value');
+
+  // Summary metrics
+  rows.push(`Total Requests,${results.totalRequests}`);
+  rows.push(`Duration (seconds),${results.duration.toFixed(2)}`);
+  rows.push(`Success Rate (%),${results.successRate.toFixed(2)}`);
+  rows.push(`Throughput (req/s),${results.throughput.toFixed(2)}`);
+  rows.push(`Data Transferred (bytes),${results.dataTransferred}`);
+
+  // Response times
+  rows.push('');
+  rows.push('Response Time Metrics');
+  rows.push(`Min (ms),${results.responseTime.min}`);
+  rows.push(`Max (ms),${results.responseTime.max}`);
+  rows.push(`Average (ms),${results.responseTime.avg.toFixed(2)}`);
+  rows.push(`Median P50 (ms),${results.responseTime.median}`);
+  rows.push(`P95 (ms),${results.responseTime.p95.toFixed(2)}`);
+  rows.push(`P99 (ms),${results.responseTime.p99.toFixed(2)}`);
+
+  // Status codes
+  rows.push('');
+  rows.push('Status Code Distribution');
+  rows.push(`2xx Success,${results.statusCodes['2xx']}`);
+  rows.push(`3xx Redirect,${results.statusCodes['3xx']}`);
+  rows.push(`4xx Client Error,${results.statusCodes['4xx']}`);
+  rows.push(`5xx Server Error,${results.statusCodes['5xx']}`);
+
+  // Errors
+  if (results.errorTotal > 0) {
+    rows.push('');
+    rows.push('Error Details');
+    Object.entries(results.errors).forEach(([error, count]) => {
+      rows.push(`${escapeCsvField(error)},${count}`);
+    });
+  }
+
+  return rows.join('\n');
+}
+
+module.exports = {
+  format,
+};

package/src/formatters/JsonFormatter.js

@@ -0,0 +1,17 @@
+/**
+ * JSON Formatter
+ * Outputs results as JSON
+ */
+
+/**
+ * Format results as JSON
+ * @param {Object} results - Test results
+ * @returns {string} JSON formatted output
+ */
+function format(results) {
+  return JSON.stringify(results, null, 2);
+}
+
+module.exports = {
+  format,
+};

package/src/formatters/TableFormatter.js

@@ -0,0 +1,95 @@
+/**
+ * Table Formatter
+ * Outputs results as pretty ASCII tables
+ */
+
+const Table = require('cli-table3');
+const { formatBytes } = require('../utils');
+
+/**
+ * Format results as pretty tables
+ * @param {Object} results - Test results
+ * @returns {string} Formatted output
+ */
+function format(results) {
+  const output = [];
+
+  // Summary Table
+  const summaryTable = new Table({
+    head: ['Metric', 'Value'],
+    style: { head: [], border: ['cyan'] },
+    colWidths: [25, 40],
+  });
+
+  summaryTable.push(
+    ['Total Requests', results.totalRequests.toString()],
+    ['Duration', `${results.duration.toFixed(2)}s`],
+    ['Success Rate', `${results.successRate.toFixed(2)}%`],
+    ['Throughput', `${results.throughput.toFixed(2)} req/s`],
+    ['Data Transferred', formatBytes(results.dataTransferred)]
+  );
+
+  output.push('Summary');
+  output.push(summaryTable.toString());
+  output.push('');
+
+  // Response Times Table
+  const responseTable = new Table({
+    head: ['Metric', 'Value'],
+    style: { head: [], border: ['cyan'] },
+    colWidths: [25, 40],
+  });
+
+  responseTable.push(
+    ['Min', `${results.responseTime.min}ms`],
+    ['Max', `${results.responseTime.max}ms`],
+    ['Average', `${results.responseTime.avg.toFixed(2)}ms`],
+    ['Median (P50)', `${results.responseTime.median}ms`],
+    ['P95', `${results.responseTime.p95.toFixed(2)}ms`],
+    ['P99', `${results.responseTime.p99.toFixed(2)}ms`]
+  );
+
+  output.push('Response Times');
+  output.push(responseTable.toString());
+  output.push('');
+
+  // Status Codes Table
+  const statusTable = new Table({
+    head: ['Status Code', 'Count'],
+    style: { head: [], border: ['cyan'] },
+    colWidths: [25, 40],
+  });
+
+  statusTable.push(
+    ['2xx Success', results.statusCodes['2xx'].toString()],
+    ['3xx Redirect', results.statusCodes['3xx'].toString()],
+    ['4xx Client Error', results.statusCodes['4xx'].toString()],
+    ['5xx Server Error', results.statusCodes['5xx'].toString()]
+  );
+
+  output.push('Status Codes');
+  output.push(statusTable.toString());
+  output.push('');
+
+  // Errors Table (if any)
+  if (results.errorTotal > 0) {
+    const errorTable = new Table({
+      head: ['Error Type', 'Count'],
+      style: { head: [], border: ['cyan'] },
+      colWidths: [40, 20],
+    });
+
+    Object.entries(results.errors).forEach(([error, count]) => {
+      errorTable.push([error, count.toString()]);
+    });
+
+    output.push('Errors');
+    output.push(errorTable.toString());
+  }
+
+  return output.join('\n');
+}
+
+module.exports = {
+  format,
+};

package/src/formatters/factory.js

@@ -0,0 +1,31 @@
+/**
+ * Formatter Factory
+ * Selects and returns the appropriate formatter based on output format
+ */
+
+const TableFormatter = require('./TableFormatter');
+const JsonFormatter = require('./JsonFormatter');
+const CsvFormatter = require('./CsvFormatter');
+
+/**
+ * Get formatter by name
+ * @param {string} format - Format name: 'table', 'json', or 'csv'
+ * @returns {Object} Formatter with format() method
+ * @throws {Error} if format is not recognized
+ */
+function getFormatter(format) {
+  switch (format.toLowerCase()) {
+    case 'table':
+      return TableFormatter;
+    case 'json':
+      return JsonFormatter;
+    case 'csv':
+      return CsvFormatter;
+    default:
+      throw new Error(`Unknown format: ${format}. Valid formats: table, json, csv`);
+  }
+}
+
+module.exports = {
+  getFormatter,
+};

package/src/http/client.js

@@ -0,0 +1,111 @@
+/**
+ * HTTP Client using Node's native Fetch API
+ *
+ * Handles HTTP requests with timeout support, error classification,
+ * and metrics collection (response time, size, status code).
+ */
+
+const logger = require('../logger');
+
+/**
+ * Make an HTTP request and return metrics
+ *
+ * @param {string} url - Full URL to request
+ * @param {Object} options - Request options
+ * @param {string} options.method - HTTP method (GET, POST, etc.) - default: GET
+ * @param {number} options.timeout - Timeout in milliseconds - default: 30000
+ * @param {boolean} options.followRedirects - Follow redirects - default: true
+ * @param {string} options.userAgent - User agent string - default: Node.js default
+ * @returns {Promise<Object>} Result object with metrics
+ *   - statusCode: HTTP status code or null
+ *   - responseTime: Response time in milliseconds
+ *   - size: Response body size in bytes
+ *   - error: Error string or null
+ *   - errorType: 'network' | 'timeout' | 'http' | null
+ */
+async function makeRequest(url, options = {}) {
+  const { method = 'GET', timeout = 30000, followRedirects = true, userAgent = null } = options;
+
+  const startTime = Date.now();
+  let statusCode = null;
+  let size = 0;
+  let error = null;
+  let errorType = null;
+
+  try {
+    // Create abort controller for timeout handling
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+    const fetchOptions = {
+      method,
+      signal: controller.signal,
+      redirect: followRedirects ? 'follow' : 'manual',
+      headers: {},
+    };
+
+    // Add User-Agent header if provided
+    if (userAgent) {
+      fetchOptions.headers['User-Agent'] = userAgent;
+    }
+
+    let response;
+    try {
+      response = await fetch(url, fetchOptions);
+    } finally {
+      clearTimeout(timeoutId);
+    }
+
+    statusCode = response.status;
+
+    // Extract response size from Content-Length header or read body
+    const contentLength = response.headers.get('content-length');
+    if (contentLength) {
+      size = parseInt(contentLength, 10);
+    } else {
+      // If no Content-Length, read the body to get actual size
+      const body = await response.text();
+      size = Buffer.byteLength(body, 'utf8');
+    }
+
+    // Log 4xx and 5xx responses as warnings, not errors
+    if (response.status >= 400) {
+      logger.debug(`HTTP ${response.status} from ${url}`);
+    }
+  } catch (err) {
+    // Classify the error
+    if (err.name === 'AbortError') {
+      error = 'Request timeout';
+      errorType = 'timeout';
+    } else if (
+      err.code === 'ECONNREFUSED' ||
+      err.code === 'ENOTFOUND' ||
+      err.code === 'EHOSTUNREACH'
+    ) {
+      error = `Network error: ${err.code}`;
+      errorType = 'network';
+    } else if (err.message.includes('fetch')) {
+      error = `Network error: ${err.message}`;
+      errorType = 'network';
+    } else {
+      error = err.message;
+      errorType = 'unknown';
+    }
+
+    logger.debug(`Request failed to ${url}: ${error}`);
+  }
+
+  const responseTime = Date.now() - startTime;
+
+  return {
+    statusCode,
+    responseTime,
+    size,
+    error,
+    errorType,
+  };
+}
+
+module.exports = {
+  makeRequest,
+};

package/src/logger.js

@@ -0,0 +1,59 @@
+/**
+ * Custom logger with configurable log levels
+ * Respects LOG_LEVEL environment variable
+ */
+
+const LOG_LEVELS = {
+  DEBUG: 0,
+  INFO: 1,
+  WARN: 2,
+  ERROR: 3,
+};
+
+class Logger {
+  constructor(level = 'INFO') {
+    this.currentLevel = LOG_LEVELS[level.toUpperCase()] || LOG_LEVELS.INFO;
+  }
+
+  /**
+   * Log an info message
+   * @param {string} message
+   */
+  log(message) {
+    if (this.currentLevel <= LOG_LEVELS.INFO) {
+      console.log(message);
+    }
+  }
+
+  /**
+   * Log a debug message
+   * @param {string} message
+   */
+  debug(message) {
+    if (this.currentLevel <= LOG_LEVELS.DEBUG) {
+      console.log(`[DEBUG] ${message}`);
+    }
+  }
+
+  /**
+   * Log a warning message
+   * @param {string} message
+   */
+  warn(message) {
+    if (this.currentLevel <= LOG_LEVELS.WARN) {
+      console.warn(`[WARN] ${message}`);
+    }
+  }
+
+  /**
+   * Log an error message
+   * @param {string} message
+   */
+  error(message) {
+    if (this.currentLevel <= LOG_LEVELS.ERROR) {
+      console.error(`[ERROR] ${message}`);
+    }
+  }
+}
+
+module.exports = new Logger(process.env.LOG_LEVEL || 'INFO');