@testspectra/cli 1.1.8-rc.30 → 1.1.8-rc.33

package/dist/lifecycle/parallel-grouping.js

@@ -0,0 +1,151 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+/**
+ * Detects actual CPU quota available to the process, accounting for
+ * Docker and Kubernetes cgroup v1 and cgroup v2 container limits.
+ */
+export function detectContainerCpuQuota() {
+    try {
+        // 1. Check cgroup v2 (Unified Hierarchy): /sys/fs/cgroup/cpu.max
+        // Format: "<quota> <period>" e.g. "200000 100000" or "max 100000"
+        if (fs.existsSync('/sys/fs/cgroup/cpu.max')) {
+            const content = fs.readFileSync('/sys/fs/cgroup/cpu.max', 'utf-8').trim();
+            const [quotaStr, periodStr] = content.split(/\s+/);
+            if (quotaStr && quotaStr !== 'max' && periodStr) {
+                const quota = parseFloat(quotaStr);
+                const period = parseFloat(periodStr);
+                if (quota > 0 && period > 0) {
+                    return Math.max(0.5, quota / period);
+                }
+            }
+        }
+        // 2. Check cgroup v1: /sys/fs/cgroup/cpu/cpu.cfs_quota_us and cpu.cfs_period_us
+        if (fs.existsSync('/sys/fs/cgroup/cpu/cpu.cfs_quota_us') && fs.existsSync('/sys/fs/cgroup/cpu/cpu.cfs_period_us')) {
+            const quota = parseFloat(fs.readFileSync('/sys/fs/cgroup/cpu/cpu.cfs_quota_us', 'utf-8').trim());
+            const period = parseFloat(fs.readFileSync('/sys/fs/cgroup/cpu/cpu.cfs_period_us', 'utf-8').trim());
+            if (quota > 0 && period > 0) {
+                return Math.max(0.5, quota / period);
+            }
+        }
+    }
+    catch { }
+    // 3. Fallback to host CPU count
+    if (typeof os.availableParallelism === 'function') {
+        try {
+            return os.availableParallelism();
+        }
+        catch { }
+    }
+    return os.cpus()?.length || 2;
+}
+/**
+ * Detects available memory in bytes, respecting container cgroup memory limits
+ * to prevent Linux OOM (Out of Memory) kills.
+ */
+export function detectAvailableMemoryBytes() {
+    try {
+        // 1. Check cgroup v2: /sys/fs/cgroup/memory.max and /sys/fs/cgroup/memory.current
+        if (fs.existsSync('/sys/fs/cgroup/memory.max')) {
+            const maxStr = fs.readFileSync('/sys/fs/cgroup/memory.max', 'utf-8').trim();
+            if (maxStr !== 'max') {
+                const limit = parseFloat(maxStr);
+                let usage = 0;
+                if (fs.existsSync('/sys/fs/cgroup/memory.current')) {
+                    usage = parseFloat(fs.readFileSync('/sys/fs/cgroup/memory.current', 'utf-8').trim()) || 0;
+                }
+                if (limit > 0) {
+                    return Math.max(0, limit - usage);
+                }
+            }
+        }
+        // 2. Check cgroup v1: /sys/fs/cgroup/memory/memory.limit_in_bytes
+        if (fs.existsSync('/sys/fs/cgroup/memory/memory.limit_in_bytes')) {
+            const limit = parseFloat(fs.readFileSync('/sys/fs/cgroup/memory/memory.limit_in_bytes', 'utf-8').trim());
+            // cgroup v1 sets a huge number (e.g. 9223372036854771712) when no limit is enforced
+            if (limit > 0 && limit < 1e15) {
+                let usage = 0;
+                if (fs.existsSync('/sys/fs/cgroup/memory/memory.usage_in_bytes')) {
+                    usage = parseFloat(fs.readFileSync('/sys/fs/cgroup/memory/memory.usage_in_bytes', 'utf-8').trim()) || 0;
+                }
+                return Math.max(0, limit - usage);
+            }
+        }
+    }
+    catch { }
+    // 3. Fallback to host available memory (estimating reclaimable cache/buffer on modern OS)
+    try {
+        const free = os.freemem();
+        const total = os.totalmem();
+        return Math.max(free, total * 0.4);
+    }
+    catch {
+        return 1024 * 1024 * 1024; // 1 GB fallback
+    }
+}
+/**
+ * Dynamically computes optimal worker concurrency respecting:
+ * 1. Explicit user concurrency flag (--concurrency <N> or config)
+ * 2. Real container cgroups CPU quota & host CPU count
+ * 3. Low-CPU safety ratio (clamping <=2 CPUs to 1 worker, 3-4 CPUs to 2 workers)
+ * 4. Memory-aware guard (~600MB RAM budget per Chromium instance to prevent OOM kills)
+ * 5. Target items count & maximum worker cap
+ */
+export function calculateWorkerCount(targetItems, options) {
+    const opts = typeof options === 'number' ? { maxWorkersCap: options } : options || {};
+    const itemCount = targetItems.length;
+    if (itemCount === 0)
+        return 1;
+    // 1. Explicit User Concurrency has absolute priority
+    if (opts.userConcurrency && opts.userConcurrency > 0) {
+        return Math.min(opts.userConcurrency, itemCount);
+    }
+    // 2. Determine CPU Quota (cgroups aware)
+    const cpuCount = opts.cpuQuotaOverride !== undefined ? opts.cpuQuotaOverride : detectContainerCpuQuota();
+    // 3. Low-CPU Safety Ratio:
+    // - CPU <= 2: Max 1 worker (prevents severe thrashing on 2-vCPU CI runners)
+    // - CPU 3-4: Max 2 workers
+    // - CPU > 4: cpuCount - 2 (leaves 2 cores for OS/IDE/DevTools)
+    let cpuBasedWorkers = 1;
+    if (cpuCount <= 2) {
+        cpuBasedWorkers = 1;
+    }
+    else if (cpuCount <= 4) {
+        cpuBasedWorkers = 2;
+    }
+    else {
+        cpuBasedWorkers = Math.max(1, Math.floor(cpuCount - 2));
+    }
+    // 4. Memory-Aware Guard (Anti-OOM):
+    // Allocate ~600MB per Chromium browser instance
+    const MEMORY_PER_WORKER_BYTES = 600 * 1024 * 1024;
+    const availableMemBytes = opts.memoryBytesOverride !== undefined ? opts.memoryBytesOverride : detectAvailableMemoryBytes();
+    const memBasedWorkers = Math.max(1, Math.floor(availableMemBytes / MEMORY_PER_WORKER_BYTES));
+    // 5. Apply Maximum Cap and Item Count Clamping
+    const maxCap = opts.maxWorkersCap || 6;
+    return Math.max(1, Math.min(cpuBasedWorkers, memBasedWorkers, maxCap, itemCount));
+}
+export function groupSpecs(specPaths, mode = 'suite') {
+    if (mode === 'testcase') {
+        return [...specPaths];
+    }
+    // Group by suite directory
+    const suiteGroups = new Map();
+    for (const specPath of specPaths) {
+        const normalized = specPath.replace(/\\/g, '/');
+        const parts = normalized.split('/');
+        let suiteKey = 'default';
+        const specsIdx = parts.findIndex((p) => p === 'specs' || p === 'suites');
+        if (specsIdx !== -1 && specsIdx + 1 < parts.length) {
+            suiteKey = parts.slice(0, specsIdx + 2).join('/');
+        }
+        else {
+            suiteKey = path.dirname(normalized);
+        }
+        if (!suiteGroups.has(suiteKey)) {
+            suiteGroups.set(suiteKey, []);
+        }
+        suiteGroups.get(suiteKey).push(specPath);
+    }
+    return Array.from(suiteGroups.values());
+}

package/dist/utils/__tests__/dev-server-manager.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/__tests__/dev-server-manager.test.js

@@ -0,0 +1,72 @@
+import http from 'node:http';
+import { describe, expect, it, vi } from 'vitest';
+import { DevServerManager } from '../dev-server-manager.js';
+describe('DevServerManager', () => {
+    it('parses command strings into binary and argv array without shell', () => {
+        expect(DevServerManager.parseCommand('pnpm --filter sso dev')).toEqual({
+            bin: 'pnpm',
+            args: ['--filter', 'sso', 'dev'],
+        });
+        expect(DevServerManager.parseCommand('nx run auth-e2e:serve --port=5174')).toEqual({
+            bin: 'nx',
+            args: ['run', 'auth-e2e:serve', '--port=5174'],
+        });
+        expect(DevServerManager.parseCommand('node "./scripts/serve.js" --mode "dev test"')).toEqual({
+            bin: 'node',
+            args: ['./scripts/serve.js', '--mode', 'dev test'],
+        });
+    });
+    it('probes listening HTTP server and detects readiness', async () => {
+        const server = http.createServer((_req, res) => {
+            res.writeHead(200, { 'Content-Type': 'text/plain' });
+            res.end('OK');
+        });
+        await new Promise((resolve) => {
+            server.listen(0, '127.0.0.1', () => resolve());
+        });
+        const addr = server.address();
+        const url = `http://127.0.0.1:${addr.port}`;
+        const isReady = await DevServerManager.probeUrl(url, 1000);
+        expect(isReady).toBe(true);
+        const isNonExistentReady = await DevServerManager.probeUrl('http://127.0.0.1:49999', 200);
+        expect(isNonExistentReady).toBe(false);
+        await new Promise((resolve) => server.close(() => resolve()));
+    });
+    it('reuses existing running server without spawning new process', async () => {
+        const server = http.createServer((_req, res) => {
+            res.writeHead(200);
+            res.end('OK');
+        });
+        await new Promise((resolve) => {
+            server.listen(0, '127.0.0.1', () => resolve());
+        });
+        const addr = server.address();
+        const url = `http://127.0.0.1:${addr.port}`;
+        const manager = new DevServerManager();
+        const result = await manager.ensureServer({
+            name: 'test-server',
+            command: 'echo "should not run"',
+            url,
+            reuseExistingServer: true,
+        });
+        expect(result.reused).toBe(true);
+        expect(result.name).toBe('test-server');
+        expect(result.url).toBe(url);
+        await manager.stopAll();
+        await new Promise((resolve) => server.close(() => resolve()));
+    });
+    it('filters dev servers by target host filter', async () => {
+        const manager = new DevServerManager();
+        const spy = vi.spyOn(manager, 'ensureServer').mockResolvedValue({
+            name: 'sso',
+            url: 'https://sso.local:5174',
+            reused: true,
+        });
+        await manager.startAll([
+            { name: 'sso', command: 'pnpm sso:dev', url: 'https://sso.local:5174' },
+            { name: 'fam', command: 'pnpm fam:dev', url: 'https://fam.local:5175' },
+        ], 'sso');
+        expect(spy).toHaveBeenCalledTimes(1);
+        expect(spy).toHaveBeenCalledWith(expect.objectContaining({ name: 'sso' }), expect.any(String));
+    });
+});

package/dist/utils/dev-server-manager.d.ts

@@ -0,0 +1,40 @@
+import type { ChildProcess } from 'node:child_process';
+import type { DevServerConfig } from '../config/schema.js';
+export interface RunningDevServer {
+    name: string;
+    url: string;
+    process?: ChildProcess;
+    reused: boolean;
+}
+export declare class DevServerManager {
+    private spawnedProcesses;
+    private cleanupRegistered;
+    constructor();
+    /**
+     * Safely splits a shell command string into binary executable and argument array without shell expansion.
+     */
+    static parseCommand(command: string): {
+        bin: string;
+        args: string[];
+    };
+    /**
+     * Probes a URL to verify if the server is actively listening and responsive.
+     * Performs a rapid TCP connection test followed by an HTTP/HTTPS request.
+     */
+    static probeUrl(targetUrl: string, timeoutMs?: number): Promise<boolean>;
+    /**
+     * Ensures an individual dev server is running. If already responding and reuseExistingServer !== false,
+     * reuses the instance. Otherwise, spawns the process and polls until ready.
+     */
+    ensureServer(config: DevServerConfig, rootCwd?: string): Promise<RunningDevServer>;
+    /**
+     * Starts all matching dev servers in parallel.
+     */
+    startAll(configs?: DevServerConfig[], targetHostFilter?: string, rootCwd?: string): Promise<RunningDevServer[]>;
+    /**
+     * Safely terminates all spawned dev server child processes.
+     */
+    stopAll(): Promise<void>;
+    private killProcess;
+    private registerExitHooks;
+}

package/dist/utils/dev-server-manager.js

@@ -0,0 +1,257 @@
+import net from 'node:net';
+import http from 'node:http';
+import https from 'node:https';
+import path from 'node:path';
+import spawn from 'cross-spawn';
+export class DevServerManager {
+    spawnedProcesses = new Map();
+    cleanupRegistered = false;
+    constructor() {
+        this.registerExitHooks();
+    }
+    /**
+     * Safely splits a shell command string into binary executable and argument array without shell expansion.
+     */
+    static parseCommand(command) {
+        const trimmed = command.trim();
+        if (!trimmed) {
+            throw new Error('Dev server command cannot be empty');
+        }
+        const tokens = [];
+        let current = '';
+        let inQuotes = false;
+        let quoteChar = '';
+        for (let i = 0; i < trimmed.length; i++) {
+            const char = trimmed[i];
+            if ((char === '"' || char === "'") && (i === 0 || trimmed[i - 1] !== '\\')) {
+                if (inQuotes && char === quoteChar) {
+                    inQuotes = false;
+                    quoteChar = '';
+                }
+                else if (!inQuotes) {
+                    inQuotes = true;
+                    quoteChar = char;
+                }
+                else {
+                    current += char;
+                }
+            }
+            else if (/\s/.test(char) && !inQuotes) {
+                if (current.length > 0) {
+                    tokens.push(current);
+                    current = '';
+                }
+            }
+            else {
+                current += char;
+            }
+        }
+        if (current.length > 0) {
+            tokens.push(current);
+        }
+        const bin = tokens[0];
+        const args = tokens.slice(1);
+        return { bin, args };
+    }
+    /**
+     * Probes a URL to verify if the server is actively listening and responsive.
+     * Performs a rapid TCP connection test followed by an HTTP/HTTPS request.
+     */
+    static async probeUrl(targetUrl, timeoutMs = 1500) {
+        try {
+            const parsed = new URL(targetUrl);
+            const isHttps = parsed.protocol === 'https:';
+            const port = parsed.port ? parseInt(parsed.port, 10) : isHttps ? 443 : 80;
+            const hostname = parsed.hostname;
+            // 1. TCP Probe (Fast check)
+            const tcpReachable = await new Promise((resolve) => {
+                const socket = net.createConnection({ host: hostname, port, timeout: timeoutMs }, () => {
+                    socket.destroy();
+                    resolve(true);
+                });
+                socket.on('error', () => {
+                    socket.destroy();
+                    resolve(false);
+                });
+                socket.on('timeout', () => {
+                    socket.destroy();
+                    resolve(false);
+                });
+            });
+            if (!tcpReachable) {
+                return false;
+            }
+            // 2. HTTP/HTTPS Probe (Verify application readiness, bypass self-signed certs)
+            return await new Promise((resolve) => {
+                const transport = isHttps ? https : http;
+                const req = transport.request(targetUrl, {
+                    method: 'HEAD',
+                    timeout: timeoutMs,
+                    rejectUnauthorized: false,
+                }, (res) => {
+                    // Any valid HTTP response means server is alive and accepting traffic
+                    res.resume();
+                    resolve(true);
+                });
+                req.on('error', () => resolve(false));
+                req.on('timeout', () => {
+                    req.destroy();
+                    resolve(false);
+                });
+                req.end();
+            });
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Ensures an individual dev server is running. If already responding and reuseExistingServer !== false,
+     * reuses the instance. Otherwise, spawns the process and polls until ready.
+     */
+    async ensureServer(config, rootCwd = process.cwd()) {
+        const serverName = config.name || config.url;
+        const timeoutMs = config.timeout ?? 60000;
+        const reuse = config.reuseExistingServer !== false;
+        // Check if server is already running
+        if (reuse) {
+            const isRunning = await DevServerManager.probeUrl(config.url, 1000);
+            if (isRunning) {
+                console.log(`\x1b[36m[TestSpectra DevServer]\x1b[0m ⚡ Reusing active server \x1b[1m"${serverName}"\x1b[0m at \x1b[33m${config.url}\x1b[0m`);
+                return {
+                    name: serverName,
+                    url: config.url,
+                    reused: true,
+                };
+            }
+        }
+        console.log(`\x1b[36m[TestSpectra DevServer]\x1b[0m 🚀 Launching dev server \x1b[1m"${serverName}"\x1b[0m (\x1b[90m${config.command}\x1b[0m)...`);
+        const { bin, args } = DevServerManager.parseCommand(config.command);
+        const execCwd = config.cwd ? path.resolve(rootCwd, config.cwd) : rootCwd;
+        const logBuffer = [];
+        const pushLog = (data) => {
+            const lines = data.toString().split('\n');
+            for (const line of lines) {
+                if (line.trim()) {
+                    logBuffer.push(line);
+                    if (logBuffer.length > 50)
+                        logBuffer.shift();
+                }
+            }
+        };
+        const child = spawn(bin, args, {
+            cwd: execCwd,
+            env: { ...process.env, ...config.env },
+            stdio: ['ignore', 'pipe', 'pipe'],
+            detached: process.platform !== 'win32',
+        });
+        child.stdout?.on('data', pushLog);
+        child.stderr?.on('data', pushLog);
+        this.spawnedProcesses.set(serverName, {
+            child,
+            name: serverName,
+            url: config.url,
+            logBuffer,
+        });
+        const startTime = Date.now();
+        let isReady = false;
+        while (Date.now() - startTime < timeoutMs) {
+            if (child.exitCode !== null) {
+                const errorLogs = logBuffer.slice(-20).join('\n');
+                throw new Error(`Dev server "${serverName}" terminated prematurely with exit code ${child.exitCode}.\n` +
+                    `Last output:\n${errorLogs || '(no output)'}`);
+            }
+            isReady = await DevServerManager.probeUrl(config.url, 500);
+            if (isReady) {
+                const durationSec = ((Date.now() - startTime) / 1000).toFixed(1);
+                console.log(`\x1b[32m[TestSpectra DevServer] ✓ Server "${serverName}" ready at ${config.url} (${durationSec}s)\x1b[0m`);
+                return {
+                    name: serverName,
+                    url: config.url,
+                    process: child,
+                    reused: false,
+                };
+            }
+            await new Promise((r) => setTimeout(r, 200));
+        }
+        // Timeout exceeded — dump logs and kill child
+        this.killProcess(child);
+        this.spawnedProcesses.delete(serverName);
+        const errorLogs = logBuffer.slice(-25).join('\n');
+        throw new Error(`Dev server "${serverName}" timed out after ${timeoutMs}ms waiting for ${config.url}.\n` +
+            `Last output:\n${errorLogs || '(no output)'}`);
+    }
+    /**
+     * Starts all matching dev servers in parallel.
+     */
+    async startAll(configs = [], targetHostFilter, rootCwd = process.cwd()) {
+        if (!configs || configs.length === 0) {
+            return [];
+        }
+        let targetConfigs = configs;
+        if (targetHostFilter) {
+            const matched = configs.filter((c) => c.name === targetHostFilter);
+            if (matched.length > 0) {
+                targetConfigs = matched;
+            }
+        }
+        return Promise.all(targetConfigs.map((cfg) => this.ensureServer(cfg, rootCwd)));
+    }
+    /**
+     * Safely terminates all spawned dev server child processes.
+     */
+    async stopAll() {
+        if (this.spawnedProcesses.size === 0)
+            return;
+        for (const entry of this.spawnedProcesses.values()) {
+            try {
+                this.killProcess(entry.child);
+            }
+            catch { }
+        }
+        this.spawnedProcesses.clear();
+    }
+    killProcess(child) {
+        if (child.pid && !child.killed) {
+            if (process.platform !== 'win32') {
+                try {
+                    process.kill(-child.pid, 'SIGTERM');
+                }
+                catch {
+                    try {
+                        child.kill('SIGTERM');
+                    }
+                    catch { }
+                }
+            }
+            else {
+                try {
+                    child.kill('SIGTERM');
+                }
+                catch { }
+            }
+        }
+    }
+    registerExitHooks() {
+        if (this.cleanupRegistered)
+            return;
+        this.cleanupRegistered = true;
+        const cleanup = () => {
+            for (const entry of this.spawnedProcesses.values()) {
+                try {
+                    this.killProcess(entry.child);
+                }
+                catch { }
+            }
+        };
+        process.once('exit', cleanup);
+        process.once('SIGINT', () => {
+            cleanup();
+            process.exit(130);
+        });
+        process.once('SIGTERM', () => {
+            cleanup();
+            process.exit(143);
+        });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@testspectra/cli",
-  "version": "1.1.8-rc.30",
+  "version": "1.1.8-rc.33",
   "description": "TestSpectra Cross-Platform Test Runner CLI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -26,11 +26,12 @@
   ],
   "dependencies": {
     "@clack/prompts": "^1.7.0",
-    "@testspectra/matchers": "^1.1.8-rc.30",
-    "@testspectra/react": "^1.1.8-rc.30",
-    "@testspectra/skills": "^1.1.8-rc.30",
+    "@testspectra/matchers": "^1.1.8-rc.33",
+    "@testspectra/react": "^1.1.8-rc.33",
+    "@testspectra/skills": "^1.1.8-rc.33",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
+    "cross-spawn": "^7.0.6",
     "dotenv": "^16.4.5",
     "ora": "^8.0.1",
     "typescript": "^5.6.3",
@@ -38,11 +39,12 @@
     "zod": "^3.23.8"
   },
   "optionalDependencies": {
-    "@testspectra/cli-darwin-arm64": "1.1.8-rc.30",
-    "@testspectra/cli-linux-x64": "1.1.8-rc.30",
-    "@testspectra/cli-win32-x64": "1.1.8-rc.30"
+    "@testspectra/cli-darwin-arm64": "1.1.8-rc.33",
+    "@testspectra/cli-linux-x64": "1.1.8-rc.33",
+    "@testspectra/cli-win32-x64": "1.1.8-rc.33"
   },
   "devDependencies": {
+    "@types/cross-spawn": "^6.0.6",
     "@types/node": "^20.14.0",
     "@wdio/globals": "^9.24.0",
     "@wdio/mocha-framework": "^9.24.0",

package/templates/default/package.json

@@ -17,8 +17,8 @@
     "postinstall": "spectra sync-types"
   },
   "devDependencies": {
-    "@testspectra/cli": "^1.1.8-rc.30",
-    "@testspectra/matchers": "^1.1.8-rc.30",
+    "@testspectra/cli": "^1.1.8-rc.33",
+    "@testspectra/matchers": "^1.1.8-rc.33",
     "@types/node": "^20.14.0",
     "@wdio/cli": "^9.2.8",
     "@wdio/local-runner": "^9.2.8",