@testspectra/reporter 1.1.13

package/LICENSE.md

@@ -0,0 +1,5 @@
+# TestSpectra Proprietary License
+
+Copyright (c) 2026 TestSpectra Team. All rights reserved.
+
+This source code is licensed under the proprietary terms specified in the root repository license.

package/dist/formatter.d.ts

@@ -0,0 +1,38 @@
+import type { ActionKey, AssertionKey } from './types.js';
+/**
+ * Extracts a string representation from an element/target identifier or object.
+ */
+export declare function extractTargetString(target?: any): string;
+/**
+ * Renders a `ScopedSelector`'s `.parent` chain (produced by `element.get()`/`.getAll()` chaining)
+ * as `"parent" within "grandparent"`, nearest ancestor first — or null when the target isn't scoped.
+ */
+export declare function extractWithinChain(target?: any): string | null;
+/**
+ * Formats an element target into a descriptive label.
+ */
+export declare function formatElementTarget(target?: any): string;
+/**
+ * Formats a collection target into a descriptive label.
+ */
+export declare function formatCollectionTarget(target?: any): string;
+/**
+ * Maps positional action arguments array to a named argument dictionary.
+ */
+export declare function mapActionArgs(key: string, arr: any): Record<string, any>;
+/**
+ * Maps positional assertion arguments array to a named argument dictionary.
+ */
+export declare function mapAssertionArgs(key: string, arr: any): Record<string, any>;
+/**
+ * Transforms raw action commands into grammatically correct English sentences.
+ */
+export declare function formatAction(actionKey: ActionKey | string, target?: any, args?: Record<string, any>): string;
+/**
+ * Transforms raw matcher assertions into grammatically correct English sentences.
+ */
+export declare function formatAssertion(assertionKey: AssertionKey | string, target?: any, args?: Record<string, any>): string;
+/**
+ * Parses raw JSON action/assertion payloads or native orchestrator payloads into English sentences.
+ */
+export declare function parseAndFormat(cmdText: string): string;

package/dist/formatter.js

@@ -0,0 +1,379 @@
+/**
+ * Extracts a string representation from an element/target identifier or object.
+ */
+export function extractTargetString(target) {
+    if (!target)
+        return '';
+    if (typeof target === 'string')
+        return target;
+    if (typeof target === 'object') {
+        if (typeof target.selector === 'string')
+            return target.selector;
+        if (typeof target.name === 'string')
+            return target.name;
+        if (typeof target.target === 'string')
+            return target.target;
+    }
+    return String(target);
+}
+/**
+ * Renders a `ScopedSelector`'s `.parent` chain (produced by `element.get()`/`.getAll()` chaining)
+ * as `"parent" within "grandparent"`, nearest ancestor first — or null when the target isn't scoped.
+ */
+export function extractWithinChain(target) {
+    if (!target || typeof target !== 'object' || !target.parent)
+        return null;
+    const chain = [];
+    for (let p = target.parent; p; p = p.parent) {
+        if (p.selector) {
+            chain.push(p.selector);
+        }
+    }
+    return chain.length > 0 ? chain.join('" within "') : null;
+}
+/**
+ * Formats an element target into a descriptive label.
+ */
+export function formatElementTarget(target) {
+    const sel = extractTargetString(target);
+    if (!sel)
+        return 'element {target}';
+    if (sel.startsWith('element "') || sel.startsWith('collection "')) {
+        return sel;
+    }
+    const within = extractWithinChain(target);
+    return within ? `element "${sel}" within "${within}"` : `element "${sel}"`;
+}
+/**
+ * Formats a collection target into a descriptive label.
+ */
+export function formatCollectionTarget(target) {
+    const sel = extractTargetString(target);
+    if (!sel)
+        return 'collection "{selector}"';
+    if (sel.startsWith('collection "')) {
+        return sel;
+    }
+    const within = extractWithinChain(target);
+    return within ? `collection "${sel}" within "${within}"` : `collection "${sel}"`;
+}
+/**
+ * Maps positional action arguments array to a named argument dictionary.
+ */
+export 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 {};
+    }
+}
+/**
+ * Maps positional assertion arguments array to a named argument dictionary.
+ */
+export 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],
+    };
+}
+/**
+ * Transforms raw action commands into grammatically correct English sentences.
+ */
+export function formatAction(actionKey, target, args = {}) {
+    const el = formatElementTarget(target);
+    switch (actionKey) {
+        case 'mount':
+            return `Mount component "${extractTargetString(target) || '{component}'}"`;
+        case 'click':
+            return `Click on ${el}`;
+        case 'doubleClick':
+            return `Double-click on ${el}`;
+        case 'rightClick':
+            return `Right-click on ${el}`;
+        case 'type':
+            return `Type "${args.text ?? args.value ?? '{text}'}" into ${el}`;
+        case 'clear':
+            return `Clear text in ${el}`;
+        case 'select':
+        case 'selectOption':
+            return `Select option "${args.option ?? args.value ?? args.text ?? '{option}'}" in ${el}`;
+        case 'hover':
+            return `Hover over ${el}`;
+        case 'dragDrop': {
+            const dest = args.dest || args.destination ? formatElementTarget(args.dest || args.destination) : 'element {dest}';
+            return `Drag ${el} and drop onto ${dest}`;
+        }
+        case 'scrollIntoView':
+            return `Scroll ${el} into view`;
+        case 'longPress':
+            return `Long-press on ${el} for ${args.durationMs ?? args.ms ?? args.duration ?? '{durationMs}'}ms`;
+        case 'waitForElement':
+            return `Wait for ${el} to be displayed`;
+        case 'navigate':
+            return `Navigate to "${args.url ?? '{url}'}"`;
+        case 'back':
+            return `Navigate back in browser`;
+        case 'forward':
+            return `Navigate forward in browser`;
+        case 'refresh':
+            return `Refresh current page`;
+        case 'setViewport':
+            return `Set viewport to ${args.width ?? '{width}'}x${args.height ?? '{height}'}`;
+        case 'wait':
+            return `Wait for ${args.ms ?? args.durationMs ?? '{ms}'}ms`;
+        case 'pressKey':
+            return `Press keyboard key "${args.key ?? args.value ?? '{key}'}"`;
+        case 'scroll':
+            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':
+            return `Clear all browser cookies`;
+        case 'setCookies':
+            return `Set cookies for "${args.url ?? '{url}'}"`;
+        case 'clearLocalStorage':
+            return `Clear browser localStorage`;
+        default:
+            return `Perform ${actionKey} on ${el}`;
+    }
+}
+/**
+ * Transforms raw matcher assertions into grammatically correct English sentences.
+ */
+export function formatAssertion(assertionKey, target, args = {}) {
+    const el = formatElementTarget(target);
+    const col = formatCollectionTarget(target);
+    switch (assertionKey) {
+        case 'be.visible':
+            return `Expect ${el} to be visible`;
+        case 'not.be.visible':
+            return `Expect ${el} not to be visible`;
+        case 'exist':
+            return `Expect ${el} to exist in DOM`;
+        case 'not.exist':
+            return `Expect ${el} not to exist in DOM`;
+        case 'be.clickable':
+            return `Expect ${el} to be clickable`;
+        case 'not.be.clickable':
+            return `Expect ${el} not to be clickable`;
+        case 'be.enabled':
+            return `Expect ${el} to be enabled`;
+        case 'be.disabled':
+            return `Expect ${el} to be disabled`;
+        case 'be.checked':
+            return `Expect ${el} to be checked`;
+        case 'not.be.checked':
+            return `Expect ${el} not to be checked`;
+        case 'be.selected':
+            return `Expect ${el} to be selected`;
+        case 'not.be.selected':
+            return `Expect ${el} not to be selected`;
+        case 'be.focused':
+            return `Expect ${el} to be focused`;
+        case 'not.be.focused':
+            return `Expect ${el} not to be focused`;
+        case 'have.text':
+            return `Expect ${el} to have text "${args.expected ?? args.text ?? '{str}'}"`;
+        case 'not.have.text':
+            return `Expect ${el} not to have text "${args.expected ?? args.text ?? '{str}'}"`;
+        case 'contain.text':
+            return `Expect ${el} to contain text "${args.expected ?? args.text ?? '{sub}'}"`;
+        case 'not.contain.text':
+            return `Expect ${el} not to contain text "${args.expected ?? args.text ?? '{s}'}"`;
+        case 'have.value':
+            return `Expect ${el} to have value "${args.expected ?? args.value ?? '{val}'}"`;
+        case 'not.have.value':
+            return `Expect ${el} not to have value "${args.expected ?? args.value ?? '{val}'}"`;
+        case 'contain.value':
+            return `Expect ${el} to contain value "${args.expected ?? args.value ?? '{s}'}"`;
+        case 'not.contain.value':
+            return `Expect ${el} not to contain value "${args.expected ?? args.value ?? '{s}'}"`;
+        case 'have.attr':
+            return args.value !== undefined
+                ? `Expect ${el} to have attribute "${args.name ?? args.expected ?? '{k}'}" = "${args.value}"`
+                : `Expect ${el} to have attribute "${args.name ?? args.expected ?? '{k}'}"`;
+        case 'not.have.attr':
+            return `Expect ${el} not to have attribute "${args.name ?? args.expected ?? '{k}'}"`;
+        case 'have.class':
+            return `Expect ${el} to have class "${args.expected ?? args.className ?? '{cls}'}"`;
+        case 'not.have.class':
+            return `Expect ${el} not to have class "${args.expected ?? args.className ?? '{cls}'}"`;
+        case 'have.css':
+            return `Expect ${el} to have CSS "${args.name ?? args.property ?? '{prop}'}" = "${args.value ?? '{val}'}"`;
+        case 'not.have.css':
+            return `Expect ${el} not to have CSS "${args.name ?? args.property ?? '{p}'}" = "${args.value ?? '{v}'}"`;
+        // Collections
+        case 'have.length':
+            return `Expect ${col} count to equal ${args.expected ?? args.length ?? '{n}'}`;
+        case 'not.have.length':
+            return `Expect ${col} count not to equal ${args.expected ?? args.length ?? '{n}'}`;
+        case 'have.length.greaterThan':
+            return `Expect ${col} count to be greater than ${args.expected ?? args.min ?? '{n}'}`;
+        case 'have.length.lessThan':
+            return `Expect ${col} count to be less than ${args.expected ?? args.max ?? '{n}'}`;
+        case 'be.empty':
+            return `Expect ${col} to be empty`;
+        case 'not.be.empty':
+            return `Expect ${col} not to be empty`;
+        // Browser Context
+        case 'have.url':
+        case 'shouldHaveUrl':
+            return `Expect browser URL to be "${args.expected ?? args.url ?? '{url}'}"`;
+        case 'contain.url':
+        case 'shouldContainUrl':
+            return `Expect browser URL to contain "${args.expected ?? args.url ?? '{url}'}"`;
+        case 'have.title':
+        case 'shouldHaveTitle':
+            return `Expect browser title to be "${args.expected ?? args.title ?? '{title}'}"`;
+        case 'contain.title':
+        case 'shouldContainTitle':
+            return `Expect browser title to contain "${args.expected ?? args.title ?? '{title}'}"`;
+        case 'be.loaded':
+        case 'shouldBeLoaded':
+        case 'be.pageLoaded':
+        case 'shouldBePageLoaded':
+            return `Expect page to be fully loaded`;
+        case 'have.noConsoleErrors':
+        case 'shouldHaveNoConsoleErrors':
+            return `Expect browser console to have no errors`;
+        default:
+            return `Expect ${el} to match ${assertionKey}`;
+    }
+}
+/**
+ * Parses raw JSON action/assertion payloads or native orchestrator payloads into English sentences.
+ */
+export function parseAndFormat(cmdText) {
+    try {
+        const payload = JSON.parse(cmdText);
+        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;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @packageDocumentation
+ * # @testspectra/reporter
+ *
+ * Canonical semantic reporter, stream parser, and execution telemetry for TestSpectra.
+ */
+export * from './types.js';
+export * from './formatter.js';
+export * from './parser.js';
+export * from './reporter.js';

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * @packageDocumentation
+ * # @testspectra/reporter
+ *
+ * Canonical semantic reporter, stream parser, and execution telemetry for TestSpectra.
+ */
+export * from './types.js';
+export * from './formatter.js';
+export * from './parser.js';
+export * from './reporter.js';

package/dist/parser.d.ts

@@ -0,0 +1,61 @@
+import type { ParsedLineResult, ParsedTestHeader, ParsedToken, TestLog } from './types.js';
+/**
+ * Strips ANSI color and control escape sequences from a string.
+ */
+export declare function stripAnsi(str: string): string;
+/**
+ * Parses test headers in formats like:
+ * - "✓ ApiInterception / TC-0008-fetch-mocking (412ms)"
+ * - "✗ ApiInterception / TC-0009-post-mocking (65ms)"
+ * - "● Playground / TC-0001-form-controls"
+ * - "✓ TC-0008-fetch-mocking (412ms)"
+ */
+export declare function parseTestHeader(rawText: string): ParsedTestHeader;
+/**
+ * Detects whether a terminal stdout line belongs to an execution summary card or phase timing breakdown.
+ */
+export declare function isSummaryLine(raw: string): boolean;
+/**
+ * Checks whether a raw or cleaned line is an internal machine protocol token
+ * (e.g. `[TESTSPECTRA_STEP_START]`, `[TESTSPECTRA_STEP_PASS]`, `[TESTSPECTRA_STEP_FAIL]`,
+ * `[TESTSPECTRA_TEST_START]`, `[TESTSPECTRA_TEST_PASS]`, `[TESTSPECTRA_TEST_FAIL]`,
+ * `[TESTSPECTRA_TEST_ERROR]`, `[TESTSPECTRA_COMPLETE]`, `[TESTSPECTRA_NETWORK]`, `[TESTSPECTRA_DURATION]`).
+ */
+export declare function isInternalProtocolLine(raw: string): boolean;
+/**
+ * Real-Time Terminal Stdout Tokenizer & Log Factory.
+ */
+export declare class TestOutputParser {
+    private _currentError;
+    /** Returns the most recently captured error message string. */
+    get currentError(): string;
+    /** Clears the current error state. */
+    clearError(): void;
+    /**
+     * Extracts optional worker tags such as `[0-0]`, `[0-1]`, `[worker-1]`, `[worker:0]`.
+     * Ensures internal tokens like `[TESTSPECTRA_...]` are never falsely classified as worker tags.
+     */
+    extractWorkerTag(line: string): {
+        workerId?: string;
+        remaining: string;
+    };
+    /**
+     * Parses a raw line of terminal output, stripping worker tags and extracting lifecycle tokens.
+     */
+    parseLineWithWorker(line: string): ParsedLineResult;
+    /**
+     * Evaluates a clean terminal line and extracts lifecycle tokens.
+     *
+     * @param line - Clean line text without worker prefixes.
+     * @returns The extracted `ParsedToken`.
+     */
+    parseLine(line: string): ParsedToken;
+    /**
+     * Factory creating a structured `TestLog` from a terminal output line.
+     *
+     * @param line - Raw line text.
+     * @param isError - Whether the line originated from stderr.
+     * @param executionId - Associated execution ID.
+     */
+    createTestLog(line: string, isError: boolean, executionId?: string): TestLog;
+}

package/dist/parser.js

@@ -0,0 +1,238 @@
+import { parseAndFormat } from './formatter.js';
+/**
+ * Strips ANSI color and control escape sequences from a string.
+ */
+export function stripAnsi(str) {
+    return str.replace(/\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, '');
+}
+/**
+ * Parses test headers in formats like:
+ * - "✓ ApiInterception / TC-0008-fetch-mocking (412ms)"
+ * - "✗ ApiInterception / TC-0009-post-mocking (65ms)"
+ * - "● Playground / TC-0001-form-controls"
+ * - "✓ TC-0008-fetch-mocking (412ms)"
+ */
+export function parseTestHeader(rawText) {
+    const clean = stripAnsi(rawText)
+        .replace(/^\[TESTSPECTRA_TEST_(START|PASS|FAIL)\]/, '')
+        .replace(/^[✓✗●✔✖]\s*/, '')
+        .trim();
+    const matchDuration = clean.match(/\(([^)]+)ms\)$/);
+    const durationMs = matchDuration ? parseInt(matchDuration[1], 10) : undefined;
+    const titlePart = clean.replace(/\s*\([^)]+\)$/, '').trim();
+    if (titlePart.includes(' / ')) {
+        const parts = titlePart.split(' / ');
+        const suiteName = parts[0].trim();
+        const testCaseId = parts.slice(1).join(' / ').trim();
+        return {
+            suiteName: suiteName || undefined,
+            testCaseId: testCaseId || titlePart,
+            durationMs,
+        };
+    }
+    return {
+        testCaseId: titlePart,
+        durationMs,
+    };
+}
+/**
+ * Detects whether a terminal stdout line belongs to an execution summary card or phase timing breakdown.
+ */
+export function isSummaryLine(raw) {
+    const clean = stripAnsi(raw).trim();
+    return (clean.includes('TESTSPECTRA EXECUTION SUMMARY') ||
+        clean.includes('TestSpectra Execution Summary') ||
+        clean.includes('EXECUTION TIMING BREAKDOWN') ||
+        clean.startsWith('╭') ||
+        clean.startsWith('├') ||
+        clean.startsWith('╰') ||
+        clean.startsWith('┌') ||
+        clean.startsWith('└') ||
+        clean.startsWith('│') ||
+        /^\d+\.\s+(Master Chromium|Worker Spawning|Incognito Context|Total Test Execution|Context Teardown)/.test(clean));
+}
+/**
+ * Checks whether a raw or cleaned line is an internal machine protocol token
+ * (e.g. `[TESTSPECTRA_STEP_START]`, `[TESTSPECTRA_STEP_PASS]`, `[TESTSPECTRA_STEP_FAIL]`,
+ * `[TESTSPECTRA_TEST_START]`, `[TESTSPECTRA_TEST_PASS]`, `[TESTSPECTRA_TEST_FAIL]`,
+ * `[TESTSPECTRA_TEST_ERROR]`, `[TESTSPECTRA_COMPLETE]`, `[TESTSPECTRA_NETWORK]`, `[TESTSPECTRA_DURATION]`).
+ */
+export function isInternalProtocolLine(raw) {
+    const clean = stripAnsi(raw).trim();
+    return /^\[TESTSPECTRA_[A-Z0-9_]+\]/i.test(clean);
+}
+/**
+ * Real-Time Terminal Stdout Tokenizer & Log Factory.
+ */
+export class TestOutputParser {
+    _currentError = '';
+    /** Returns the most recently captured error message string. */
+    get currentError() {
+        return this._currentError;
+    }
+    /** Clears the current error state. */
+    clearError() {
+        this._currentError = '';
+    }
+    /**
+     * Extracts optional worker tags such as `[0-0]`, `[0-1]`, `[worker-1]`, `[worker:0]`.
+     * Ensures internal tokens like `[TESTSPECTRA_...]` are never falsely classified as worker tags.
+     */
+    extractWorkerTag(line) {
+        const raw = stripAnsi(line).trim();
+        if (/^\[(TESTSPECTRA|Network|TestSpectra)/i.test(raw)) {
+            return { workerId: undefined, remaining: raw };
+        }
+        const match = raw.match(/^\[(\d+-\d+|worker[:_-]?\w+|\d+)\]\s*(.*)$/i);
+        if (match) {
+            return { workerId: match[1], remaining: match[2] };
+        }
+        return { workerId: undefined, remaining: raw };
+    }
+    /**
+     * Parses a raw line of terminal output, stripping worker tags and extracting lifecycle tokens.
+     */
+    parseLineWithWorker(line) {
+        const { workerId, remaining } = this.extractWorkerTag(line);
+        const token = this.parseLine(remaining);
+        return { workerId, token, cleanLine: remaining };
+    }
+    /**
+     * Evaluates a clean terminal line and extracts lifecycle tokens.
+     *
+     * @param line - Clean line text without worker prefixes.
+     * @returns The extracted `ParsedToken`.
+     */
+    parseLine(line) {
+        const raw = stripAnsi(line).trim();
+        if (!raw)
+            return { type: 'none' };
+        // 1. Check for summary cards or timing tables
+        if (isSummaryLine(raw)) {
+            return { type: 'summary_banner', text: raw };
+        }
+        // 2. Spec file announcement: "RUNNING in <path>"
+        const runningMatch = raw.match(/RUNNING in (.+)/);
+        if (runningMatch) {
+            let specPath = runningMatch[1].trim();
+            specPath = specPath.replace(/\s+-\s+[a-zA-Z0-9_-]+$/, '').trim();
+            specPath = specPath.replace(/^[a-zA-Z0-9_-]+\s+-\s+/, '').trim();
+            return { type: 'spec_file', specPath };
+        }
+        // 3. Step passed: "✔ <stepText> (<duration>ms)" or "[TESTSPECTRA_STEP_PASS]"
+        if (raw.startsWith('✔ ') || raw.startsWith('[TESTSPECTRA_STEP_PASS]')) {
+            const fullText = raw
+                .replace('[TESTSPECTRA_STEP_PASS]', '')
+                .replace(/^✔\s*/, '')
+                .trim();
+            const match = fullText.match(/\(([^)]+)ms\)$/);
+            const durationMs = match ? parseInt(match[1], 10) : undefined;
+            const cmdText = fullText.replace(/\s*\([^)]+\)$/, '').trim();
+            const formatted = parseAndFormat(cmdText);
+            return { type: 'step_pass', stepText: formatted, durationMs };
+        }
+        // 4. Step failed: "✖ <stepText> (<duration>ms)" or "[TESTSPECTRA_STEP_FAIL]"
+        if (raw.startsWith('✖ ') || raw.startsWith('[TESTSPECTRA_STEP_FAIL]')) {
+            const fullText = raw
+                .replace('[TESTSPECTRA_STEP_FAIL]', '')
+                .replace(/^✖\s*/, '')
+                .trim();
+            const match = fullText.match(/\(([^)]+)ms\)$/);
+            const durationMs = match ? parseInt(match[1], 10) : undefined;
+            const cmdText = fullText.replace(/\s*\([^)]+\)$/, '').trim();
+            const formatted = parseAndFormat(cmdText);
+            return { type: 'step_fail', stepText: formatted, durationMs };
+        }
+        // 5. Test error: "[TESTSPECTRA_TEST_ERROR]" or "↳ Error: <msg>"
+        if (raw.startsWith('[TESTSPECTRA_TEST_ERROR]') || raw.includes('↳ Error:')) {
+            const message = raw
+                .replace('[TESTSPECTRA_TEST_ERROR]', '')
+                .replace(/.*↳\s*Error:\s*/, '')
+                .trim();
+            this._currentError = message;
+            return { type: 'test_error', message };
+        }
+        // 6. Test started: "[TESTSPECTRA_TEST_START]" or "● <title>"
+        if (raw.startsWith('[TESTSPECTRA_TEST_START]') || raw.startsWith('● ')) {
+            const content = raw
+                .replace('[TESTSPECTRA_TEST_START]', '')
+                .replace(/^●\s*/, '')
+                .trim();
+            try {
+                const parsed = JSON.parse(content);
+                if (parsed && typeof parsed === 'object') {
+                    const title = parsed.title || parsed.id || '';
+                    const id = typeof parsed.id === 'string' ? parsed.id : undefined;
+                    const testFilePath = typeof parsed.testFilePath === 'string' ? parsed.testFilePath : undefined;
+                    const workerId = typeof parsed.workerId === 'number' ? parsed.workerId : undefined;
+                    const header = parseTestHeader(title);
+                    return {
+                        type: 'test_start',
+                        title,
+                        suiteName: header.suiteName,
+                        testCaseId: header.testCaseId,
+                        id,
+                        testFilePath,
+                        workerId,
+                    };
+                }
+            }
+            catch { }
+            const header = parseTestHeader(content);
+            return {
+                type: 'test_start',
+                title: content,
+                suiteName: header.suiteName,
+                testCaseId: header.testCaseId,
+            };
+        }
+        // 7. Test passed: "[TESTSPECTRA_TEST_PASS]" or "✓ <title> (<duration>ms)"
+        if (raw.startsWith('[TESTSPECTRA_TEST_PASS]') || raw.startsWith('✓ ')) {
+            const header = parseTestHeader(raw);
+            this._currentError = '';
+            return {
+                type: 'test_pass',
+                title: header.testCaseId,
+                suiteName: header.suiteName,
+                testCaseId: header.testCaseId,
+                durationMs: header.durationMs,
+            };
+        }
+        // 8. Test failed: "[TESTSPECTRA_TEST_FAIL]" or "✗ <title> (<duration>ms)"
+        if (raw.startsWith('[TESTSPECTRA_TEST_FAIL]') || raw.startsWith('✗ ')) {
+            const header = parseTestHeader(raw);
+            return {
+                type: 'test_fail',
+                title: header.testCaseId,
+                suiteName: header.suiteName,
+                testCaseId: header.testCaseId,
+                durationMs: header.durationMs,
+            };
+        }
+        return { type: 'none' };
+    }
+    /**
+     * Factory creating a structured `TestLog` from a terminal output line.
+     *
+     * @param line - Raw line text.
+     * @param isError - Whether the line originated from stderr.
+     * @param executionId - Associated execution ID.
+     */
+    createTestLog(line, isError, executionId) {
+        const now = new Date();
+        const timeStr = `${String(now.getHours()).padStart(2, '0')}:${String(now.getMinutes()).padStart(2, '0')}:${String(now.getSeconds()).padStart(2, '0')}`;
+        let level = isError ? 'ERROR' : 'INFO';
+        if (line.includes('✓') || line.includes('✔') || line.includes('PASSED'))
+            level = 'SUCCESS';
+        else if (line.includes('✗') || line.includes('✖') || line.includes('FAILED'))
+            level = 'ERROR';
+        else if (line.includes('WARN') || line.includes('Warning:'))
+            level = 'WARNING';
+        return {
+            timestamp: timeStr,
+            level,
+            message: line,
+            runId: executionId,
+        };
+    }
+}

package/dist/reporter.d.ts

@@ -0,0 +1,32 @@
+import type { ExecutionSummary, NetworkResource, PendingTestCase, ReporterOptions, TestLog, TestRunResult } from './types.js';
+export declare class SemanticReporter {
+    protected logs: TestLog[];
+    protected networkEvents: NetworkResource[];
+    protected pendingTests: Map<string, PendingTestCase>;
+    protected workerToTest: Map<number, string>;
+    protected pendingErrorMsg?: string;
+    protected passedCount: number;
+    protected failedCount: number;
+    protected options: ReporterOptions;
+    constructor(options?: ReporterOptions);
+    /**
+     * Resolves an active pending test case by test title or worker ID.
+     */
+    resolveTestCase(testTitle?: string, workerId?: number): PendingTestCase | undefined;
+    /**
+     * Ingests a raw string line or structured TestLog entry from stdout/stderr.
+     */
+    addLog(input: string | TestLog): void;
+    /**
+     * Returns a snapshot of currently running pending test cases.
+     */
+    getPendingTests(): PendingTestCase[];
+    /**
+     * Returns aggregated test run telemetry results.
+     */
+    getResult(): TestRunResult;
+    /**
+     * Computes an execution summary.
+     */
+    getSummary(reportLocation?: string): ExecutionSummary;
+}

package/dist/reporter.js

@@ -0,0 +1,270 @@
+import { parseAndFormat } from './formatter.js';
+import { stripAnsi } from './parser.js';
+export class SemanticReporter {
+    logs = [];
+    networkEvents = [];
+    pendingTests = new Map();
+    workerToTest = new Map();
+    pendingErrorMsg;
+    passedCount = 0;
+    failedCount = 0;
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /**
+     * Resolves an active pending test case by test title or worker ID.
+     */
+    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);
+            }
+        }
+        if (this.pendingTests.size === 1) {
+            return this.pendingTests.values().next().value;
+        }
+        return Array.from(this.pendingTests.values()).pop();
+    }
+    /**
+     * Ingests a raw string line or structured TestLog entry from stdout/stderr.
+     */
+    addLog(input) {
+        const log = typeof input === 'string'
+            ? {
+                timestamp: new Date().toISOString(),
+                level: 'INFO',
+                message: input,
+            }
+            : input;
+        this.logs.push(log);
+        this.options.onLog?.(log);
+        const raw = stripAnsi(log.message || '').trim();
+        if (!raw)
+            return;
+        // Filter out WDIO framework internal noise
+        if (raw.includes('RUNNING in chrome') ||
+            raw.includes('PASSED in chrome') ||
+            raw.includes('FAILED in chrome') ||
+            raw.includes('[NetworkRecorder]') ||
+            raw.includes('"spec" Reporter:') ||
+            raw.includes('"DotReporter" Reporter:') ||
+            raw.includes('SilentReporter') ||
+            raw.startsWith('---') ||
+            raw === '.' ||
+            raw.includes('Session ID:') ||
+            raw.includes('Running: chrome') ||
+            raw.includes('[chrome') ||
+            raw.includes('[firefox') ||
+            raw.includes('[safari') ||
+            raw.includes('[edge') ||
+            raw.includes('(root)') ||
+            raw.includes('passing (') ||
+            raw.includes('failing (') ||
+            raw.includes('Spec Files:') ||
+            (raw.includes('Execution of') && raw.includes('workers started')) ||
+            raw.includes('Spawning WDIO execution') ||
+            raw.includes('WARN webdriver:') ||
+            raw.includes('WebDriverError: unknown error: net::ERR_CONNECTION_REFUSED') ||
+            raw.includes('when running "url" with method "POST"') ||
+            raw.includes('Session info: chrome=')) {
+            return;
+        }
+        // 1. Test started -> initialize test buffer & worker slot
+        if (raw.startsWith('[TESTSPECTRA_TEST_START]')) {
+            const content = raw.replace('[TESTSPECTRA_TEST_START]', '').trim();
+            let title = content;
+            let workerId;
+            try {
+                const parsed = JSON.parse(content);
+                if (parsed.title) {
+                    title = parsed.title;
+                    workerId = parsed.workerId;
+                }
+            }
+            catch { }
+            const pending = {
+                title,
+                workerId,
+                steps: [],
+                currentStep: 'Running suite...',
+                startTime: Date.now(),
+            };
+            this.pendingTests.set(title, pending);
+            if (workerId !== undefined) {
+                this.workerToTest.set(workerId, title);
+            }
+            this.options.onTestStart?.(pending);
+            return;
+        }
+        // 2. Step in-progress / start
+        if (raw.startsWith('[TESTSPECTRA_STEP_START]')) {
+            const fullText = raw.replace('[TESTSPECTRA_STEP_START]', '').trim();
+            let testTitle = '';
+            let workerId;
+            try {
+                const payload = JSON.parse(fullText);
+                testTitle = payload.test || payload.title || '';
+                workerId = payload.workerId;
+            }
+            catch { }
+            const formatted = parseAndFormat(fullText);
+            const testCase = this.resolveTestCase(testTitle, workerId);
+            if (testCase) {
+                testCase.currentStep = formatted;
+            }
+            this.options.onStepStart?.(testTitle || testCase?.title || '', formatted, workerId ?? testCase?.workerId);
+            return;
+        }
+        // 3. Step passed -> record step to matching test case
+        if (raw.startsWith('[TESTSPECTRA_STEP_PASS]')) {
+            const fullText = raw.replace('[TESTSPECTRA_STEP_PASS]', '').trim();
+            const match = fullText.match(/\(([^)]+)ms\)$/);
+            const duration = match ? parseInt(match[1], 10) : 0;
+            const cmdText = fullText.replace(/\s*\([^)]+\)$/, '').trim();
+            const formatted = parseAndFormat(cmdText);
+            let testTitle = '';
+            let workerId;
+            try {
+                const payload = JSON.parse(cmdText);
+                testTitle = payload.test || payload.title || '';
+                workerId = payload.workerId;
+            }
+            catch { }
+            const testCase = this.resolveTestCase(testTitle, workerId);
+            const step = { text: formatted, duration, passed: true };
+            if (testCase) {
+                testCase.steps.push(step);
+                testCase.currentStep = formatted;
+            }
+            this.options.onStepPass?.(testTitle || testCase?.title || '', step, workerId ?? testCase?.workerId);
+            return;
+        }
+        // 4. Step failed -> record failed step to matching test case
+        if (raw.startsWith('[TESTSPECTRA_STEP_FAIL]')) {
+            const fullText = raw.replace('[TESTSPECTRA_STEP_FAIL]', '').trim();
+            const match = fullText.match(/\(([^)]+)ms\)$/);
+            const duration = match ? parseInt(match[1], 10) : 0;
+            const cmdText = fullText.replace(/\s*\([^)]+\)$/, '').trim();
+            const formatted = parseAndFormat(cmdText);
+            let testTitle = '';
+            let workerId;
+            try {
+                const payload = JSON.parse(cmdText);
+                testTitle = payload.test || payload.title || '';
+                workerId = payload.workerId;
+            }
+            catch { }
+            const testCase = this.resolveTestCase(testTitle, workerId);
+            const step = { text: formatted, duration, passed: false };
+            if (testCase) {
+                testCase.steps.push(step);
+                testCase.currentStep = formatted;
+            }
+            this.options.onStepFail?.(testTitle || testCase?.title || '', step, workerId ?? testCase?.workerId);
+            return;
+        }
+        // 5. Test error detail
+        if (raw.startsWith('[TESTSPECTRA_TEST_ERROR]')) {
+            const err = raw.replace('[TESTSPECTRA_TEST_ERROR]', '').trim();
+            const latest = Array.from(this.pendingTests.values()).pop();
+            if (latest) {
+                latest.errorMsg = latest.errorMsg ? `${latest.errorMsg}\n${err}` : err;
+            }
+            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
+        if (raw.startsWith('[TESTSPECTRA_TEST_PASS]')) {
+            const fullText = raw.replace('[TESTSPECTRA_TEST_PASS]', '').trim();
+            const match = fullText.match(/\(([^)]+)ms\)$/);
+            const duration = match ? parseInt(match[1], 10) : 0;
+            const title = fullText.replace(/\s*\([^)]+\)$/, '').trim();
+            this.passedCount++;
+            const testCase = this.pendingTests.get(title) || this.resolveTestCase(title);
+            const steps = testCase?.steps || [];
+            const workerId = testCase?.workerId;
+            this.pendingTests.delete(title);
+            if (workerId !== undefined) {
+                this.workerToTest.delete(workerId);
+            }
+            this.options.onTestPass?.({ title, duration, steps, workerId });
+            return;
+        }
+        // 7. Test failed completely -> flush atomic failed test block
+        if (raw.startsWith('[TESTSPECTRA_TEST_FAIL]')) {
+            const fullText = raw.replace('[TESTSPECTRA_TEST_FAIL]', '').trim();
+            const match = fullText.match(/\(([^)]+)ms\)$/);
+            const duration = match ? parseInt(match[1], 10) : 0;
+            const title = fullText.replace(/\s*\([^)]+\)$/, '').trim();
+            this.failedCount++;
+            const testCase = this.pendingTests.get(title) || this.resolveTestCase(title);
+            const steps = testCase?.steps || [];
+            const errorMsg = testCase?.errorMsg || this.pendingErrorMsg;
+            const workerId = testCase?.workerId;
+            this.pendingTests.delete(title);
+            if (workerId !== undefined) {
+                this.workerToTest.delete(workerId);
+            }
+            this.pendingErrorMsg = undefined;
+            this.options.onTestFail?.({ title, duration, steps, errorMsg, workerId });
+            return;
+        }
+        // 8. Test duration token
+        if (raw.startsWith('[TESTSPECTRA_DURATION]')) {
+            return;
+        }
+        // 9. Network resource telemetry
+        if (raw.startsWith('[TESTSPECTRA_NETWORK]')) {
+            try {
+                const jsonStr = raw.replace('[TESTSPECTRA_NETWORK]', '').trim();
+                const payload = JSON.parse(jsonStr);
+                this.networkEvents.push(payload);
+                this.options.onNetwork?.(payload);
+            }
+            catch { }
+            return;
+        }
+    }
+    /**
+     * Returns a snapshot of currently running pending test cases.
+     */
+    getPendingTests() {
+        return Array.from(this.pendingTests.values());
+    }
+    /**
+     * Returns aggregated test run telemetry results.
+     */
+    getResult() {
+        const hasFailures = this.failedCount > 0;
+        return {
+            status: hasFailures ? 'failed' : 'passed',
+            duration: '0s',
+            passedCount: this.passedCount,
+            failedCount: this.failedCount,
+            logs: this.logs,
+            networkResources: this.networkEvents.length > 0 ? this.networkEvents : undefined,
+        };
+    }
+    /**
+     * Computes an execution summary.
+     */
+    getSummary(reportLocation = '.testspectra/reports/result.json') {
+        const totalTests = this.passedCount + this.failedCount;
+        return {
+            totalSuites: 1,
+            totalTests,
+            passedCount: this.passedCount,
+            failedCount: this.failedCount,
+            durationMs: 0,
+            reportLocation,
+        };
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,138 @@
+export type ActionKey = 'click' | 'doubleClick' | 'rightClick' | 'type' | 'clear' | 'select' | 'selectOption' | 'hover' | 'dragDrop' | 'scrollIntoView' | 'longPress' | 'waitForElement' | 'navigate' | 'back' | 'forward' | 'refresh' | 'setViewport' | 'wait' | 'pressKey' | 'scroll' | 'swipe' | 'upload' | 'intercept' | 'clearCookies' | 'setCookies' | 'clearLocalStorage' | 'mount';
+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';
+export type TestLogLevel = 'INFO' | 'SUCCESS' | 'WARNING' | 'ERROR' | 'DEBUG';
+export interface TestLog {
+    timestamp: string;
+    level: TestLogLevel;
+    message: string;
+    runId?: string;
+}
+export interface NetworkResource {
+    requestId: string;
+    url: string;
+    method: string;
+    status: number;
+    type?: string;
+    statusText?: string;
+    domain?: string;
+    protocol?: string;
+    timing?: {
+        waiting: number;
+        download: number;
+    };
+    size?: number;
+    transferSize?: number;
+    priority?: string;
+    cached?: boolean;
+    initiator?: string;
+    remoteIP?: string;
+    connectionId?: string;
+    startTime?: number;
+    runId?: string;
+    testTitle?: string;
+}
+export interface PendingStep {
+    text: string;
+    duration: number;
+    passed: boolean;
+}
+export interface PendingTestCase {
+    title: string;
+    workerId?: number;
+    steps: PendingStep[];
+    currentStep?: string;
+    errorMsg?: string;
+    videoPath?: string;
+    startTime: number;
+}
+export interface TestRunResult {
+    status: 'passed' | 'failed' | 'error' | string;
+    duration: string;
+    passedCount: number;
+    failedCount: number;
+    logs: TestLog[];
+    networkResources?: NetworkResource[];
+}
+export interface ExecutionSummary {
+    totalSuites: number;
+    totalTests: number;
+    passedCount: number;
+    failedCount: number;
+    durationMs: number;
+    reportLocation: string;
+}
+export interface ParsedTestHeader {
+    suiteName?: string;
+    testCaseId: string;
+    durationMs?: number;
+}
+export type ParsedToken = {
+    type: 'spec_file';
+    specPath: string;
+} | {
+    type: 'test_start';
+    title: string;
+    suiteName?: string;
+    testCaseId?: string;
+    id?: string;
+    testFilePath?: string;
+    workerId?: number;
+} | {
+    type: 'test_error';
+    message: string;
+} | {
+    type: 'test_pass';
+    title: string;
+    suiteName?: string;
+    testCaseId?: string;
+    durationMs?: number;
+} | {
+    type: 'test_fail';
+    title: string;
+    suiteName?: string;
+    testCaseId?: string;
+    durationMs?: number;
+} | {
+    type: 'step_pass';
+    stepText: string;
+    durationMs?: number;
+} | {
+    type: 'step_fail';
+    stepText: string;
+    durationMs?: number;
+} | {
+    type: 'summary_banner';
+    text: string;
+} | {
+    type: 'none';
+};
+export interface ParsedLineResult {
+    workerId?: string;
+    token: ParsedToken;
+    cleanLine: string;
+}
+export interface ReporterCallbacks {
+    onTestStart?: (test: PendingTestCase) => void;
+    onStepStart?: (testTitle: string, stepText: string, workerId?: number) => void;
+    onStepPass?: (testTitle: string, step: PendingStep, workerId?: number) => void;
+    onStepFail?: (testTitle: string, step: PendingStep, workerId?: number) => void;
+    onTestPass?: (test: {
+        title: string;
+        duration: number;
+        steps: PendingStep[];
+        workerId?: number;
+    }) => void;
+    onTestFail?: (test: {
+        title: string;
+        duration: number;
+        steps: PendingStep[];
+        errorMsg?: string;
+        workerId?: number;
+    }) => void;
+    onTestError?: (errorMessage: string, testTitle?: string, workerId?: number) => void;
+    onNetwork?: (resource: NetworkResource) => void;
+    onLog?: (log: TestLog) => void;
+}
+export interface ReporterOptions extends ReporterCallbacks {
+    isInteractive?: boolean;
+}

package/dist/types.js

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

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@testspectra/reporter",
+  "version": "1.1.13",
+  "description": "Canonical semantic reporter, output stream parser, and execution telemetry for TestSpectra",
+  "files": [
+    "dist",
+    "LICENSE.md"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  },
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc -w",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}