@frontmcp/testing 0.5.0

package/src/server/test-server.js

@@ -0,0 +1,286 @@
+"use strict";
+/**
+ * @file test-server.ts
+ * @description Test server management for E2E testing
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestServer = void 0;
+exports.findAvailablePort = findAvailablePort;
+const child_process_1 = require("child_process");
+// ═══════════════════════════════════════════════════════════════════
+// TEST SERVER CLASS
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * Manages test server lifecycle for E2E testing
+ *
+ * @example
+ * ```typescript
+ * // Start a server with custom command
+ * const server = await TestServer.start({
+ *   command: 'node dist/main.js',
+ *   port: 3003,
+ *   cwd: './apps/my-server',
+ * });
+ *
+ * // Or start an Nx project
+ * const server = await TestServer.startNx('demo-public', { port: 3003 });
+ *
+ * // Use the server
+ * console.log(server.info.baseUrl); // http://localhost:3003
+ *
+ * // Stop when done
+ * await server.stop();
+ * ```
+ */
+class TestServer {
+    process = null;
+    options;
+    _info;
+    logs = [];
+    constructor(options, port) {
+        this.options = {
+            port,
+            command: options.command ?? '',
+            cwd: options.cwd ?? process.cwd(),
+            env: options.env ?? {},
+            startupTimeout: options.startupTimeout ?? 30000,
+            healthCheckPath: options.healthCheckPath ?? '/health',
+            debug: options.debug ?? false,
+        };
+        this._info = {
+            baseUrl: `http://localhost:${port}`,
+            port,
+        };
+    }
+    /**
+     * Start a test server with custom command
+     */
+    static async start(options) {
+        const port = options.port ?? (await findAvailablePort());
+        const server = new TestServer(options, port);
+        try {
+            await server.startProcess();
+        }
+        catch (error) {
+            await server.stop(); // Clean up spawned process to prevent leaks
+            throw error;
+        }
+        return server;
+    }
+    /**
+     * Start an Nx project as test server
+     */
+    static async startNx(project, options = {}) {
+        // Validate project name contains only safe characters to prevent shell injection
+        if (!/^[\w-]+$/.test(project)) {
+            throw new Error(`Invalid project name: ${project}. Must contain only alphanumeric, underscore, and hyphen characters.`);
+        }
+        const port = options.port ?? (await findAvailablePort());
+        const serverOptions = {
+            ...options,
+            port,
+            command: `npx nx serve ${project} --port ${port}`,
+            cwd: options.cwd ?? process.cwd(),
+        };
+        const server = new TestServer(serverOptions, port);
+        try {
+            await server.startProcess();
+        }
+        catch (error) {
+            await server.stop(); // Clean up spawned process to prevent leaks
+            throw error;
+        }
+        return server;
+    }
+    /**
+     * Create a test server connected to an already running server
+     */
+    static connect(baseUrl) {
+        const url = new URL(baseUrl);
+        const port = parseInt(url.port, 10) || (url.protocol === 'https:' ? 443 : 80);
+        const server = new TestServer({
+            command: '',
+            port,
+        }, port);
+        server._info = {
+            baseUrl: baseUrl.replace(/\/$/, ''),
+            port,
+        };
+        return server;
+    }
+    /**
+     * Get server information
+     */
+    get info() {
+        return { ...this._info };
+    }
+    /**
+     * Stop the test server
+     */
+    async stop() {
+        if (this.process) {
+            this.log('Stopping server...');
+            // Try graceful shutdown first
+            this.process.kill('SIGTERM');
+            // Wait for process to exit
+            const exitPromise = new Promise((resolve) => {
+                if (this.process) {
+                    this.process.once('exit', () => resolve());
+                }
+                else {
+                    resolve();
+                }
+            });
+            // Force kill after timeout (but still wait for actual exit)
+            const killTimeout = setTimeout(() => {
+                if (this.process) {
+                    this.log('Force killing server after timeout...');
+                    this.process.kill('SIGKILL');
+                }
+            }, 5000);
+            await exitPromise;
+            clearTimeout(killTimeout);
+            this.process = null;
+            this.log('Server stopped');
+        }
+    }
+    /**
+     * Wait for server to be ready
+     */
+    async waitForReady(timeout) {
+        const timeoutMs = timeout ?? this.options.startupTimeout;
+        const deadline = Date.now() + timeoutMs;
+        const checkInterval = 100;
+        while (Date.now() < deadline) {
+            try {
+                const response = await fetch(`${this._info.baseUrl}${this.options.healthCheckPath}`, {
+                    method: 'GET',
+                    signal: AbortSignal.timeout(1000),
+                });
+                if (response.ok || response.status === 404) {
+                    // 404 is okay - it means the server is running but might not have a health endpoint
+                    this.log('Server is ready');
+                    return;
+                }
+            }
+            catch {
+                // Server not ready yet
+            }
+            await sleep(checkInterval);
+        }
+        throw new Error(`Server did not become ready within ${timeoutMs}ms`);
+    }
+    /**
+     * Restart the server
+     */
+    async restart() {
+        await this.stop();
+        await this.startProcess();
+    }
+    /**
+     * Get captured server logs
+     */
+    getLogs() {
+        return [...this.logs];
+    }
+    /**
+     * Clear captured logs
+     */
+    clearLogs() {
+        this.logs = [];
+    }
+    // ═══════════════════════════════════════════════════════════════════
+    // PRIVATE METHODS
+    // ═══════════════════════════════════════════════════════════════════
+    async startProcess() {
+        if (!this.options.command) {
+            // No command means we're connecting to an existing server
+            await this.waitForReady();
+            return;
+        }
+        this.log(`Starting server: ${this.options.command}`);
+        const env = {
+            ...process.env,
+            ...this.options.env,
+            PORT: String(this.options.port),
+        };
+        // Use shell: true to handle complex commands with quoted arguments
+        // This avoids fragile command parsing with split(' ')
+        this.process = (0, child_process_1.spawn)(this.options.command, [], {
+            cwd: this.options.cwd,
+            env,
+            shell: true,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        // pid can be undefined if spawn fails
+        if (this.process.pid !== undefined) {
+            this._info.pid = this.process.pid;
+        }
+        // Capture stdout
+        this.process.stdout?.on('data', (data) => {
+            const text = data.toString();
+            this.logs.push(text);
+            if (this.options.debug) {
+                console.log('[SERVER]', text);
+            }
+        });
+        // Capture stderr
+        this.process.stderr?.on('data', (data) => {
+            const text = data.toString();
+            this.logs.push(`[ERROR] ${text}`);
+            if (this.options.debug) {
+                console.error('[SERVER ERROR]', text);
+            }
+        });
+        // Handle spawn errors to prevent unhandled error events
+        this.process.on('error', (err) => {
+            this.logs.push(`[SPAWN ERROR] ${err.message}`);
+            if (this.options.debug) {
+                console.error('[SERVER SPAWN ERROR]', err);
+            }
+        });
+        // Handle process exit - use once() to avoid memory leak from listener not being cleaned up
+        this.process.once('exit', (code) => {
+            this.log(`Server process exited with code ${code}`);
+        });
+        // Wait for server to be ready
+        await this.waitForReady();
+    }
+    log(message) {
+        if (this.options.debug) {
+            console.log(`[TestServer] ${message}`);
+        }
+    }
+}
+exports.TestServer = TestServer;
+// ═══════════════════════════════════════════════════════════════════
+// UTILITIES
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * Find an available port
+ */
+async function findAvailablePort() {
+    // Use a simple approach: try to create a server on port 0 to get an available port
+    const { createServer } = await import('net');
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.listen(0, () => {
+            const address = server.address();
+            if (address && typeof address !== 'string') {
+                const port = address.port;
+                server.close(() => resolve(port));
+            }
+            else {
+                reject(new Error('Could not get port'));
+            }
+        });
+        server.on('error', reject);
+    });
+}
+/**
+ * Sleep for specified milliseconds
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=test-server.js.map

package/src/server/test-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-server.js","sourceRoot":"","sources":["../../../src/server/test-server.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAsUH,8CAmBC;AAvVD,iDAAoD;AAgCpD,sEAAsE;AACtE,oBAAoB;AACpB,sEAAsE;AAEtE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAa,UAAU;IACb,OAAO,GAAwB,IAAI,CAAC;IAC3B,OAAO,CAA8B;IAC9C,KAAK,CAAiB;IACtB,IAAI,GAAa,EAAE,CAAC;IAE5B,YAAoB,OAA0B,EAAE,IAAY;QAC1D,IAAI,CAAC,OAAO,GAAG;YACb,IAAI;YACJ,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,EAAE;YAC9B,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE;YACjC,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,EAAE;YACtB,cAAc,EAAE,OAAO,CAAC,cAAc,IAAI,KAAK;YAC/C,eAAe,EAAE,OAAO,CAAC,eAAe,IAAI,SAAS;YACrD,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,KAAK;SAC9B,CAAC;QAEF,IAAI,CAAC,KAAK,GAAG;YACX,OAAO,EAAE,oBAAoB,IAAI,EAAE;YACnC,IAAI;SACL,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,OAA0B;QAC3C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,CAAC,MAAM,iBAAiB,EAAE,CAAC,CAAC;QACzD,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAC7C,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,YAAY,EAAE,CAAC;QAC9B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,4CAA4C;YACjE,MAAM,KAAK,CAAC;QACd,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,OAAe,EAAE,UAAsC,EAAE;QAC5E,iFAAiF;QACjF,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CACb,yBAAyB,OAAO,sEAAsE,CACvG,CAAC;QACJ,CAAC;QAED,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,CAAC,MAAM,iBAAiB,EAAE,CAAC,CAAC;QAEzD,MAAM,aAAa,GAAsB;YACvC,GAAG,OAAO;YACV,IAAI;YACJ,OAAO,EAAE,gBAAgB,OAAO,WAAW,IAAI,EAAE;YACjD,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE;SAClC,CAAC;QAEF,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;QACnD,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,YAAY,EAAE,CAAC;QAC9B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,4CAA4C;YACjE,MAAM,KAAK,CAAC;QACd,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,OAAe;QAC5B,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC;QAC7B,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAE9E,MAAM,MAAM,GAAG,IAAI,UAAU,CAC3B;YACE,OAAO,EAAE,EAAE;YACX,IAAI;SACL,EACD,IAAI,CACL,CAAC;QAEF,MAAM,CAAC,KAAK,GAAG;YACb,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;YACnC,IAAI;SACL,CAAC;QAEF,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,IAAI;QACR,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,IAAI,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;YAE/B,8BAA8B;YAC9B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAE7B,2BAA2B;YAC3B,MAAM,WAAW,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;gBAChD,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;oBACjB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;gBAC7C,CAAC;qBAAM,CAAC;oBACN,OAAO,EAAE,CAAC;gBACZ,CAAC;YACH,CAAC,CAAC,CAAC;YAEH,4DAA4D;YAC5D,MAAM,WAAW,GAAG,UAAU,CAAC,GAAG,EAAE;gBAClC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;oBACjB,IAAI,CAAC,GAAG,CAAC,uCAAuC,CAAC,CAAC;oBAClD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;gBAC/B,CAAC;YACH,CAAC,EAAE,IAAI,CAAC,CAAC;YAET,MAAM,WAAW,CAAC;YAClB,YAAY,CAAC,WAAW,CAAC,CAAC;YAC1B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;YACpB,IAAI,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,YAAY,CAAC,OAAgB;QACjC,MAAM,SAAS,GAAG,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC;QACzD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;QACxC,MAAM,aAAa,GAAG,GAAG,CAAC;QAE1B,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;YAC7B,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,EAAE;oBACnF,MAAM,EAAE,KAAK;oBACb,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC;iBAClC,CAAC,CAAC;gBAEH,IAAI,QAAQ,CAAC,EAAE,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;oBAC3C,oFAAoF;oBACpF,IAAI,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;oBAC5B,OAAO;gBACT,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,uBAAuB;YACzB,CAAC;YAED,MAAM,KAAK,CAAC,aAAa,CAAC,CAAC;QAC7B,CAAC;QAED,MAAM,IAAI,KAAK,CAAC,sCAAsC,SAAS,IAAI,CAAC,CAAC;IACvE,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO;QACX,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,OAAO;QACL,OAAO,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IAED;;OAEG;IACH,SAAS;QACP,IAAI,CAAC,IAAI,GAAG,EAAE,CAAC;IACjB,CAAC;IAED,sEAAsE;IACtE,kBAAkB;IAClB,sEAAsE;IAE9D,KAAK,CAAC,YAAY;QACxB,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;YAC1B,0DAA0D;YAC1D,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;YAC1B,OAAO;QACT,CAAC;QAED,IAAI,CAAC,GAAG,CAAC,oBAAoB,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;QAErD,MAAM,GAAG,GAAG;YACV,GAAG,OAAO,CAAC,GAAG;YACd,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG;YACnB,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;SAChC,CAAC;QAEF,mEAAmE;QACnE,sDAAsD;QACtD,IAAI,CAAC,OAAO,GAAG,IAAA,qBAAK,EAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,EAAE;YAC7C,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG;YACrB,GAAG;YACH,KAAK,EAAE,IAAI;YACX,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;SAChC,CAAC,CAAC;QAEH,sCAAsC;QACtC,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;YACnC,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC;QACpC,CAAC;QAED,iBAAiB;QACjB,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,IAAY,EAAE,EAAE;YAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC7B,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACrB,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;gBACvB,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;YAChC,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,iBAAiB;QACjB,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,IAAY,EAAE,EAAE;YAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC7B,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;YAClC,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;gBACvB,OAAO,CAAC,KAAK,CAAC,gBAAgB,EAAE,IAAI,CAAC,CAAC;YACxC,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,wDAAwD;QACxD,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;YAC/B,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,iBAAiB,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YAC/C,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;gBACvB,OAAO,CAAC,KAAK,CAAC,sBAAsB,EAAE,GAAG,CAAC,CAAC;YAC7C,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,2FAA2F;QAC3F,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;YACjC,IAAI,CAAC,GAAG,CAAC,mCAAmC,IAAI,EAAE,CAAC,CAAC;QACtD,CAAC,CAAC,CAAC;QAEH,8BAA8B;QAC9B,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;IAC5B,CAAC;IAEO,GAAG,CAAC,OAAe;QACzB,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;YACvB,OAAO,CAAC,GAAG,CAAC,gBAAgB,OAAO,EAAE,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;CACF;AAjQD,gCAiQC;AAED,sEAAsE;AACtE,YAAY;AACZ,sEAAsE;AAEtE;;GAEG;AACI,KAAK,UAAU,iBAAiB;IACrC,mFAAmF;IACnF,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,CAAC;IAE7C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;QAE9B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE;YACpB,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;YACjC,IAAI,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;gBAC3C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;gBAC1B,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;YACpC,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC,CAAC;YAC1C,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC7B,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC","sourcesContent":["/**\n * @file test-server.ts\n * @description Test server management for E2E testing\n */\n\nimport { spawn, ChildProcess } from 'child_process';\n\n// ═══════════════════════════════════════════════════════════════════\n// TYPES\n// ═══════════════════════════════════════════════════════════════════\n\nexport interface TestServerOptions {\n  /** Port to run the server on (default: random available port) */\n  port?: number;\n  /** Command to start the server */\n  command?: string;\n  /** Working directory */\n  cwd?: string;\n  /** Environment variables */\n  env?: Record<string, string>;\n  /** Timeout for server startup in milliseconds (default: 30000) */\n  startupTimeout?: number;\n  /** Path to check for server readiness (default: /health) */\n  healthCheckPath?: string;\n  /** Enable debug logging */\n  debug?: boolean;\n}\n\nexport interface TestServerInfo {\n  /** Base URL of the server */\n  baseUrl: string;\n  /** Port the server is running on */\n  port: number;\n  /** Process ID (if available) */\n  pid?: number;\n}\n\n// ═══════════════════════════════════════════════════════════════════\n// TEST SERVER CLASS\n// ═══════════════════════════════════════════════════════════════════\n\n/**\n * Manages test server lifecycle for E2E testing\n *\n * @example\n * ```typescript\n * // Start a server with custom command\n * const server = await TestServer.start({\n *   command: 'node dist/main.js',\n *   port: 3003,\n *   cwd: './apps/my-server',\n * });\n *\n * // Or start an Nx project\n * const server = await TestServer.startNx('demo-public', { port: 3003 });\n *\n * // Use the server\n * console.log(server.info.baseUrl); // http://localhost:3003\n *\n * // Stop when done\n * await server.stop();\n * ```\n */\nexport class TestServer {\n  private process: ChildProcess | null = null;\n  private readonly options: Required<TestServerOptions>;\n  private _info: TestServerInfo;\n  private logs: string[] = [];\n\n  private constructor(options: TestServerOptions, port: number) {\n    this.options = {\n      port,\n      command: options.command ?? '',\n      cwd: options.cwd ?? process.cwd(),\n      env: options.env ?? {},\n      startupTimeout: options.startupTimeout ?? 30000,\n      healthCheckPath: options.healthCheckPath ?? '/health',\n      debug: options.debug ?? false,\n    };\n\n    this._info = {\n      baseUrl: `http://localhost:${port}`,\n      port,\n    };\n  }\n\n  /**\n   * Start a test server with custom command\n   */\n  static async start(options: TestServerOptions): Promise<TestServer> {\n    const port = options.port ?? (await findAvailablePort());\n    const server = new TestServer(options, port);\n    try {\n      await server.startProcess();\n    } catch (error) {\n      await server.stop(); // Clean up spawned process to prevent leaks\n      throw error;\n    }\n    return server;\n  }\n\n  /**\n   * Start an Nx project as test server\n   */\n  static async startNx(project: string, options: Partial<TestServerOptions> = {}): Promise<TestServer> {\n    // Validate project name contains only safe characters to prevent shell injection\n    if (!/^[\\w-]+$/.test(project)) {\n      throw new Error(\n        `Invalid project name: ${project}. Must contain only alphanumeric, underscore, and hyphen characters.`,\n      );\n    }\n\n    const port = options.port ?? (await findAvailablePort());\n\n    const serverOptions: TestServerOptions = {\n      ...options,\n      port,\n      command: `npx nx serve ${project} --port ${port}`,\n      cwd: options.cwd ?? process.cwd(),\n    };\n\n    const server = new TestServer(serverOptions, port);\n    try {\n      await server.startProcess();\n    } catch (error) {\n      await server.stop(); // Clean up spawned process to prevent leaks\n      throw error;\n    }\n    return server;\n  }\n\n  /**\n   * Create a test server connected to an already running server\n   */\n  static connect(baseUrl: string): TestServer {\n    const url = new URL(baseUrl);\n    const port = parseInt(url.port, 10) || (url.protocol === 'https:' ? 443 : 80);\n\n    const server = new TestServer(\n      {\n        command: '',\n        port,\n      },\n      port,\n    );\n\n    server._info = {\n      baseUrl: baseUrl.replace(/\\/$/, ''),\n      port,\n    };\n\n    return server;\n  }\n\n  /**\n   * Get server information\n   */\n  get info(): TestServerInfo {\n    return { ...this._info };\n  }\n\n  /**\n   * Stop the test server\n   */\n  async stop(): Promise<void> {\n    if (this.process) {\n      this.log('Stopping server...');\n\n      // Try graceful shutdown first\n      this.process.kill('SIGTERM');\n\n      // Wait for process to exit\n      const exitPromise = new Promise<void>((resolve) => {\n        if (this.process) {\n          this.process.once('exit', () => resolve());\n        } else {\n          resolve();\n        }\n      });\n\n      // Force kill after timeout (but still wait for actual exit)\n      const killTimeout = setTimeout(() => {\n        if (this.process) {\n          this.log('Force killing server after timeout...');\n          this.process.kill('SIGKILL');\n        }\n      }, 5000);\n\n      await exitPromise;\n      clearTimeout(killTimeout);\n      this.process = null;\n      this.log('Server stopped');\n    }\n  }\n\n  /**\n   * Wait for server to be ready\n   */\n  async waitForReady(timeout?: number): Promise<void> {\n    const timeoutMs = timeout ?? this.options.startupTimeout;\n    const deadline = Date.now() + timeoutMs;\n    const checkInterval = 100;\n\n    while (Date.now() < deadline) {\n      try {\n        const response = await fetch(`${this._info.baseUrl}${this.options.healthCheckPath}`, {\n          method: 'GET',\n          signal: AbortSignal.timeout(1000),\n        });\n\n        if (response.ok || response.status === 404) {\n          // 404 is okay - it means the server is running but might not have a health endpoint\n          this.log('Server is ready');\n          return;\n        }\n      } catch {\n        // Server not ready yet\n      }\n\n      await sleep(checkInterval);\n    }\n\n    throw new Error(`Server did not become ready within ${timeoutMs}ms`);\n  }\n\n  /**\n   * Restart the server\n   */\n  async restart(): Promise<void> {\n    await this.stop();\n    await this.startProcess();\n  }\n\n  /**\n   * Get captured server logs\n   */\n  getLogs(): string[] {\n    return [...this.logs];\n  }\n\n  /**\n   * Clear captured logs\n   */\n  clearLogs(): void {\n    this.logs = [];\n  }\n\n  // ═══════════════════════════════════════════════════════════════════\n  // PRIVATE METHODS\n  // ═══════════════════════════════════════════════════════════════════\n\n  private async startProcess(): Promise<void> {\n    if (!this.options.command) {\n      // No command means we're connecting to an existing server\n      await this.waitForReady();\n      return;\n    }\n\n    this.log(`Starting server: ${this.options.command}`);\n\n    const env = {\n      ...process.env,\n      ...this.options.env,\n      PORT: String(this.options.port),\n    };\n\n    // Use shell: true to handle complex commands with quoted arguments\n    // This avoids fragile command parsing with split(' ')\n    this.process = spawn(this.options.command, [], {\n      cwd: this.options.cwd,\n      env,\n      shell: true,\n      stdio: ['pipe', 'pipe', 'pipe'],\n    });\n\n    // pid can be undefined if spawn fails\n    if (this.process.pid !== undefined) {\n      this._info.pid = this.process.pid;\n    }\n\n    // Capture stdout\n    this.process.stdout?.on('data', (data: Buffer) => {\n      const text = data.toString();\n      this.logs.push(text);\n      if (this.options.debug) {\n        console.log('[SERVER]', text);\n      }\n    });\n\n    // Capture stderr\n    this.process.stderr?.on('data', (data: Buffer) => {\n      const text = data.toString();\n      this.logs.push(`[ERROR] ${text}`);\n      if (this.options.debug) {\n        console.error('[SERVER ERROR]', text);\n      }\n    });\n\n    // Handle spawn errors to prevent unhandled error events\n    this.process.on('error', (err) => {\n      this.logs.push(`[SPAWN ERROR] ${err.message}`);\n      if (this.options.debug) {\n        console.error('[SERVER SPAWN ERROR]', err);\n      }\n    });\n\n    // Handle process exit - use once() to avoid memory leak from listener not being cleaned up\n    this.process.once('exit', (code) => {\n      this.log(`Server process exited with code ${code}`);\n    });\n\n    // Wait for server to be ready\n    await this.waitForReady();\n  }\n\n  private log(message: string): void {\n    if (this.options.debug) {\n      console.log(`[TestServer] ${message}`);\n    }\n  }\n}\n\n// ═══════════════════════════════════════════════════════════════════\n// UTILITIES\n// ═══════════════════════════════════════════════════════════════════\n\n/**\n * Find an available port\n */\nexport async function findAvailablePort(): Promise<number> {\n  // Use a simple approach: try to create a server on port 0 to get an available port\n  const { createServer } = await import('net');\n\n  return new Promise((resolve, reject) => {\n    const server = createServer();\n\n    server.listen(0, () => {\n      const address = server.address();\n      if (address && typeof address !== 'string') {\n        const port = address.port;\n        server.close(() => resolve(port));\n      } else {\n        reject(new Error('Could not get port'));\n      }\n    });\n\n    server.on('error', reject);\n  });\n}\n\n/**\n * Sleep for specified milliseconds\n */\nfunction sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n"]}

package/src/setup.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @file setup.ts
+ * @description Jest setup file for @frontmcp/testing
+ *
+ * This file registers custom MCP matchers with Jest.
+ * Include it in your Jest config's setupFilesAfterEnv:
+ *
+ * @example jest.config.ts
+ * ```typescript
+ * export default {
+ *   setupFilesAfterEnv: ['@frontmcp/testing/setup'],
+ * };
+ * ```
+ *
+ * Or use the preset:
+ * ```typescript
+ * export default {
+ *   preset: '@frontmcp/testing/jest-preset',
+ * };
+ * ```
+ */
+import './matchers/matcher-types';

package/src/setup.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * @file setup.ts
+ * @description Jest setup file for @frontmcp/testing
+ *
+ * This file registers custom MCP matchers with Jest.
+ * Include it in your Jest config's setupFilesAfterEnv:
+ *
+ * @example jest.config.ts
+ * ```typescript
+ * export default {
+ *   setupFilesAfterEnv: ['@frontmcp/testing/setup'],
+ * };
+ * ```
+ *
+ * Or use the preset:
+ * ```typescript
+ * export default {
+ *   preset: '@frontmcp/testing/jest-preset',
+ * };
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const globals_1 = require("@jest/globals");
+const mcp_matchers_1 = require("./matchers/mcp-matchers");
+// Register custom matchers with Jest
+globals_1.expect.extend(mcp_matchers_1.mcpMatchers);
+// Import type augmentation
+require("./matchers/matcher-types");
+//# sourceMappingURL=setup.js.map

package/src/setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../src/setup.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;AAEH,2CAAuC;AACvC,0DAAsD;AAEtD,qCAAqC;AACrC,gBAAM,CAAC,MAAM,CAAC,0BAAW,CAAC,CAAC;AAE3B,2BAA2B;AAC3B,oCAAkC","sourcesContent":["/**\n * @file setup.ts\n * @description Jest setup file for @frontmcp/testing\n *\n * This file registers custom MCP matchers with Jest.\n * Include it in your Jest config's setupFilesAfterEnv:\n *\n * @example jest.config.ts\n * ```typescript\n * export default {\n *   setupFilesAfterEnv: ['@frontmcp/testing/setup'],\n * };\n * ```\n *\n * Or use the preset:\n * ```typescript\n * export default {\n *   preset: '@frontmcp/testing/jest-preset',\n * };\n * ```\n */\n\nimport { expect } from '@jest/globals';\nimport { mcpMatchers } from './matchers/mcp-matchers';\n\n// Register custom matchers with Jest\nexpect.extend(mcpMatchers);\n\n// Import type augmentation\nimport './matchers/matcher-types';\n"]}

package/src/transport/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @file transport/index.ts
+ * @description Transport layer exports
+ */
+export type { McpTransport, TransportConfig, TransportState, JsonRpcRequest, JsonRpcResponse, } from './transport.interface';
+export { StreamableHttpTransport } from './streamable-http.transport';

package/src/transport/index.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * @file transport/index.ts
+ * @description Transport layer exports
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StreamableHttpTransport = void 0;
+var streamable_http_transport_1 = require("./streamable-http.transport");
+Object.defineProperty(exports, "StreamableHttpTransport", { enumerable: true, get: function () { return streamable_http_transport_1.StreamableHttpTransport; } });
+//# sourceMappingURL=index.js.map

package/src/transport/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/transport/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AASH,yEAAsE;AAA7D,oIAAA,uBAAuB,OAAA","sourcesContent":["/**\n * @file transport/index.ts\n * @description Transport layer exports\n */\n\nexport type {\n  McpTransport,\n  TransportConfig,\n  TransportState,\n  JsonRpcRequest,\n  JsonRpcResponse,\n} from './transport.interface';\nexport { StreamableHttpTransport } from './streamable-http.transport';\n"]}

package/src/transport/streamable-http.transport.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @file streamable-http.transport.ts
+ * @description StreamableHTTP transport implementation for MCP Test Client
+ */
+import type { McpTransport, TransportConfig, TransportState, JsonRpcRequest, JsonRpcResponse } from './transport.interface';
+import type { InterceptorChain } from '../interceptor';
+/**
+ * StreamableHTTP transport for MCP communication
+ *
+ * This transport uses HTTP POST requests for all communication,
+ * following the MCP StreamableHTTP specification.
+ */
+export declare class StreamableHttpTransport implements McpTransport {
+    private readonly config;
+    private state;
+    private sessionId;
+    private authToken;
+    private connectionCount;
+    private reconnectCount;
+    private lastRequestHeaders;
+    private interceptors?;
+    private readonly publicMode;
+    constructor(config: TransportConfig);
+    connect(): Promise<void>;
+    /**
+     * Request an anonymous token from the FrontMCP OAuth endpoint
+     * This allows the test client to authenticate without user interaction
+     */
+    private requestAnonymousToken;
+    request<T = unknown>(message: JsonRpcRequest): Promise<JsonRpcResponse & {
+        result?: T;
+    }>;
+    notify(message: JsonRpcRequest): Promise<void>;
+    sendRaw(data: string): Promise<JsonRpcResponse>;
+    close(): Promise<void>;
+    isConnected(): boolean;
+    getState(): TransportState;
+    getSessionId(): string | undefined;
+    setAuthToken(token: string): void;
+    setTimeout(ms: number): void;
+    setInterceptors(interceptors: InterceptorChain): void;
+    getInterceptors(): InterceptorChain | undefined;
+    getConnectionCount(): number;
+    getReconnectCount(): number;
+    getLastRequestHeaders(): Record<string, string>;
+    simulateDisconnect(): Promise<void>;
+    waitForReconnect(timeoutMs: number): Promise<void>;
+    private buildHeaders;
+    private ensureConnected;
+    private log;
+    /**
+     * Parse SSE (Server-Sent Events) response format with session ID extraction
+     * SSE format is:
+     * event: message
+     * id: sessionId:messageId
+     * data: {"jsonrpc":"2.0",...}
+     *
+     * The id field contains the session ID followed by a colon and the message ID.
+     *
+     * @param text - The raw SSE response text
+     * @param requestId - The original request ID
+     * @returns Object with parsed JSON-RPC response and session ID (if found)
+     */
+    private parseSSEResponseWithSession;
+}