@testspectra/cli 1.1.11-rc.3 → 1.1.12

package/dist/generator/__tests__/type-generator.test.js

@@ -393,7 +393,7 @@ async function verifyZeroImport() {
         const featureLibDir = path.join(tmpDir, 'packages', 'features', 'auth');
         fs.mkdirSync(featureLibDir, { recursive: true });
         fs.writeFileSync(path.join(featureLibDir, 'project.json'), JSON.stringify({
-            name: '@tagsamurai/feature-auth',
+            name: '@example/feature-auth',
             projectType: 'library',
             sourceRoot: 'packages/features/auth',
             targets: {},
@@ -421,4 +421,18 @@ async function verifyZeroImport() {
         // Verify packages/features/auth is NOT in scopes
         expect(scopes.some((s) => s.dir === path.resolve(featureLibDir))).toBe(false);
     });
+    it('generates ambient types for non-JSON fixtures including images and PDF files', () => {
+        const fixDir = path.join(tmpDir, 'fixtures');
+        fs.mkdirSync(fixDir, { recursive: true });
+        fs.writeFileSync(path.join(fixDir, 'sampleImage.png'), 'fake-png-bytes');
+        fs.writeFileSync(path.join(fixDir, 'sampleDocument.pdf'), 'fake-pdf-bytes');
+        fs.writeFileSync(path.join(fixDir, 'dataset.csv'), 'id,name\n1,Alice');
+        fs.writeFileSync(path.join(fixDir, 'users.json'), JSON.stringify({ count: 1 }));
+        TypeGenerator.generateAll(tmpDir);
+        const fixturesDts = fs.readFileSync(path.join(tmpDir, '.testspectra', 'types', 'fixtures.d.ts'), 'utf-8');
+        expect(fixturesDts).toContain('readonly sampleImage: string;');
+        expect(fixturesDts).toContain('readonly sampleDocument: string;');
+        expect(fixturesDts).toContain('readonly dataset: string;');
+        expect(fixturesDts).toContain('readonly users: typeof import(');
+    });
 });

package/dist/generator/tsconfig-generator.js

@@ -260,6 +260,7 @@ export class TsConfigGenerator {
                 target: 'ES2022',
                 module: 'NodeNext',
                 moduleResolution: 'NodeNext',
+                jsx: 'react-jsx',
                 composite: true,
                 noEmit: true,
                 skipLibCheck: true,

package/dist/generator/type-generator.js

@@ -579,6 +579,8 @@ export class TypeGenerator {
                         scanFixtureDir(path.join(dir, entry.name));
                     }
                     else if (entry.isFile()) {
+                        if (entry.name.endsWith('.d.ts'))
+                            continue;
                         const parsed = path.parse(entry.name);
                         const varName = parsed.name.replace(/[^a-zA-Z0-9_$]/g, '_');
                         if (declaredFixtures.has(varName))

package/dist/index.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { addCommand } from './commands/add.js';
 import { demoCommand } from './commands/demo.js';
+import { DEFAULT_DEMO_PORT } from './utils/demo-server.js';
 import { devicesCommand } from './commands/devices.js';
 import { doctorCommand } from './commands/doctor.js';
 import { initCommand } from './commands/init.js';
@@ -54,8 +55,8 @@ Examples:
         .action(installCommand);
     program
         .command('demo')
-        .description('Launch the built-in TestSpectra Demo Web App server on localhost:5173')
-        .option('-p, --port <port>', 'Port to bind server (default: 5173)')
+        .description(`Launch the built-in TestSpectra Demo Web App server on localhost:${DEFAULT_DEMO_PORT}`)
+        .option('-p, --port <port>', `Port to bind server (default: ${DEFAULT_DEMO_PORT})`)
         .action(demoCommand);
     program
         .command('watch')
@@ -182,17 +183,23 @@ Examples:
         .option('--headless', 'Run in headless mode')
         .option('--no-headless', 'Run in headed mode')
         .option('--headed', 'Run browser in visible GUI mode (alias for --no-headless)')
+        .option('--no-dev-server', 'Skip auto-starting local development servers')
+        .option('--no-dev-servers', 'Skip auto-starting local development servers (alias)')
+        .option('--skip-dev-servers', 'Skip auto-starting local development servers')
         .option('--step-delay <ms>', 'Delay between consecutive actions and commands in milliseconds (slow motion)')
         .option('--delay <ms>', 'Alias for --step-delay')
+        .option('--video', 'Enable failure video recording (default: true)')
+        .option('--no-video', 'Disable video recording completely')
         .option('--failed [targets]', 'Re-run failed tests from previous run (accepts comma-separated test IDs or spec paths)')
         .option('-c, --concurrency <number>', 'Maximum parallel worker concurrency (auto-detected if omitted)')
+        .option('--debug', 'Run in debug mode (headed browser, single worker, inspector attached for breakpoints)')
+        .option('--inspect-port <port>', 'Bun inspector port for debug mode (default: 9229)')
         .option('-w, --workdir <dir>', 'Custom app data / temp workdir')
         .option('-o, --output <path>', 'Custom test report JSON output path')
         .action(runCommand);
     program
         .command('test')
-        .description('Run React component tests via @testspectra/react')
-        .option('-r, --runner <engine>', 'Component test runner engine: spectra (default, native CDP) or vitest (Playwright browser mode)', 'spectra')
+        .description('Run React component tests via the native CDP engine')
         .option('-w, --cwd <dir>', 'Custom workspace directory')
         .option('-s, --spec <path>', 'Spec file path (or substring filter) to execute')
         .option('--headless', 'Run in headless mode (default)')

package/dist/lifecycle/__tests__/lifecycle-engine.test.js

@@ -0,0 +1,290 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { discoverGlobalHooks, discoverSuiteHooks } from '../hook-discovery.js';
+import { LifecycleDispatcher, HookExecutionError } from '../hook-dispatcher.js';
+import { calculateWorkerCount, groupSpecs } from '../parallel-grouping.js';
+describe('Core Lifecycle Execution Engine (docs/v2/cli/lifecycle-execution-engine.md)', () => {
+    let tmpDir;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'testspectra-lifecycle-test-'));
+    });
+    afterEach(() => {
+        try {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch { }
+    });
+    describe('Hook Discovery', () => {
+        it('discovers global-hooks and filters by platform hierarchy', () => {
+            const gBefore = path.join(tmpDir, 'global-hooks', 'before');
+            const gAfter = path.join(tmpDir, 'global-hooks', 'after');
+            fs.mkdirSync(gBefore, { recursive: true });
+            fs.mkdirSync(gAfter, { recursive: true });
+            fs.writeFileSync(path.join(gBefore, 'web.hook.ts'), 'export default async () => {}');
+            fs.writeFileSync(path.join(gBefore, 'mobile.hook.ts'), 'export default async () => {}');
+            fs.writeFileSync(path.join(gBefore, 'common.hook.ts'), 'export default async () => {}');
+            fs.writeFileSync(path.join(gAfter, 'web.hook.ts'), 'export default async () => {}');
+            const webGlobal = discoverGlobalHooks(tmpDir, 'web');
+            expect(webGlobal.before.some((h) => h.endsWith('web.hook.ts'))).toBe(true);
+            expect(webGlobal.before.some((h) => h.endsWith('common.hook.ts'))).toBe(true);
+            expect(webGlobal.before.some((h) => h.endsWith('mobile.hook.ts'))).toBe(false);
+            const mobileGlobal = discoverGlobalHooks(tmpDir, 'mobile');
+            expect(mobileGlobal.before.some((h) => h.endsWith('mobile.hook.ts'))).toBe(true);
+            expect(mobileGlobal.before.some((h) => h.endsWith('common.hook.ts'))).toBe(true);
+            expect(mobileGlobal.before.some((h) => h.endsWith('web.hook.ts'))).toBe(false);
+        });
+        it('discovers suite hooks (before, beforeEach, afterEach, after)', () => {
+            const suiteDir = path.join(tmpDir, 'specs', 'Auth');
+            for (const hookType of ['before', 'beforeEach', 'afterEach', 'after']) {
+                const hDir = path.join(suiteDir, 'hooks', hookType);
+                fs.mkdirSync(hDir, { recursive: true });
+                fs.writeFileSync(path.join(hDir, 'web.hook.ts'), 'export default async () => {}');
+            }
+            const suiteHooks = discoverSuiteHooks(suiteDir, 'web');
+            expect(suiteHooks.before.length).toBe(1);
+            expect(suiteHooks.beforeEach.length).toBe(1);
+            expect(suiteHooks.afterEach.length).toBe(1);
+            expect(suiteHooks.after.length).toBe(1);
+        });
+    });
+    describe('Lifecycle Dispatcher & Execution Flow', () => {
+        it('single run executes suite hooks without triggering global hooks', async () => {
+            const executionOrder = [];
+            const globalBeforeFn = vi.fn(async () => {
+                executionOrder.push('globalBefore');
+            });
+            const globalAfterFn = vi.fn(async () => {
+                executionOrder.push('globalAfter');
+            });
+            const suiteHooks = {
+                before: [
+                    async () => {
+                        executionOrder.push('suiteBefore');
+                    },
+                ],
+                beforeEach: [
+                    async () => {
+                        executionOrder.push('beforeEach');
+                    },
+                ],
+                afterEach: [
+                    async () => {
+                        executionOrder.push('afterEach');
+                    },
+                ],
+                after: [
+                    async () => {
+                        executionOrder.push('suiteAfter');
+                    },
+                ],
+            };
+            const dispatcher = new LifecycleDispatcher('single', {
+                before: [globalBeforeFn],
+                after: [globalAfterFn],
+            });
+            // Single run bypasses global before & global after
+            await dispatcher.runGlobalBefore();
+            expect(globalBeforeFn).not.toHaveBeenCalled();
+            const result = await dispatcher.executeSuite('AuthSuite', suiteHooks, [
+                {
+                    id: 'TC-01',
+                    title: 'Valid Login',
+                    fn: async () => {
+                        executionOrder.push('testBody');
+                    },
+                },
+            ]);
+            await dispatcher.runGlobalAfter();
+            expect(globalAfterFn).not.toHaveBeenCalled();
+            expect(result.status).toBe('PASSED');
+            expect(executionOrder).toEqual(['suiteBefore', 'beforeEach', 'testBody', 'afterEach', 'suiteAfter']);
+        });
+        it('global batch run executes global-hooks/before once at start and global-hooks/after once at finish', async () => {
+            const executionOrder = [];
+            const globalBeforeFn = vi.fn(async () => {
+                executionOrder.push('globalBefore');
+            });
+            const globalAfterFn = vi.fn(async () => {
+                executionOrder.push('globalAfter');
+            });
+            const dispatcher = new LifecycleDispatcher('global', {
+                before: [globalBeforeFn],
+                after: [globalAfterFn],
+            });
+            await dispatcher.runGlobalBefore();
+            expect(globalBeforeFn).toHaveBeenCalledTimes(1);
+            const suiteHooks = {
+                before: [
+                    async () => {
+                        executionOrder.push('suiteBefore');
+                    },
+                ],
+                beforeEach: [
+                    async () => {
+                        executionOrder.push('beforeEach');
+                    },
+                ],
+                afterEach: [
+                    async () => {
+                        executionOrder.push('afterEach');
+                    },
+                ],
+                after: [
+                    async () => {
+                        executionOrder.push('suiteAfter');
+                    },
+                ],
+            };
+            const result = await dispatcher.executeSuite('AuthSuite', suiteHooks, [
+                {
+                    id: 'TC-01',
+                    title: 'Test 1',
+                    fn: async () => {
+                        executionOrder.push('tc1');
+                    },
+                },
+                {
+                    id: 'TC-02',
+                    title: 'Test 2',
+                    fn: async () => {
+                        executionOrder.push('tc2');
+                    },
+                },
+            ]);
+            await dispatcher.runGlobalAfter();
+            expect(globalAfterFn).toHaveBeenCalledTimes(1);
+            expect(result.status).toBe('PASSED');
+            expect(executionOrder).toEqual([
+                'globalBefore',
+                'suiteBefore',
+                'beforeEach',
+                'tc1',
+                'afterEach',
+                'beforeEach',
+                'tc2',
+                'afterEach',
+                'suiteAfter',
+                'globalAfter',
+            ]);
+        });
+        it('when beforeEach fails, test body is skipped, afterEach is guaranteed to execute, and test is marked as ERROR', async () => {
+            const testBodyFn = vi.fn();
+            let afterEachRan = false;
+            const suiteHooks = {
+                before: [],
+                beforeEach: [
+                    async () => {
+                        throw new Error('Database connection failed in beforeEach');
+                    },
+                ],
+                afterEach: [
+                    async () => {
+                        afterEachRan = true;
+                    },
+                ],
+                after: [],
+            };
+            const dispatcher = new LifecycleDispatcher('single');
+            const result = await dispatcher.executeSuite('FailingBeforeEachSuite', suiteHooks, [
+                {
+                    id: 'TC-FAIL-01',
+                    title: 'Should be skipped',
+                    fn: testBodyFn,
+                },
+            ]);
+            expect(testBodyFn).not.toHaveBeenCalled();
+            expect(afterEachRan).toBe(true);
+            expect(result.results[0].status).toBe('ERROR');
+            expect(result.results[0].error?.message).toContain('Database connection failed in beforeEach');
+            expect(result.status).toBe('ERROR');
+        });
+        it('when afterEach fails, test transitions to ERROR status', async () => {
+            const suiteHooks = {
+                before: [],
+                beforeEach: [],
+                afterEach: [
+                    async () => {
+                        throw new Error('Teardown resource leak in afterEach');
+                    },
+                ],
+                after: [],
+            };
+            const dispatcher = new LifecycleDispatcher('single');
+            const result = await dispatcher.executeSuite('TeardownFailSuite', suiteHooks, [
+                {
+                    id: 'TC-01',
+                    title: 'Passing Body but failing afterEach',
+                    fn: async () => {
+                        // Passing body
+                    },
+                },
+            ]);
+            expect(result.results[0].status).toBe('ERROR');
+            expect(result.results[0].error?.message).toContain('Teardown resource leak in afterEach');
+            expect(result.status).toBe('ERROR');
+        });
+        it('when global-hooks/before fails, throws HookExecutionError immediately', async () => {
+            const dispatcher = new LifecycleDispatcher('global', {
+                before: [
+                    async () => {
+                        throw new Error('Global health check failed');
+                    },
+                ],
+                after: [],
+            });
+            await expect(dispatcher.runGlobalBefore()).rejects.toThrow(HookExecutionError);
+            await expect(dispatcher.runGlobalBefore()).rejects.toThrow('Global health check failed');
+        });
+    });
+    describe('Parallel Spec Grouping & Dynamic Worker Sizing', () => {
+        it('prioritizes explicit user concurrency flag over auto-calculation', () => {
+            const targets = Array.from({ length: 10 }, () => 'spec.ts');
+            expect(calculateWorkerCount(targets, { userConcurrency: 4 })).toBe(4);
+            // Clamps to item count if items < userConcurrency
+            expect(calculateWorkerCount(['only-one.ts'], { userConcurrency: 4 })).toBe(1);
+        });
+        it('enforces low-CPU safety ratio based on container/host CPU quota', () => {
+            const targets = Array.from({ length: 10 }, () => 'spec.ts');
+            const highRam = 16 * 1024 * 1024 * 1024; // 16 GB
+            // CPU <= 2 (e.g. 2-vCPU standard CI runner): clamped to 1 worker
+            expect(calculateWorkerCount(targets, { cpuQuotaOverride: 1, memoryBytesOverride: highRam })).toBe(1);
+            expect(calculateWorkerCount(targets, { cpuQuotaOverride: 2, memoryBytesOverride: highRam })).toBe(1);
+            // CPU 3 - 4: allocates 2 workers
+            expect(calculateWorkerCount(targets, { cpuQuotaOverride: 3, memoryBytesOverride: highRam })).toBe(2);
+            expect(calculateWorkerCount(targets, { cpuQuotaOverride: 4, memoryBytesOverride: highRam })).toBe(2);
+            // CPU > 4: allocates (cpu - 2) capped at maxWorkersCap (default 6)
+            expect(calculateWorkerCount(targets, { cpuQuotaOverride: 6, memoryBytesOverride: highRam })).toBe(4);
+            expect(calculateWorkerCount(targets, { cpuQuotaOverride: 8, memoryBytesOverride: highRam })).toBe(6);
+            expect(calculateWorkerCount(targets, { cpuQuotaOverride: 64, memoryBytesOverride: highRam })).toBe(6);
+        });
+        it('enforces memory-aware guard to prevent OOM kills during browser automation', () => {
+            const targets = Array.from({ length: 10 }, () => 'spec.ts');
+            const highCpu = 16;
+            // 500 MB RAM budget -> allows at most 1 worker (~600MB budget per browser)
+            expect(calculateWorkerCount(targets, { cpuQuotaOverride: highCpu, memoryBytesOverride: 500 * 1024 * 1024 })).toBe(1);
+            // 1.5 GB RAM budget -> allows 2 workers
+            expect(calculateWorkerCount(targets, { cpuQuotaOverride: highCpu, memoryBytesOverride: 1500 * 1024 * 1024 })).toBe(2);
+            // 2.5 GB RAM budget -> allows 4 workers
+            expect(calculateWorkerCount(targets, { cpuQuotaOverride: highCpu, memoryBytesOverride: 2500 * 1024 * 1024 })).toBe(4);
+        });
+        it('groups specs by suite directory in nested array format when mode is "suite"', () => {
+            const specs = [
+                'specs/Auth/TC-001/web.test.ts',
+                'specs/Auth/TC-002/web.test.ts',
+                'specs/Cart/TC-010/web.test.ts',
+                'specs/Cart/TC-011/web.test.ts',
+            ];
+            const grouped = groupSpecs(specs, 'suite');
+            expect(grouped.length).toBe(2);
+            expect(grouped[0]).toEqual(['specs/Auth/TC-001/web.test.ts', 'specs/Auth/TC-002/web.test.ts']);
+            expect(grouped[1]).toEqual(['specs/Cart/TC-010/web.test.ts', 'specs/Cart/TC-011/web.test.ts']);
+        });
+        it('flattens specs when mode is "testcase"', () => {
+            const specs = ['specs/Auth/TC-001/web.test.ts', 'specs/Auth/TC-002/web.test.ts', 'specs/Cart/TC-010/web.test.ts'];
+            const flat = groupSpecs(specs, 'testcase');
+            expect(flat).toEqual(specs);
+        });
+    });
+});

package/dist/lifecycle/hook-discovery.d.ts

@@ -0,0 +1,24 @@
+import { PlatformTarget } from '../generator/type-generator.js';
+export type HookEntry = string | (() => Promise<void> | void);
+export interface DiscoveredSuiteHooks {
+    before: string[];
+    beforeEach: string[];
+    afterEach: string[];
+    after: string[];
+}
+export interface DiscoveredGlobalHooks {
+    before: string[];
+    after: string[];
+}
+export interface SuiteHooks {
+    before: HookEntry[];
+    beforeEach: HookEntry[];
+    afterEach: HookEntry[];
+    after: HookEntry[];
+}
+export interface GlobalHooks {
+    before: HookEntry[];
+    after: HookEntry[];
+}
+export declare function discoverGlobalHooks(cwd: string, platform?: PlatformTarget): DiscoveredGlobalHooks;
+export declare function discoverSuiteHooks(suiteDir: string, platform?: PlatformTarget): DiscoveredSuiteHooks;

package/dist/lifecycle/hook-discovery.js

@@ -0,0 +1,60 @@
+import fs from 'fs';
+import path from 'path';
+import { PLATFORM_HIERARCHY } from '../generator/type-generator.js';
+function resolveHookFilesForType(dir, platform = 'web') {
+    if (!fs.existsSync(dir))
+        return [];
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    const hierarchy = PLATFORM_HIERARCHY[platform] || ['common'];
+    const matched = [];
+    // Group files by base name if applicable or collect directly
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.hook.ts'))
+            continue;
+        const parts = entry.name.split('.');
+        // Formats:
+        // 1. web.hook.ts -> parts = ['web', 'hook', 'ts']
+        // 2. auth.web.hook.ts -> parts = ['auth', 'web', 'hook', 'ts']
+        // 3. auth.hook.ts -> parts = ['auth', 'hook', 'ts']
+        let filePlatform = 'common';
+        if (parts.length === 3) {
+            filePlatform = parts[0];
+        }
+        else if (parts.length >= 4) {
+            filePlatform = parts[parts.length - 3];
+        }
+        if (hierarchy.includes(filePlatform) || filePlatform === 'common') {
+            matched.push(path.join(dir, entry.name));
+        }
+    }
+    // Sort by hierarchy priority
+    matched.sort((a, b) => {
+        const getPriority = (filePath) => {
+            const base = path.basename(filePath);
+            for (let i = 0; i < hierarchy.length; i++) {
+                if (base.includes(`.${hierarchy[i]}.`) || base.startsWith(`${hierarchy[i]}.`)) {
+                    return i;
+                }
+            }
+            return hierarchy.length;
+        };
+        return getPriority(a) - getPriority(b);
+    });
+    return matched;
+}
+export function discoverGlobalHooks(cwd, platform = 'web') {
+    const globalHooksDir = path.join(cwd, 'global-hooks');
+    return {
+        before: resolveHookFilesForType(path.join(globalHooksDir, 'before'), platform),
+        after: resolveHookFilesForType(path.join(globalHooksDir, 'after'), platform),
+    };
+}
+export function discoverSuiteHooks(suiteDir, platform = 'web') {
+    const hooksDir = path.join(suiteDir, 'hooks');
+    return {
+        before: resolveHookFilesForType(path.join(hooksDir, 'before'), platform),
+        beforeEach: resolveHookFilesForType(path.join(hooksDir, 'beforeEach'), platform),
+        afterEach: resolveHookFilesForType(path.join(hooksDir, 'afterEach'), platform),
+        after: resolveHookFilesForType(path.join(hooksDir, 'after'), platform),
+    };
+}

package/dist/lifecycle/hook-dispatcher.d.ts

@@ -0,0 +1,34 @@
+import { SuiteHooks, GlobalHooks } from './hook-discovery.js';
+export type TestCaseStatus = 'PASSED' | 'FAILED' | 'SKIPPED' | 'ERROR';
+export interface TestCaseResult {
+    id: string;
+    title: string;
+    status: TestCaseStatus;
+    error?: Error;
+    durationMs: number;
+}
+export interface SuiteExecutionResult {
+    suiteName: string;
+    results: TestCaseResult[];
+    status: 'PASSED' | 'FAILED' | 'ERROR';
+    error?: Error;
+}
+export type HookFn = () => Promise<void> | void;
+export declare class HookExecutionError extends Error {
+    phase: 'before' | 'beforeEach' | 'afterEach' | 'after' | 'globalBefore' | 'globalAfter';
+    originalError: any;
+    constructor(phase: 'before' | 'beforeEach' | 'afterEach' | 'after' | 'globalBefore' | 'globalAfter', originalError: any);
+}
+export declare function runHook(hookPathOrFn: string | HookFn, timeoutMs?: number): Promise<void>;
+export declare class LifecycleDispatcher {
+    mode: 'single' | 'global';
+    globalHooks: GlobalHooks;
+    constructor(mode?: 'single' | 'global', globalHooks?: GlobalHooks);
+    runGlobalBefore(): Promise<void>;
+    runGlobalAfter(): Promise<void>;
+    executeSuite(suiteName: string, suiteHooks: SuiteHooks, testCases: Array<{
+        id: string;
+        title: string;
+        fn: () => Promise<void>;
+    }>): Promise<SuiteExecutionResult>;
+}