@testspectra/cli 1.1.11-rc.3 → 1.1.12

package/dist/runner/reporter.js

@@ -1,169 +1,14 @@
+import { formatAction, formatAssertion, parseAndFormat, SemanticReporter, stripAnsi, } from '@testspectra/reporter';
 import chalk from 'chalk';
-import { formatAction, formatAssertion } from '../reporter/semantic-formatter.js';
-function stripAnsi(str) {
-    return str.replace(/\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, '');
-}
-function mapActionArgs(key, arr) {
-    if (!Array.isArray(arr)) {
-        return typeof arr === 'object' && arr !== null ? arr : {};
-    }
-    switch (key) {
-        case 'type':
-            return { text: arr[0] };
-        case 'select':
-        case 'selectOption':
-            return { option: arr[0] };
-        case 'dragDrop':
-            return { dest: arr[0] };
-        case 'longPress':
-            return { durationMs: arr[0] };
-        case 'navigate':
-            return { url: arr[0] };
-        case 'setCookies':
-            return { url: arr[0] };
-        case 'setViewport':
-            return { width: arr[0], height: arr[1] };
-        case 'wait':
-            return { ms: arr[0] };
-        case 'pressKey':
-            return { key: arr[0] };
-        case 'scroll':
-            return { direction: arr[0], pixels: arr[1] };
-        case 'swipe':
-            return { direction: arr[0], distance: arr[1] };
-        case 'intercept':
-            return { method: arr[0], url: arr[1] };
-        default:
-            return {};
-    }
-}
-function mapAssertionArgs(key, arr) {
-    if (!Array.isArray(arr)) {
-        return typeof arr === 'object' && arr !== null ? arr : { expected: arr };
-    }
-    if (key === 'have.attr' || key === 'not.have.attr') {
-        return arr.length >= 2 ? { name: arr[0], value: arr[1], expected: arr[0] } : { name: arr[0], expected: arr[0] };
-    }
-    if (key === 'have.css' || key === 'not.have.css') {
-        return { name: arr[0], property: arr[0], value: arr[1], expected: arr[0] };
-    }
-    if (arr.length >= 2) {
-        return { name: arr[0], value: arr[1], expected: arr[0] };
-    }
-    return {
-        expected: arr[0],
-        name: arr[0],
-        text: arr[0],
-        value: arr[0],
-        title: arr[0],
-        url: arr[0],
-        length: arr[0],
-        min: arr[0],
-        max: arr[0],
-    };
-}
-function parseAndFormat(cmdText) {
-    try {
-        const payload = JSON.parse(cmdText);
-        // Passed through as-is (not pre-flattened to a bare string here) — `formatAction`/
-        // `formatAssertion` already do the same `.selector`/`.name`/`.target` fallback lookup
-        // themselves, and only the raw object retains `.parent` for a scoped (`element.get()`/
-        // `.getAll()`-chained) target, which they need to render the "within" phrasing.
-        const target = payload.target;
-        if (payload.type === 'action') {
-            return formatAction(payload.key, target, mapActionArgs(payload.key, payload.args || []));
-        }
-        else if (payload.type === 'assertion' || payload.type === 'browser') {
-            return formatAssertion(payload.key, target, mapAssertionArgs(payload.key, payload.args || []));
-        }
-        // Native Orchestrator payload format ({ test, action, selector, target, ... })
-        if (payload.action) {
-            const action = payload.action;
-            const t = payload.selector || payload.target;
-            switch (action) {
-                case 'navigate':
-                    return formatAction('navigate', undefined, {
-                        url: t || payload.url || payload.value || 'http://localhost:5173',
-                    });
-                case 'click':
-                    return formatAction('click', t);
-                case 'double_click':
-                case 'doubleClick':
-                    return formatAction('doubleClick', t);
-                case 'right_click':
-                case 'rightClick':
-                    return formatAction('rightClick', t);
-                case 'type':
-                case 'type_text':
-                case 'set_value':
-                    return formatAction('type', t, { text: payload.text || payload.value });
-                case 'clear':
-                    return formatAction('clear', t);
-                case 'hover':
-                    return formatAction('hover', t);
-                case 'scroll_into_view':
-                case 'scrollIntoView':
-                    return formatAction('scrollIntoView', t);
-                case 'should_be_visible':
-                    return formatAssertion('be.visible', t);
-                case 'should_not_be_visible':
-                    return formatAssertion('not.be.visible', t);
-                case 'should_exist':
-                    return formatAssertion('exist', t);
-                case 'should_not_exist':
-                    return formatAssertion('not.exist', t);
-                case 'should_be_enabled':
-                    return formatAssertion('be.enabled', t);
-                case 'should_be_disabled':
-                    return formatAssertion('be.disabled', t);
-                case 'should_be_clickable':
-                    return formatAssertion('be.clickable', t);
-                case 'should_have_text':
-                    return formatAssertion('have.text', t, { expected: payload.expected || payload.text || payload.value });
-                case 'should_contain_text':
-                    return formatAssertion('contain.text', t, {
-                        expected: payload.expected || payload.text || payload.value,
-                    });
-                case 'should_have_value':
-                    return formatAssertion('have.value', t, { expected: payload.expected || payload.value });
-                case 'should_contain_value':
-                    return formatAssertion('contain.value', t, { expected: payload.expected || payload.value });
-                case 'should_have_length':
-                    return formatAssertion('have.length', t, {
-                        expected: payload.expected || payload.length || payload.value,
-                    });
-                case 'should_have_title':
-                    return formatAssertion('have.title', undefined, {
-                        expected: payload.expected || payload.value || t || 'TestSpectra',
-                    });
-                case 'should_be_empty':
-                    return formatAssertion('be.empty', t);
-                case 'should_not_be_empty':
-                    return formatAssertion('not.be.empty', t);
-                default:
-                    return `Execute step "${action}" on ${t || 'target'}`;
-            }
-        }
-        return cmdText;
-    }
-    catch {
-        return cmdText;
-    }
-}
-export class Reporter {
-    logs = [];
-    networkEvents = [];
-    pendingTests = new Map();
-    workerToTest = new Map();
-    pendingErrorMsg;
-    passedCount = 0;
-    failedCount = 0;
+export { formatAction, formatAssertion, parseAndFormat, SemanticReporter, stripAnsi, };
+export class Reporter extends SemanticReporter {
     isInteractive;
     lastRenderedLines = 0;
     spinnerFrames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
     spinnerIndex = 0;
     spinnerTimer = null;
-    constructor() {
+    constructor(options = {}) {
+        super(options);
         this.isInteractive = Boolean(process.stdout.isTTY && !process.env.CI && process.env.NODE_ENV !== 'test' && !process.env.VITEST);
         if (this.isInteractive) {
             this.spinnerTimer = setInterval(() => {
@@ -211,23 +56,16 @@ export class Reporter {
         }
         this.lastRenderedLines = linesCount;
     }
-    resolveTestCase(testTitle, workerId) {
-        if (testTitle && this.pendingTests.has(testTitle)) {
-            return this.pendingTests.get(testTitle);
-        }
-        if (workerId !== undefined && this.workerToTest.has(workerId)) {
-            const title = this.workerToTest.get(workerId);
-            if (title && this.pendingTests.has(title)) {
-                return this.pendingTests.get(title);
+    addLog(input) {
+        const log = typeof input === 'string'
+            ? {
+                timestamp: new Date().toISOString(),
+                level: 'INFO',
+                message: input,
             }
-        }
-        if (this.pendingTests.size === 1) {
-            return this.pendingTests.values().next().value;
-        }
-        return Array.from(this.pendingTests.values()).pop();
-    }
-    addLog(log) {
+            : input;
         this.logs.push(log);
+        this.options.onLog?.(log);
         const raw = stripAnsi(log.message || '').trim();
         if (!raw)
             return;
@@ -284,6 +122,7 @@ export class Reporter {
                 this.workerToTest.set(workerId, title);
             }
             this.renderActiveSlots();
+            this.options.onTestStart?.(pending);
             return;
         }
         // 2. Step in-progress / start
@@ -303,6 +142,7 @@ export class Reporter {
                 testCase.currentStep = formatted;
                 this.renderActiveSlots();
             }
+            this.options.onStepStart?.(testTitle || testCase?.title || '', formatted, workerId ?? testCase?.workerId);
             return;
         }
         // 3. Step passed -> record step to matching test case
@@ -321,11 +161,13 @@ export class Reporter {
             }
             catch { }
             const testCase = this.resolveTestCase(testTitle, workerId);
+            const step = { text: formatted, duration, passed: true };
             if (testCase) {
-                testCase.steps.push({ text: formatted, duration, passed: true });
+                testCase.steps.push(step);
                 testCase.currentStep = formatted;
                 this.renderActiveSlots();
             }
+            this.options.onStepPass?.(testTitle || testCase?.title || '', step, workerId ?? testCase?.workerId);
             return;
         }
         // 4. Step failed -> record failed step to matching test case
@@ -344,11 +186,28 @@ export class Reporter {
             }
             catch { }
             const testCase = this.resolveTestCase(testTitle, workerId);
+            const step = { text: formatted, duration, passed: false };
             if (testCase) {
-                testCase.steps.push({ text: formatted, duration, passed: false });
+                testCase.steps.push(step);
                 testCase.currentStep = formatted;
                 this.renderActiveSlots();
             }
+            this.options.onStepFail?.(testTitle || testCase?.title || '', step, workerId ?? testCase?.workerId);
+            return;
+        }
+        // 4.5 Video capture notification
+        if (raw.startsWith('[TESTSPECTRA_VIDEO]')) {
+            const content = raw.replace('[TESTSPECTRA_VIDEO]', '').trim();
+            try {
+                const payload = JSON.parse(content);
+                if (payload.videoPath) {
+                    const testCase = this.resolveTestCase(payload.id);
+                    if (testCase) {
+                        testCase.videoPath = payload.videoPath;
+                    }
+                }
+            }
+            catch { }
             return;
         }
         // 5. Test error detail
@@ -361,6 +220,7 @@ export class Reporter {
             else {
                 this.pendingErrorMsg = this.pendingErrorMsg ? `${this.pendingErrorMsg}\n${err}` : err;
             }
+            this.options.onTestError?.(err, latest?.title, latest?.workerId);
             return;
         }
         // 6. Test passed completely -> flush atomic test block to permanent history
@@ -384,6 +244,7 @@ export class Reporter {
             }
             console.log('');
             this.renderActiveSlots();
+            this.options.onTestPass?.({ title, duration, steps, workerId });
             return;
         }
         // 7. Test failed completely -> flush atomic failed test block to permanent history
@@ -397,6 +258,7 @@ export class Reporter {
             const steps = testCase?.steps || [];
             const errorMsg = testCase?.errorMsg || this.pendingErrorMsg;
             this.pendingErrorMsg = undefined;
+            const videoPath = testCase?.videoPath;
             const workerId = testCase?.workerId;
             this.pendingTests.delete(title);
             if (workerId !== undefined) {
@@ -419,17 +281,21 @@ export class Reporter {
                     console.log(`      \x1b[38;2;248;113;113m${errLines[i]}\x1b[0m`);
                 }
             }
+            if (videoPath) {
+                console.log(`    \x1b[38;2;251;191;36m↳ Video:\x1b[0m \x1b[38;2;251;191;36m${videoPath}\x1b[0m`);
+            }
             console.log('');
             this.renderActiveSlots();
+            this.options.onTestFail?.({ title, duration, steps, errorMsg, workerId });
             return;
         }
         // Generic errors & warnings
-        if (log.level === 'ERROR' || log.level === 'FAILED') {
+        if (log.level === 'ERROR') {
             this.clearActiveSlots();
             console.log(`  \x1b[38;2;248;113;113m${log.message}\x1b[0m`);
             this.renderActiveSlots();
         }
-        else if (log.level === 'WARN' || log.level === 'WARNING') {
+        else if (log.level === 'WARNING') {
             this.clearActiveSlots();
             console.log(`  \x1b[38;2;251;191;36m${log.message}\x1b[0m`);
             this.renderActiveSlots();
@@ -437,6 +303,7 @@ export class Reporter {
     }
     addNetwork(res) {
         this.networkEvents.push(res);
+        this.options.onNetwork?.(res);
     }
     getLogs() {
         return this.logs;

package/dist/utils/__tests__/demo-state.test.d.ts

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

package/dist/utils/__tests__/demo-state.test.js

@@ -0,0 +1,96 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import http from 'http';
+import { DemoStateManager } from '../demo-state.js';
+describe('DemoStateManager (cli/src/utils/demo-state.ts)', () => {
+    let tmpDir;
+    let testServer = null;
+    let testPort = 0;
+    beforeAll(async () => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'spectra-demo-state-test-'));
+        fs.mkdirSync(path.join(tmpDir, '.testspectra'), { recursive: true });
+        // Start a dummy HTTP server simulating a live demo web app
+        await new Promise((resolve) => {
+            testServer = http.createServer((_req, res) => {
+                res.writeHead(200, {
+                    'Content-Type': 'text/html',
+                    'X-TestSpectra-Demo': 'true',
+                });
+                res.end('<div id="app"></div>');
+            });
+            testServer.listen(0, '127.0.0.1', () => {
+                const addr = testServer?.address();
+                testPort = typeof addr === 'object' && addr !== null ? addr.port : 0;
+                resolve();
+            });
+        });
+    });
+    afterAll(async () => {
+        if (testServer) {
+            await new Promise((resolve) => testServer?.close(() => resolve()));
+        }
+        if (fs.existsSync(tmpDir)) {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
+    it('saves and removes demo server state in the target project dir', () => {
+        const state = {
+            pid: process.pid,
+            url: `http://127.0.0.1:${testPort}`,
+            port: testPort,
+            apiUrl: 'http://127.0.0.1:5200',
+            apiPort: 5200,
+            startedAt: Date.now(),
+        };
+        DemoStateManager.saveState(state, tmpDir);
+        const stateFilePath = path.join(tmpDir, '.testspectra', 'demo-server.json');
+        expect(fs.existsSync(stateFilePath)).toBe(true);
+        const saved = JSON.parse(fs.readFileSync(stateFilePath, 'utf-8'));
+        expect(saved.url).toBe(`http://127.0.0.1:${testPort}`);
+        expect(saved.port).toBe(testPort);
+        DemoStateManager.removeState(tmpDir);
+        expect(fs.existsSync(stateFilePath)).toBe(false);
+    });
+    it('probeServer returns true for an active responsive HTTP server', async () => {
+        const isLive = await DemoStateManager.probeServer(`http://127.0.0.1:${testPort}`);
+        expect(isLive).toBe(true);
+    });
+    it('probeServer returns false for an inactive/closed port', async () => {
+        // 65534 is unlikely to be listening
+        const isLive = await DemoStateManager.probeServer('http://127.0.0.1:65534', 200);
+        expect(isLive).toBe(false);
+    });
+    it('getActiveDemoServer returns the state when the server is alive', async () => {
+        const state = {
+            pid: process.pid,
+            url: `http://127.0.0.1:${testPort}`,
+            port: testPort,
+            apiUrl: 'http://127.0.0.1:5200',
+            apiPort: 5200,
+            startedAt: Date.now(),
+        };
+        DemoStateManager.saveState(state, tmpDir);
+        const active = await DemoStateManager.getActiveDemoServer(tmpDir);
+        expect(active).not.toBeNull();
+        expect(active?.url).toBe(`http://127.0.0.1:${testPort}`);
+        expect(active?.port).toBe(testPort);
+        DemoStateManager.removeState(tmpDir);
+    });
+    it('getActiveDemoServer cleans up stale state file and returns null when server is not running', async () => {
+        const state = {
+            pid: 99999999, // Dead PID
+            url: 'http://127.0.0.1:65533', // Closed port
+            port: 65533,
+            startedAt: Date.now(),
+        };
+        DemoStateManager.saveState(state, tmpDir);
+        const stateFilePath = path.join(tmpDir, '.testspectra', 'demo-server.json');
+        expect(fs.existsSync(stateFilePath)).toBe(true);
+        const active = await DemoStateManager.getActiveDemoServer(tmpDir);
+        expect(active).toBeNull();
+        // Stale file should be cleaned up automatically
+        expect(fs.existsSync(stateFilePath)).toBe(false);
+    });
+});

package/dist/utils/api-server.d.ts

@@ -1,4 +1,4 @@
-/** Port the self-hosted demo API server listens on (separate from the demo web app's 5173). */
+/** Port the self-hosted demo API server listens on (separate from the demo web app's 5180). */
 export declare const DEMO_API_PORT = 5200;
 /**
  * Standalone self-hosted REST API server for the demo apps, kept separate from `DemoServer` (the

package/dist/utils/api-server.js

@@ -1,5 +1,5 @@
 import http from 'http';
-/** Port the self-hosted demo API server listens on (separate from the demo web app's 5173). */
+/** Port the self-hosted demo API server listens on (separate from the demo web app's 5180). */
 export const DEMO_API_PORT = 5200;
 // Self-hosted dummy REST data for the demo app's API sections — keeps the ApiInterception and
 // ApiSeeding suites fully offline/deterministic instead of depending on an external service
@@ -74,7 +74,11 @@ export class DemoApiServer {
                     reject(err);
                 }
             });
-            this.server.listen(this.port, '0.0.0.0', () => {
+            // Bind dual-stack (no host) rather than IPv4-only `0.0.0.0`: an IPv4-only bind silently
+            // coexists with an IPv6-localhost squatter on the same port, so a conflict would go
+            // undetected and clients resolving `localhost` to `::1` would hit the foreign server.
+            // See DemoServer for the full explanation.
+            this.server.listen(this.port, () => {
                 const addr = this.server?.address();
                 const actualPort = typeof addr === 'object' && addr !== null ? addr.port : this.port;
                 resolve({ url: `http://localhost:${actualPort}`, port: actualPort });
@@ -82,7 +86,7 @@ export class DemoApiServer {
         });
     }
     handleApi(req, res, pathname) {
-        // The demo web app (port 5173) calls this server (port 5200) cross-origin. A wildcard origin
+        // The demo web app (port 5180) calls this server (port 5200) cross-origin. A wildcard origin
         // can't be combined with credentialed requests (Access-Control-Allow-Credentials), which
         // /api/me below needs to receive the session cookie seeded via Spectra.browser.setCookies() —
         // reflect the actual request Origin instead so both credentialed and simple requests work.

package/dist/utils/demo-server.d.ts

@@ -1,3 +1,5 @@
+/** Default static port for the demo web app (distinct from Vite's default 5173 to avoid collisions). */
+export declare const DEFAULT_DEMO_PORT = 5180;
 /**
  * Static file server for the demo web app bundle. Serves ONLY the web app — the self-hosted demo
  * REST API lives in a separate `DemoApiServer` (`cli/src/utils/api-server.ts`, port 5200) so the

package/dist/utils/demo-server.js

@@ -16,6 +16,8 @@ const MIME_TYPES = {
     '.woff2': 'font/woff2',
     '.ttf': 'font/ttf',
 };
+/** Default static port for the demo web app (distinct from Vite's default 5173 to avoid collisions). */
+export const DEFAULT_DEMO_PORT = 5180;
 /**
  * Static file server for the demo web app bundle. Serves ONLY the web app — the self-hosted demo
  * REST API lives in a separate `DemoApiServer` (`cli/src/utils/api-server.ts`, port 5200) so the
@@ -24,7 +26,7 @@ const MIME_TYPES = {
 export class DemoServer {
     server = null;
     port;
-    constructor(port = 5173) {
+    constructor(port = DEFAULT_DEMO_PORT) {
         this.port = port;
     }
     static resolveDemoDist() {
@@ -67,6 +69,7 @@ export class DemoServer {
                     res.writeHead(200, {
                         'Content-Type': contentType,
                         'Access-Control-Allow-Origin': '*',
+                        'X-TestSpectra-Demo': 'true',
                     });
                     res.end(content);
                 }
@@ -76,15 +79,25 @@ export class DemoServer {
                 }
             });
             this.server.on('error', (err) => {
-                if (err.code === 'EADDRINUSE') {
-                    // Port already in use (e.g. user already running server)
-                    resolve({ url: `http://localhost:${this.port}`, port: this.port });
+                if (err.code === 'EADDRINUSE' && this.port !== 0) {
+                    // If preferred port is in use by another process, fall back to an ephemeral free port
+                    this.server?.listen(0, () => {
+                        const addr = this.server?.address();
+                        const actualPort = typeof addr === 'object' && addr !== null ? addr.port : 0;
+                        resolve({ url: `http://localhost:${actualPort}`, port: actualPort });
+                    });
                 }
                 else {
                     reject(err);
                 }
             });
-            this.server.listen(this.port, '0.0.0.0', () => {
+            // Bind dual-stack (no host = `::` with IPv4-mapped fallback) — NOT `0.0.0.0`. Chromium
+            // resolves `localhost` to `::1` first, so an IPv4-only server is missed whenever anything
+            // else answers IPv6 localhost. Note this does NOT guarantee EADDRINUSE against such a
+            // squatter: with SO_REUSEADDR a wildcard bind can silently coexist with a specific-bound
+            // socket, so callers must always follow the returned URL (or request port 0) instead of
+            // assuming the requested port is really ours.
+            this.server.listen(this.port, () => {
                 const addr = this.server?.address();
                 const actualPort = typeof addr === 'object' && addr !== null ? addr.port : this.port;
                 resolve({ url: `http://localhost:${actualPort}`, port: actualPort });

package/dist/utils/demo-state.d.ts

@@ -0,0 +1,40 @@
+export interface DemoServerState {
+    pid: number;
+    url: string;
+    port: number;
+    apiUrl?: string;
+    apiPort?: number;
+    startedAt: number;
+}
+export declare class DemoStateManager {
+    private static readonly STATE_FILENAME;
+    /**
+     * Resolves the primary project directory from `cwd` by locating `spectra.config.*`
+     * or falling back to searching upward for an existing `.testspectra` directory.
+     */
+    static resolveProjectDir(cwd?: string): string;
+    /**
+     * Returns candidate file paths for the demo server state file,
+     * checking the project-level `.testspectra` directory first, followed by the global home directory.
+     */
+    static getStateFilePaths(cwd?: string): string[];
+    /**
+     * Persists the active demo server state to disk for cross-process / cross-terminal discovery.
+     */
+    static saveState(state: DemoServerState, cwd?: string): void;
+    /**
+     * Removes demo server state files when the demo server terminates.
+     */
+    static removeState(cwd?: string): void;
+    /**
+     * Probes an HTTP server URL with a short timeout to verify it is responsive
+     * and optionally serves the TestSpectra demo web app.
+     */
+    static probeServer(url: string, timeoutMs?: number): Promise<boolean>;
+    /**
+     * Discovers whether a demo server session is actively running.
+     * If a state file exists and the target server responds to probe, returns the state.
+     * Stale state files (where the server does not respond) are automatically cleaned up.
+     */
+    static getActiveDemoServer(cwd?: string): Promise<DemoServerState | null>;
+}