@testsmith/perfornium 0.1.0 → 0.2.0

package/dist/config/parser.d.ts

@@ -2,6 +2,15 @@ import { TestConfiguration } from './types';
 export declare class ConfigParser {
     private templateProcessor;
     parse(configPath: string, environment?: string): Promise<TestConfiguration>;
+    /**
+     * Process includes - load scenarios from external files
+     *
+     * Supports:
+     * - includes: ["scenarios/login.yml", "scenarios/checkout.yml"]
+     * - Included files can contain single scenario or array of scenarios
+     * - Scenarios are merged with inline scenarios
+     */
+    private processIncludes;
     private parseTypeScript;
     private evaluatePlainTypeScript;
     private setupBaseDirectories;

package/dist/config/parser.js

@@ -62,6 +62,8 @@ class ConfigParser {
             const configContent = fs.readFileSync(configPath, 'utf8');
             config = this.parseContent(configContent);
         }
+        // Process includes (scenarios from external files)
+        config = await this.processIncludes(config, path.dirname(configPath));
         logger_1.logger.debug(`Parsed config.global: ${JSON.stringify(config.global, null, 2)}`);
         // Setup faker configuration if specified
         logger_1.logger.debug('About to setup faker...');
@@ -77,6 +79,55 @@ class ConfigParser {
         }
         return config;
     }
+    /**
+     * Process includes - load scenarios from external files
+     *
+     * Supports:
+     * - includes: ["scenarios/login.yml", "scenarios/checkout.yml"]
+     * - Included files can contain single scenario or array of scenarios
+     * - Scenarios are merged with inline scenarios
+     */
+    async processIncludes(config, baseDir) {
+        if (!config.includes || !Array.isArray(config.includes)) {
+            return config;
+        }
+        logger_1.logger.debug(`Processing ${config.includes.length} include(s)`);
+        const includedScenarios = [];
+        for (const includePath of config.includes) {
+            const fullPath = path.isAbsolute(includePath)
+                ? includePath
+                : path.join(baseDir, includePath);
+            if (!fs.existsSync(fullPath)) {
+                throw new Error(`Included file not found: ${fullPath}`);
+            }
+            logger_1.logger.debug(`Loading included file: ${fullPath}`);
+            const content = fs.readFileSync(fullPath, 'utf8');
+            const parsed = this.parseContent(content);
+            // Support both single scenario object and array of scenarios
+            if (Array.isArray(parsed)) {
+                // File contains array of scenarios
+                includedScenarios.push(...parsed);
+            }
+            else if (parsed.scenarios && Array.isArray(parsed.scenarios)) {
+                // File contains scenarios property
+                includedScenarios.push(...parsed.scenarios);
+            }
+            else if (parsed.name && parsed.steps) {
+                // File contains single scenario
+                includedScenarios.push(parsed);
+            }
+            else {
+                logger_1.logger.warn(`Included file ${includePath} has no valid scenarios`);
+            }
+        }
+        // Merge included scenarios with inline scenarios
+        const inlineScenarios = config.scenarios || [];
+        config.scenarios = [...includedScenarios, ...inlineScenarios];
+        // Remove includes from config (no longer needed)
+        delete config.includes;
+        logger_1.logger.debug(`Total scenarios after includes: ${config.scenarios.length}`);
+        return config;
+    }
     async parseTypeScript(configPath) {
         try {
             // Resolve to absolute path

package/dist/config/types/step-types.d.ts

@@ -1,8 +1,8 @@
 import { StepHooks } from "./hooks";
-export type Step = RESTStep | SOAPStep | WebStep | CustomStep | WaitStep | ScriptStep;
+export type Step = RESTStep | SOAPStep | WebStep | CustomStep | WaitStep | ScriptStep | RendezvousStep;
 export interface BaseStep {
     name?: string;
-    type?: 'rest' | 'soap' | 'web' | 'custom' | 'wait' | 'script';
+    type?: 'rest' | 'soap' | 'web' | 'custom' | 'wait' | 'script' | 'rendezvous';
     condition?: string;
     continueOnError?: boolean;
     hooks?: StepHooks;
@@ -79,6 +79,21 @@ export interface ScriptStep extends BaseStep {
     returns?: string;
     timeout?: number;
 }
+/**
+ * Rendezvous step for synchronized VU coordination
+ *
+ * Creates a synchronization point where VUs wait for each other before proceeding.
+ * Use this to create coordinated load spikes at specific points in the test.
+ *
+ * Example: 10 VUs simultaneously checking account balances
+ */
+export interface RendezvousStep extends BaseStep {
+    type: 'rendezvous';
+    rendezvous: string;
+    count: number;
+    timeout?: number | string;
+    policy?: 'all' | 'count';
+}
 export interface WebAction {
     name?: string;
     expected_text?: string;

package/dist/core/index.d.ts

@@ -3,3 +3,5 @@ export { VirtualUser } from './virtual-user';
 export { StepExecutor } from './step-executor';
 export { CSVDataProvider } from './csv-data-provider';
 export type { CSVDataRow } from './csv-data-provider';
+export { RendezvousManager } from './rendezvous';
+export type { RendezvousConfig, RendezvousResult, RendezvousStats } from './rendezvous';

package/dist/core/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CSVDataProvider = exports.StepExecutor = exports.VirtualUser = exports.TestRunner = void 0;
+exports.RendezvousManager = exports.CSVDataProvider = exports.StepExecutor = exports.VirtualUser = exports.TestRunner = void 0;
 var test_runner_1 = require("./test-runner");
 Object.defineProperty(exports, "TestRunner", { enumerable: true, get: function () { return test_runner_1.TestRunner; } });
 var virtual_user_1 = require("./virtual-user");
@@ -9,3 +9,5 @@ var step_executor_1 = require("./step-executor");
 Object.defineProperty(exports, "StepExecutor", { enumerable: true, get: function () { return step_executor_1.StepExecutor; } });
 var csv_data_provider_1 = require("./csv-data-provider");
 Object.defineProperty(exports, "CSVDataProvider", { enumerable: true, get: function () { return csv_data_provider_1.CSVDataProvider; } });
+var rendezvous_1 = require("./rendezvous");
+Object.defineProperty(exports, "RendezvousManager", { enumerable: true, get: function () { return rendezvous_1.RendezvousManager; } });

package/dist/core/rendezvous.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Rendezvous Manager for synchronized VU coordination
+ *
+ * Rendezvous points allow Virtual Users to wait for each other at specific
+ * points in the test execution, creating coordinated load spikes.
+ *
+ * Like a fairground ride queue:
+ * - VUs enter the queue and wait
+ * - When enough VUs are waiting (release count), they all proceed together
+ * - If timeout expires, waiting VUs are released regardless of count
+ */
+import { EventEmitter } from 'events';
+export interface RendezvousConfig {
+    name: string;
+    count: number;
+    timeout?: number;
+    releasePolicy?: 'all' | 'count';
+}
+export declare class RendezvousManager extends EventEmitter {
+    private static instance;
+    private rendezvousPoints;
+    private isActive;
+    private constructor();
+    static getInstance(): RendezvousManager;
+    /**
+     * Reset the manager for a new test run
+     */
+    reset(): void;
+    /**
+     * Stop the manager and release all waiting VUs
+     */
+    stop(): void;
+    /**
+     * Wait at a rendezvous point
+     * Returns when either:
+     * - The required number of VUs are waiting (synchronized release)
+     * - The timeout expires
+     * - The test is stopped
+     */
+    wait(config: RendezvousConfig, vuId: number): Promise<RendezvousResult>;
+    /**
+     * Release VUs from a rendezvous point
+     */
+    private releaseVUs;
+    /**
+     * Force release all waiting VUs (used during shutdown)
+     */
+    private releaseWaitingVUs;
+    /**
+     * Get statistics for a rendezvous point
+     */
+    getStats(name: string): RendezvousStats | null;
+    /**
+     * Get all rendezvous statistics
+     */
+    getAllStats(): RendezvousStats[];
+}
+export interface RendezvousResult {
+    released: boolean;
+    reason: 'count_reached' | 'timeout' | 'manager_inactive' | 'error';
+    waitTime: number;
+    vuCount: number;
+}
+export interface RendezvousStats {
+    name: string;
+    requiredCount: number;
+    currentlyWaiting: number;
+    totalReleased: number;
+    timeout: number;
+}

package/dist/core/rendezvous.js

@@ -0,0 +1,216 @@
+"use strict";
+/**
+ * Rendezvous Manager for synchronized VU coordination
+ *
+ * Rendezvous points allow Virtual Users to wait for each other at specific
+ * points in the test execution, creating coordinated load spikes.
+ *
+ * Like a fairground ride queue:
+ * - VUs enter the queue and wait
+ * - When enough VUs are waiting (release count), they all proceed together
+ * - If timeout expires, waiting VUs are released regardless of count
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RendezvousManager = void 0;
+const logger_1 = require("../utils/logger");
+const events_1 = require("events");
+class RendezvousManager extends events_1.EventEmitter {
+    constructor() {
+        super();
+        this.rendezvousPoints = new Map();
+        this.isActive = true;
+    }
+    static getInstance() {
+        if (!RendezvousManager.instance) {
+            RendezvousManager.instance = new RendezvousManager();
+        }
+        return RendezvousManager.instance;
+    }
+    /**
+     * Reset the manager for a new test run
+     */
+    reset() {
+        // Clear all timeout handles
+        for (const point of this.rendezvousPoints.values()) {
+            if (point.timeoutHandle) {
+                clearTimeout(point.timeoutHandle);
+            }
+            // Release any waiting VUs
+            for (const vu of point.waiting) {
+                vu.reject(new Error('Rendezvous manager reset'));
+            }
+        }
+        this.rendezvousPoints.clear();
+        this.isActive = true;
+        logger_1.logger.debug('RendezvousManager reset');
+    }
+    /**
+     * Stop the manager and release all waiting VUs
+     */
+    stop() {
+        this.isActive = false;
+        for (const point of this.rendezvousPoints.values()) {
+            if (point.timeoutHandle) {
+                clearTimeout(point.timeoutHandle);
+            }
+            // Release all waiting VUs
+            this.releaseWaitingVUs(point, 'Test stopped');
+        }
+        logger_1.logger.debug('RendezvousManager stopped');
+    }
+    /**
+     * Wait at a rendezvous point
+     * Returns when either:
+     * - The required number of VUs are waiting (synchronized release)
+     * - The timeout expires
+     * - The test is stopped
+     */
+    async wait(config, vuId) {
+        if (!this.isActive) {
+            return {
+                released: true,
+                reason: 'manager_inactive',
+                waitTime: 0,
+                vuCount: 0
+            };
+        }
+        const startTime = Date.now();
+        const pointName = config.name;
+        // Get or create rendezvous point
+        let point = this.rendezvousPoints.get(pointName);
+        if (!point) {
+            point = {
+                config: {
+                    ...config,
+                    timeout: config.timeout ?? 30000,
+                    releasePolicy: config.releasePolicy ?? 'all'
+                },
+                waiting: [],
+                releasedCount: 0
+            };
+            this.rendezvousPoints.set(pointName, point);
+            logger_1.logger.debug(`Rendezvous point '${pointName}' created (count: ${config.count}, timeout: ${point.config.timeout}ms)`);
+        }
+        logger_1.logger.debug(`VU${vuId} arriving at rendezvous '${pointName}' (${point.waiting.length + 1}/${config.count})`);
+        return new Promise((resolve, reject) => {
+            const waitingVU = {
+                vuId,
+                resolve: () => {
+                    const waitTime = Date.now() - startTime;
+                    resolve({
+                        released: true,
+                        reason: 'count_reached',
+                        waitTime,
+                        vuCount: point.waiting.length + 1
+                    });
+                },
+                reject,
+                arrivalTime: startTime
+            };
+            point.waiting.push(waitingVU);
+            // Emit event for monitoring
+            this.emit('vu_arrived', {
+                rendezvousName: pointName,
+                vuId,
+                waitingCount: point.waiting.length,
+                requiredCount: config.count
+            });
+            // Check if we've reached the required count
+            if (point.waiting.length >= config.count) {
+                logger_1.logger.debug(`Rendezvous '${pointName}' reached count (${point.waiting.length}/${config.count}) - releasing VUs`);
+                this.releaseVUs(point);
+                return;
+            }
+            // Set up timeout if not already set and timeout > 0
+            if (!point.timeoutHandle && point.config.timeout && point.config.timeout > 0) {
+                point.timeoutHandle = setTimeout(() => {
+                    if (point.waiting.length > 0) {
+                        logger_1.logger.debug(`Rendezvous '${pointName}' timeout - releasing ${point.waiting.length} VUs`);
+                        this.releaseVUs(point, 'timeout');
+                    }
+                }, point.config.timeout);
+            }
+        });
+    }
+    /**
+     * Release VUs from a rendezvous point
+     */
+    releaseVUs(point, reason = 'count_reached') {
+        // Clear timeout
+        if (point.timeoutHandle) {
+            clearTimeout(point.timeoutHandle);
+            point.timeoutHandle = undefined;
+        }
+        const toRelease = point.config.releasePolicy === 'count'
+            ? point.waiting.splice(0, point.config.count)
+            : point.waiting.splice(0);
+        const releaseTime = Date.now();
+        for (const vu of toRelease) {
+            const waitTime = releaseTime - vu.arrivalTime;
+            point.releasedCount++;
+            // Resolve the promise
+            vu.resolve();
+            logger_1.logger.debug(`VU${vu.vuId} released from rendezvous '${point.config.name}' (waited ${waitTime}ms, reason: ${reason})`);
+        }
+        // Emit release event
+        this.emit('vus_released', {
+            rendezvousName: point.config.name,
+            releasedCount: toRelease.length,
+            reason
+        });
+        // Reset timeout for next batch if there are remaining VUs
+        if (point.waiting.length > 0 && point.config.timeout && point.config.timeout > 0) {
+            point.timeoutHandle = setTimeout(() => {
+                if (point.waiting.length > 0) {
+                    this.releaseVUs(point, 'timeout');
+                }
+            }, point.config.timeout);
+        }
+    }
+    /**
+     * Force release all waiting VUs (used during shutdown)
+     */
+    releaseWaitingVUs(point, reason) {
+        const toRelease = point.waiting.splice(0);
+        for (const vu of toRelease) {
+            vu.resolve();
+        }
+        this.emit('vus_released', {
+            rendezvousName: point.config.name,
+            releasedCount: toRelease.length,
+            reason
+        });
+    }
+    /**
+     * Get statistics for a rendezvous point
+     */
+    getStats(name) {
+        const point = this.rendezvousPoints.get(name);
+        if (!point)
+            return null;
+        return {
+            name: point.config.name,
+            requiredCount: point.config.count,
+            currentlyWaiting: point.waiting.length,
+            totalReleased: point.releasedCount,
+            timeout: point.config.timeout ?? 0
+        };
+    }
+    /**
+     * Get all rendezvous statistics
+     */
+    getAllStats() {
+        const stats = [];
+        for (const point of this.rendezvousPoints.values()) {
+            stats.push({
+                name: point.config.name,
+                requiredCount: point.config.count,
+                currentlyWaiting: point.waiting.length,
+                totalReleased: point.releasedCount,
+                timeout: point.config.timeout ?? 0
+            });
+        }
+        return stats;
+    }
+}
+exports.RendezvousManager = RendezvousManager;

package/dist/core/step-executor.d.ts

@@ -29,6 +29,7 @@ export declare class StepExecutor {
     private executeWebStep;
     private executeCustomStep;
     private executeWaitStep;
+    private executeRendezvousStep;
     private executeScriptStep;
     private executeScript;
     private evaluateCondition;

package/dist/core/step-executor.js

@@ -37,6 +37,7 @@ exports.StepExecutor = void 0;
 const hooks_manager_1 = require("./hooks-manager");
 const script_executor_1 = require("./script-executor");
 const threshold_evaluator_1 = require("./threshold-evaluator");
+const rendezvous_1 = require("./rendezvous");
 const time_1 = require("../utils/time");
 const template_1 = require("../utils/template");
 const logger_1 = require("../utils/logger");
@@ -205,6 +206,9 @@ class StepExecutor {
             case 'script':
                 result = await this.executeScriptStep(processedStep, context);
                 break;
+            case 'rendezvous':
+                result = await this.executeRendezvousStep(processedStep, context);
+                break;
             default:
                 throw new Error(`Unsupported step type: ${step.type}`);
         }
@@ -443,6 +447,54 @@ class StepExecutor {
             custom_metrics: { wait_duration: duration }
         };
     }
+    async executeRendezvousStep(step, context) {
+        const rendezvousManager = rendezvous_1.RendezvousManager.getInstance();
+        // Parse timeout - can be number (ms) or string ("30s", "1m")
+        let timeoutMs = 30000; // Default 30 seconds
+        if (step.timeout !== undefined) {
+            if (typeof step.timeout === 'number') {
+                timeoutMs = step.timeout;
+            }
+            else if (typeof step.timeout === 'string') {
+                timeoutMs = (0, time_1.parseTime)(step.timeout);
+            }
+        }
+        try {
+            const result = await rendezvousManager.wait({
+                name: step.rendezvous,
+                count: step.count,
+                timeout: timeoutMs,
+                releasePolicy: step.policy || 'all'
+            }, context.vu_id);
+            return {
+                success: true,
+                data: {
+                    rendezvous: step.rendezvous,
+                    released: result.released,
+                    reason: result.reason,
+                    vuCount: result.vuCount
+                },
+                response_time: result.waitTime,
+                custom_metrics: {
+                    rendezvous_name: step.rendezvous,
+                    rendezvous_wait_time: result.waitTime,
+                    rendezvous_reason: result.reason,
+                    rendezvous_vu_count: result.vuCount
+                },
+                shouldRecord: true // Always record rendezvous timing
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error.message,
+                custom_metrics: {
+                    rendezvous_name: step.rendezvous,
+                    rendezvous_error: true
+                }
+            };
+        }
+    }
     async executeScriptStep(step, context) {
         const { file, function: funcName, params, returns, timeout = 30000 } = step;
         const path = require('path');

package/dist/core/test-runner.js

@@ -50,6 +50,7 @@ const webhook_1 = require("../outputs/webhook");
 const logger_1 = require("../utils/logger");
 const time_1 = require("../utils/time");
 const csv_data_provider_1 = require("./csv-data-provider");
+const rendezvous_1 = require("./rendezvous");
 const file_manager_1 = require("../utils/file-manager");
 class TestRunner {
     constructor(config) {
@@ -83,6 +84,8 @@ class TestRunner {
         logger_1.logger.info(`🚀 Starting test: ${this.config.name}`);
         this.isRunning = true;
         this.startTime = Date.now();
+        // Reset rendezvous manager for this test run
+        rendezvous_1.RendezvousManager.getInstance().reset();
         try {
             await this.initialize();
             // NO CSV termination callback setup needed anymore
@@ -116,6 +119,8 @@ class TestRunner {
     async stop() {
         logger_1.logger.info('⏹️  Stopping test...');
         this.isRunning = false;
+        // Stop rendezvous manager - releases any waiting VUs
+        rendezvous_1.RendezvousManager.getInstance().stop();
         // Stop all active VUs
         this.activeVUs.forEach(vu => vu.stop());
         // Wait for VUs to finish current operations

package/dist/core/virtual-user.d.ts

@@ -35,6 +35,15 @@ export declare class VirtualUser {
     executeScenario(scenario: Scenario): Promise<void>;
     private loadCSVDataIfNeeded;
     private loadCSVDataForScenario;
+    /**
+     * Select scenarios based on weights using proportional distribution.
+     *
+     * Weights determine the probability of a scenario being selected:
+     * - scenario1 (weight: 50) + scenario2 (weight: 25) + scenario3 (weight: 25) = 100
+     * - 50% of VUs will run scenario1, 25% scenario2, 25% scenario3
+     *
+     * If weights don't sum to 100, they are normalized proportionally.
+     */
     private selectScenarios;
     private executeSetup;
     private executeTeardown;

package/dist/core/virtual-user.js

@@ -366,20 +366,36 @@ class VirtualUser {
                 return await provider.getNextRow(this.id);
         }
     }
+    /**
+     * Select scenarios based on weights using proportional distribution.
+     *
+     * Weights determine the probability of a scenario being selected:
+     * - scenario1 (weight: 50) + scenario2 (weight: 25) + scenario3 (weight: 25) = 100
+     * - 50% of VUs will run scenario1, 25% scenario2, 25% scenario3
+     *
+     * If weights don't sum to 100, they are normalized proportionally.
+     */
     selectScenarios(scenarios) {
-        const selected = [];
+        if (scenarios.length === 0) {
+            return [];
+        }
+        if (scenarios.length === 1) {
+            return scenarios;
+        }
+        // Calculate total weight
+        const totalWeight = scenarios.reduce((sum, s) => sum + (s.weight ?? 100), 0);
+        // Generate random value between 0 and totalWeight
+        const random = Math.random() * totalWeight;
+        // Select scenario based on cumulative weight
+        let cumulative = 0;
         for (const scenario of scenarios) {
-            const weight = scenario.weight || 100;
-            const random = Math.random() * 100;
-            if (random < weight) {
-                selected.push(scenario);
+            cumulative += (scenario.weight ?? 100);
+            if (random < cumulative) {
+                return [scenario];
             }
         }
-        // Ensure at least one scenario is selected
-        if (selected.length === 0 && scenarios.length > 0) {
-            selected.push(scenarios[0]);
-        }
-        return selected;
+        // Fallback to last scenario (should not reach here)
+        return [scenarios[scenarios.length - 1]];
     }
     async executeSetup(setupScript) {
         try {

package/dist/dsl/test-builder.d.ts

@@ -27,6 +27,24 @@ export declare class ScenarioBuilder {
     expectText(selector: string, text: string, name?: string): this;
     expectNotVisible(selector: string, name?: string): this;
     wait(duration: string | number): this;
+    /**
+     * Add a rendezvous point to synchronize Virtual Users
+     *
+     * @param name - Unique name for this rendezvous point
+     * @param count - Number of VUs to wait for before releasing
+     * @param options - Optional configuration (timeout, policy)
+     *
+     * @example
+     * scenario('Flash Sale')
+     *   .post('/cart/add', { productId: 'LIMITED-001' })
+     *   .rendezvous('checkout_sync', 10, { timeout: '30s' })
+     *   .post('/checkout', { paymentMethod: 'card' })
+     *   .done()
+     */
+    rendezvous(name: string, count: number, options?: {
+        timeout?: string | number;
+        policy?: 'all' | 'count';
+    }): this;
     get(path: string, options?: any): this;
     post(path: string, body?: any, options?: any): this;
     put(path: string, body?: any, options?: any): this;

package/dist/dsl/test-builder.js

@@ -163,6 +163,30 @@ class ScenarioBuilder {
             duration: durationStr
         });
     }
+    /**
+     * Add a rendezvous point to synchronize Virtual Users
+     *
+     * @param name - Unique name for this rendezvous point
+     * @param count - Number of VUs to wait for before releasing
+     * @param options - Optional configuration (timeout, policy)
+     *
+     * @example
+     * scenario('Flash Sale')
+     *   .post('/cart/add', { productId: 'LIMITED-001' })
+     *   .rendezvous('checkout_sync', 10, { timeout: '30s' })
+     *   .post('/checkout', { paymentMethod: 'card' })
+     *   .done()
+     */
+    rendezvous(name, count, options) {
+        return this.addStep({
+            name: `Rendezvous: ${name}`,
+            type: 'rendezvous',
+            rendezvous: name,
+            count,
+            ...(options?.timeout && { timeout: options.timeout }),
+            ...(options?.policy && { policy: options.policy })
+        });
+    }
     // REST API step methods
     get(path, options) {
         return this.request('GET', path, options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testsmith/perfornium",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Flexible performance testing framework for REST, SOAP, and web applications",
   "author": "TestSmith",
   "license": "MIT",