@testspectra/cli 1.1.11-rc.3 → 1.1.12

package/dist/lifecycle/hook-dispatcher.js

@@ -0,0 +1,190 @@
+import { pathToFileURL } from 'url';
+export class HookExecutionError extends Error {
+    phase;
+    originalError;
+    constructor(phase, originalError) {
+        super(`Hook failure during [${phase}]: ${originalError?.message || String(originalError)}`);
+        this.phase = phase;
+        this.originalError = originalError;
+        this.name = 'HookExecutionError';
+    }
+}
+export async function runHook(hookPathOrFn, timeoutMs = 10000) {
+    let fn;
+    if (typeof hookPathOrFn === 'function') {
+        fn = hookPathOrFn;
+    }
+    else {
+        try {
+            const fileUrl = pathToFileURL(hookPathOrFn).href;
+            const mod = await import(fileUrl);
+            fn = mod.default || mod;
+            if (typeof fn !== 'function') {
+                throw new Error(`Hook file ${hookPathOrFn} does not export a default function`);
+            }
+        }
+        catch (err) {
+            throw new Error(`Failed to load hook from ${hookPathOrFn}: ${err.message}`);
+        }
+    }
+    let timeoutId = null;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => {
+            reject(new Error(`Hook execution timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+    });
+    try {
+        await Promise.race([Promise.resolve(fn()), timeoutPromise]);
+    }
+    finally {
+        if (timeoutId)
+            clearTimeout(timeoutId);
+    }
+}
+export class LifecycleDispatcher {
+    mode;
+    globalHooks;
+    constructor(mode = 'single', globalHooks = { before: [], after: [] }) {
+        this.mode = mode;
+        this.globalHooks = globalHooks;
+    }
+    async runGlobalBefore() {
+        if (this.mode !== 'global')
+            return;
+        for (const hook of this.globalHooks.before) {
+            try {
+                await runHook(hook);
+            }
+            catch (err) {
+                throw new HookExecutionError('globalBefore', err);
+            }
+        }
+    }
+    async runGlobalAfter() {
+        if (this.mode !== 'global')
+            return;
+        let firstError = null;
+        for (const hook of this.globalHooks.after) {
+            try {
+                await runHook(hook);
+            }
+            catch (err) {
+                if (!firstError)
+                    firstError = err;
+            }
+        }
+        if (firstError) {
+            throw new HookExecutionError('globalAfter', firstError);
+        }
+    }
+    async executeSuite(suiteName, suiteHooks, testCases) {
+        const results = [];
+        let suiteLevelError;
+        // 1. Run suite before hook
+        let beforeSuiteFailed = false;
+        for (const hook of suiteHooks.before) {
+            try {
+                await runHook(hook);
+            }
+            catch (err) {
+                beforeSuiteFailed = true;
+                suiteLevelError = new HookExecutionError('before', err);
+                break;
+            }
+        }
+        if (beforeSuiteFailed) {
+            // All test cases in suite are skipped / marked ERROR
+            for (const tc of testCases) {
+                results.push({
+                    id: tc.id,
+                    title: tc.title,
+                    status: 'ERROR',
+                    error: suiteLevelError,
+                    durationMs: 0,
+                });
+            }
+            // Always execute suite after hook even on before failure
+            for (const hook of suiteHooks.after) {
+                try {
+                    await runHook(hook);
+                }
+                catch { }
+            }
+            return {
+                suiteName,
+                results,
+                status: 'ERROR',
+                error: suiteLevelError,
+            };
+        }
+        // 2. Run each test case with beforeEach and afterEach
+        for (const tc of testCases) {
+            const startTime = Date.now();
+            let tcStatus = 'PASSED';
+            let tcError;
+            let beforeEachFailed = false;
+            // Run beforeEach hooks
+            for (const hook of suiteHooks.beforeEach) {
+                try {
+                    await runHook(hook);
+                }
+                catch (err) {
+                    beforeEachFailed = true;
+                    tcStatus = 'ERROR';
+                    tcError = new HookExecutionError('beforeEach', err);
+                    break;
+                }
+            }
+            // Run test body if beforeEach passed
+            if (!beforeEachFailed) {
+                try {
+                    await tc.fn();
+                    tcStatus = 'PASSED';
+                }
+                catch (err) {
+                    tcStatus = 'FAILED';
+                    tcError = err instanceof Error ? err : new Error(String(err));
+                }
+            }
+            // afterEach is GUARANTEED to execute even if beforeEach or test body failed
+            for (const hook of suiteHooks.afterEach) {
+                try {
+                    await runHook(hook);
+                }
+                catch (err) {
+                    // If test passed or failed, an afterEach failure transitions it to ERROR (Teardown Failure)
+                    tcStatus = 'ERROR';
+                    if (!tcError) {
+                        tcError = new HookExecutionError('afterEach', err);
+                    }
+                }
+            }
+            results.push({
+                id: tc.id,
+                title: tc.title,
+                status: tcStatus,
+                error: tcError,
+                durationMs: Date.now() - startTime,
+            });
+        }
+        // 3. Run suite after hook
+        for (const hook of suiteHooks.after) {
+            try {
+                await runHook(hook);
+            }
+            catch (err) {
+                if (!suiteLevelError) {
+                    suiteLevelError = new HookExecutionError('after', err);
+                }
+            }
+        }
+        const hasErrors = results.some((r) => r.status === 'ERROR') || !!suiteLevelError;
+        const hasFailures = results.some((r) => r.status === 'FAILED');
+        return {
+            suiteName,
+            results,
+            status: hasErrors ? 'ERROR' : hasFailures ? 'FAILED' : 'PASSED',
+            error: suiteLevelError,
+        };
+    }
+}

package/dist/lifecycle/index.d.ts

@@ -0,0 +1,3 @@
+export * from './hook-discovery.js';
+export * from './hook-dispatcher.js';
+export * from './parallel-grouping.js';

package/dist/lifecycle/index.js

@@ -0,0 +1,3 @@
+export * from './hook-discovery.js';
+export * from './hook-dispatcher.js';
+export * from './parallel-grouping.js';

package/dist/lifecycle/parallel-grouping.d.ts

@@ -0,0 +1,27 @@
+export type ParallelizationMode = 'suite' | 'testcase';
+export interface WorkerSizingOptions {
+    maxWorkersCap?: number;
+    userConcurrency?: number;
+    cpuQuotaOverride?: number;
+    memoryBytesOverride?: number;
+}
+/**
+ * Detects actual CPU quota available to the process, accounting for
+ * Docker and Kubernetes cgroup v1 and cgroup v2 container limits.
+ */
+export declare function detectContainerCpuQuota(): number;
+/**
+ * Detects available memory in bytes, respecting container cgroup memory limits
+ * to prevent Linux OOM (Out of Memory) kills.
+ */
+export declare function detectAvailableMemoryBytes(): number;
+/**
+ * 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 declare function calculateWorkerCount(targetItems: any[], options?: WorkerSizingOptions | number): number;
+export declare function groupSpecs(specPaths: string[], mode?: ParallelizationMode): (string | string[])[];

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/reporter/semantic-formatter.js

@@ -97,6 +97,8 @@ export function formatAction(actionKey, target, args = {}) {
             return `Scroll ${args.direction ?? '{direction}'} by ${args.pixels ?? '{pixels}'}px`;
         case 'swipe':
             return `Swipe ${args.direction ?? '{direction}'} by ${args.distance ?? '{distance}'}px`;
+        case 'upload':
+            return `Upload file "${args.files ?? args.value ?? args.file ?? '{file}'}" to ${el}`;
         case 'intercept':
             return `Intercept ${args.method ?? '{method}'} "${args.url ?? '{url}'}" mock rule registered`;
         case 'clearCookies':

package/dist/reporter/types.d.ts

@@ -1,2 +1,2 @@
-export type ActionKey = 'click' | 'doubleClick' | 'rightClick' | 'type' | 'clear' | 'select' | 'hover' | 'dragDrop' | 'scrollIntoView' | 'longPress' | 'waitForElement' | 'navigate' | 'back' | 'forward' | 'refresh' | 'setViewport' | 'wait' | 'pressKey' | 'scroll' | 'swipe' | 'intercept' | 'clearCookies' | 'setCookies' | 'clearLocalStorage';
+export type ActionKey = 'click' | 'doubleClick' | 'rightClick' | 'type' | 'clear' | 'select' | 'hover' | 'dragDrop' | 'scrollIntoView' | 'longPress' | 'waitForElement' | 'navigate' | 'back' | 'forward' | 'refresh' | 'setViewport' | 'wait' | 'pressKey' | 'scroll' | 'swipe' | 'upload' | 'intercept' | 'clearCookies' | 'setCookies' | 'clearLocalStorage';
 export type AssertionKey = 'be.visible' | 'not.be.visible' | 'exist' | 'not.exist' | 'be.clickable' | 'not.be.clickable' | 'be.enabled' | 'be.disabled' | 'be.checked' | 'not.be.checked' | 'be.selected' | 'not.be.selected' | 'be.focused' | 'not.be.focused' | 'have.text' | 'not.have.text' | 'contain.text' | 'not.contain.text' | 'have.value' | 'not.have.value' | 'contain.value' | 'not.contain.value' | 'have.attr' | 'not.have.attr' | 'have.class' | 'not.have.class' | 'have.css' | 'not.have.css' | 'have.length' | 'not.have.length' | 'have.length.greaterThan' | 'have.length.lessThan' | 'be.empty' | 'not.be.empty' | 'shouldHaveUrl' | 'shouldContainUrl' | 'shouldHaveTitle' | 'shouldContainTitle' | 'shouldBeLoaded' | 'shouldBePageLoaded' | 'shouldHaveNoConsoleErrors' | 'have.url' | 'contain.url' | 'have.title' | 'contain.title' | 'be.loaded' | 'be.pageLoaded' | 'have.noConsoleErrors';

package/dist/runner/bridge.d.ts

@@ -18,6 +18,8 @@ export interface RunOptions {
     concurrency?: number;
     failedOnly?: boolean;
     failedTarget?: string;
+    debug?: boolean;
+    inspectPort?: number;
 }
 export declare class RustCoreBridge {
     static resolveBinaryPath(): string;

package/dist/runner/bridge.js

@@ -121,6 +121,8 @@ export class RustCoreBridge {
             concurrency: options.concurrency,
             failedOnly: options.failedOnly,
             failedTarget: options.failedTarget,
+            debug: options.debug,
+            inspectPort: options.inspectPort,
         });
         const home = process.env.HOME || process.env.USERPROFILE || '';
         const globalDriversDir = path.join(home, '.testspectra', 'drivers');
@@ -162,7 +164,8 @@ export class RustCoreBridge {
                         // a real TTY (CI, or an external tool like the VS Code extension spawning this process
                         // via a pipe) — in that case this raw line is the *only* live signal a wrapping process
                         // can see, so it must still reach stdout verbatim.
-                        if (!reporter.isInteractiveMode()) {
+                        // Always forward inspector websocket URL so IDE tools can attach directly.
+                        if (line.startsWith('[TESTSPECTRA_DEBUG_INSPECTOR]') || !reporter.isInteractiveMode()) {
                             console.log(line);
                         }
                         continue;

package/dist/runner/reporter.d.ts

@@ -1,55 +1,17 @@
-export interface TestLog {
-    timestamp: string;
-    level: 'INFO' | 'SUCCESS' | 'WARNING' | 'ERROR' | 'DEBUG' | string;
-    message: string;
-}
-export interface NetworkResource {
-    requestId: string;
-    url: string;
-    method: string;
-    status: number;
-}
-export interface TestRunResult {
-    status: 'passed' | 'failed' | 'error' | string;
-    duration: string;
-    passedCount: number;
-    failedCount: number;
-    logs: TestLog[];
-    networkResources?: NetworkResource[];
-}
-export interface PendingStep {
-    text: string;
-    duration: number;
-    passed: boolean;
-}
-export interface PendingTestCase {
-    title: string;
-    workerId?: number;
-    steps: PendingStep[];
-    currentStep?: string;
-    errorMsg?: string;
-    startTime: number;
-}
-export declare class Reporter {
-    private logs;
-    private networkEvents;
-    private pendingTests;
-    private workerToTest;
-    private pendingErrorMsg?;
-    private passedCount;
-    private failedCount;
+import { type ActionKey, type AssertionKey, type ExecutionSummary, formatAction, formatAssertion, type NetworkResource, parseAndFormat, type PendingStep, type PendingTestCase, type ReporterOptions, SemanticReporter, stripAnsi, type TestLog, type TestRunResult } from '@testspectra/reporter';
+export { type ActionKey, type AssertionKey, type ExecutionSummary, formatAction, formatAssertion, type NetworkResource, parseAndFormat, type PendingStep, type PendingTestCase, type ReporterOptions, SemanticReporter, stripAnsi, type TestLog, type TestRunResult, };
+export declare class Reporter extends SemanticReporter {
     private isInteractive;
     private lastRenderedLines;
     private spinnerFrames;
     private spinnerIndex;
     private spinnerTimer;
-    constructor();
+    constructor(options?: ReporterOptions);
     /** Whether this reporter is drawing the live-updating interactive terminal UI (real TTY, not CI/VS Code/test). */
     isInteractiveMode(): boolean;
     private clearActiveSlots;
     private renderActiveSlots;
-    private resolveTestCase;
-    addLog(log: TestLog): void;
+    addLog(input: string | TestLog): void;
     addNetwork(res: NetworkResource): void;
     getLogs(): TestLog[];
     getNetworkEvents(): NetworkResource[];