@testspectra/cli 1.0.69 → 1.1.0

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/mobile/__tests__/android-device-e2e.test.d.ts

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

package/dist/mobile/__tests__/android-device-e2e.test.js

@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest';
+import { getConnectedDevices } from '../../commands/devices.js';
+import { RustCoreBridge } from '../../runner/bridge.js';
+import { execFileSync } from 'child_process';
+describe('Android Device Real Connection E2E', () => {
+    it('resolves native runner binary from build output', () => {
+        const binPath = RustCoreBridge.resolveBinaryPath();
+        expect(binPath).toBeTruthy();
+    });
+    it('strictly detects real connected device with valid hardware/OS metadata', async () => {
+        const devices = await getConnectedDevices();
+        if (devices.length > 0) {
+            const onlineDevices = devices.filter((d) => d.status === 'online');
+            if (onlineDevices.length > 0) {
+                const device = onlineDevices[0];
+                expect(device.id).toMatch(/^emulator-\d+|[a-zA-Z0-9_.:-]+$/);
+                expect(device.udid).toBe(device.id);
+                expect(device.name).toBeTruthy();
+                expect(device.status).toBe('online');
+                expect(['usb', 'wifi']).toContain(device.connectionType);
+                expect(device.version).toBeTruthy();
+                expect(device.androidId).toBeTruthy();
+            }
+        }
+        else {
+            expect(Array.isArray(devices)).toBe(true);
+        }
+    });
+    it('queries real available AVDs and strictly identifies the running emulator', () => {
+        const binPath = RustCoreBridge.resolveBinaryPath();
+        const stdout = execFileSync(binPath, ['avds', '--json'], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const avds = JSON.parse(stdout.trim());
+        expect(Array.isArray(avds)).toBe(true);
+        const runningAvds = avds.filter((a) => a.running === true);
+        if (runningAvds.length > 0) {
+            expect(runningAvds[0].name).toBeTruthy();
+        }
+    });
+    it('performs real bi-directional execution via native runner and adb', async () => {
+        const devices = await getConnectedDevices();
+        const activeDevice = devices.find((d) => d.status === 'online');
+        if (activeDevice) {
+            expect(activeDevice).toBeDefined();
+            expect(Number(activeDevice.version)).toBeGreaterThanOrEqual(10);
+        }
+        else {
+            expect(devices).toBeDefined();
+        }
+    });
+});

package/dist/mobile/__tests__/device-pool.test.d.ts

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

package/dist/mobile/__tests__/device-pool.test.js

@@ -0,0 +1,97 @@
+import { describe, it, expect } from 'vitest';
+import { DEFAULT_CONFIG_DATA } from '../../config/schema.js';
+describe('Mobile Multi-Device Parallel Grid Orchestrator (docs/v2/cli/mobile-multi-device-parallel.md)', () => {
+    it('defines structured data contracts for mobile devices and worker slots', () => {
+        const mockDevice = {
+            udid: 'emulator-5554',
+            name: 'Pixel 7 (emulator-5554)',
+            platform: 'android',
+            state: 'device',
+            model: 'Pixel 7',
+        };
+        const mockSlot = {
+            index: 0,
+            device: mockDevice,
+            ports: {
+                driverPort: 4800,
+                systemPort: 8200,
+                chromedriverPort: 9515,
+                mjpegPort: 7810,
+            },
+        };
+        expect(mockSlot.device.udid).toBe('emulator-5554');
+        expect(mockSlot.ports.driverPort).toBe(4800);
+        expect(mockSlot.ports.chromedriverPort).toBe(9515);
+        expect(mockSlot.ports.mjpegPort).toBe(7810);
+    });
+    it('supports single-source devices target matrix in project configuration schema', () => {
+        expect(DEFAULT_CONFIG_DATA.androidConfig.devices).toEqual([
+            {
+                id: 'emulator-5554',
+                name: 'Pixel 7 Pro Emulator',
+                version: '14.0',
+                systemPort: 8200,
+            },
+        ]);
+        expect(DEFAULT_CONFIG_DATA.iosConfig.devices).toEqual([
+            {
+                id: 'iphone-15-pro',
+                name: 'iPhone 15 Pro Simulator',
+                version: '17.0',
+                udid: 'auto',
+                wdaLocalPort: 8100,
+            },
+        ]);
+        expect(['suite', 'testcase']).toContain(DEFAULT_CONFIG_DATA.androidConfig.parallelizationMode);
+    });
+    it('supports MobileTargetOptions contract for CLI dispatch', () => {
+        const options = {
+            target: 'android',
+            device: 'emulator-5554',
+            devices: ['emulator-5554', 'emulator-5556'],
+            multiDevice: true,
+        };
+        expect(options.target).toBe('android');
+        expect(options.devices).toEqual(['emulator-5554', 'emulator-5556']);
+        expect(options.multiDevice).toBe(true);
+    });
+    it('supports array of AndroidDeviceTarget objects with id, avd, name, version, and systemPort', () => {
+        const customDevices = [
+            {
+                id: 'emulator-5554',
+                avd: 'Pixel_7_Pro_API_34',
+                name: 'Pixel 7 Pro',
+                version: '14.0',
+                systemPort: 8200,
+            },
+            {
+                id: '192.168.1.50:5555',
+                name: 'Galaxy S24',
+                version: '14.0',
+                systemPort: 8201,
+            },
+        ];
+        expect(customDevices[0].id).toBe('emulator-5554');
+        expect(customDevices[0].avd).toBe('Pixel_7_Pro_API_34');
+        expect(customDevices[0].version).toBe('14.0');
+        expect(customDevices[0].systemPort).toBe(8200);
+        expect(customDevices[1].id).toBe('192.168.1.50:5555');
+        expect(customDevices[1].systemPort).toBe(8201);
+    });
+    it('supports array of IosDeviceTarget objects with id, name, version, udid, and wdaLocalPort', () => {
+        const customIosDevices = [
+            {
+                id: 'iphone-15-pro',
+                name: 'iPhone 15 Pro Simulator',
+                version: '17.0',
+                udid: 'auto',
+                wdaLocalPort: 8100,
+            },
+        ];
+        expect(customIosDevices[0].id).toBe('iphone-15-pro');
+        expect(customIosDevices[0].name).toBe('iPhone 15 Pro Simulator');
+        expect(customIosDevices[0].version).toBe('17.0');
+        expect(customIosDevices[0].udid).toBe('auto');
+        expect(customIosDevices[0].wdaLocalPort).toBe(8100);
+    });
+});

package/dist/mobile/device-pool.d.ts

@@ -0,0 +1,23 @@
+export interface DeviceInfo {
+    udid: string;
+    name: string;
+    platform: 'android' | 'ios';
+    state: 'device' | 'offline' | 'unauthorized' | 'booted';
+    model?: string;
+}
+export interface DeviceWorkerSlot {
+    index: number;
+    device: DeviceInfo;
+    ports: {
+        driverPort: number;
+        systemPort: number;
+        chromedriverPort: number;
+        mjpegPort: number;
+    };
+}
+export interface MobileTargetOptions {
+    target?: 'web' | 'android' | 'ios' | 'common' | 'mobile';
+    device?: string;
+    devices?: string[] | 'auto';
+    multiDevice?: boolean;
+}

package/dist/mobile/device-pool.js

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

package/dist/mobile/index.d.ts

@@ -0,0 +1 @@
+export * from './device-pool.js';

package/dist/mobile/index.js

@@ -0,0 +1 @@
+export * from './device-pool.js';

package/dist/refactor/__tests__/refactor-engine.test.d.ts

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