flowstride 1.0.21 → 1.0.22

package/dist/native/deadline.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nativeStepTimeout = nativeStepTimeout;
+const validation_1 = require("./validation");
+/** Only commands whose validated contract accepts a timeout may override it. */
+function nativeStepTimeout(command, input, fallback) {
+    if (['assert.that', 'a11y.match', 'a11y.snapshot', 'stub.expect'].includes(command) &&
+        input !== null && typeof input === 'object' && !Array.isArray(input) &&
+        Object.hasOwn(input, 'timeout')) {
+        return validation_1.positive.parse(input.timeout);
+    }
+    return fallback;
+}

package/dist/native/events.d.ts

@@ -1,3 +1,4 @@
+import { type AssertionReporter } from '../reporting/assertion_result';
 import type { FlowstrideConfig } from '../types';
 import { WebAdapter } from '../adapters/web/playwright';
 export declare class ArmedEvent<T> {
@@ -27,8 +28,8 @@ export declare class NativeEvents {
     private savedDownloads;
     constructor(web: WebAdapter, config: FlowstrideConfig);
     private key;
-    network(action: string, input: unknown): Promise<any>;
-    download(action: string, input: unknown): Promise<any>;
+    network(action: string, input: unknown, reporter?: AssertionReporter): Promise<any>;
+    download(action: string, input: unknown, reporter?: AssertionReporter): Promise<any>;
     disposeProfile(profile: string): Promise<void>;
     dispose(): Promise<void>;
 }

package/dist/native/events.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NativeEvents = exports.ArmedEvent = void 0;
 exports.matchesURL = matchesURL;
+const assertion_result_1 = require("../reporting/assertion_result");
 const zod_1 = require("zod");
 const validation_1 = require("./validation");
 const projectPaths_1 = require("../utils/projectPaths");
@@ -60,7 +61,7 @@ class NativeEvents {
         this.config = config;
     }
     key(value) { return `${this.web.activeProfile}:${value}`; }
-    async network(action, input) {
+    async network(action, input, reporter) {
         if (this.routeErrors.length)
             throw new Error(`Network route failed: ${this.routeErrors.shift()}`);
         if (action === 'route') {
@@ -180,19 +181,26 @@ class NativeEvents {
                 throw new Error('No captured event; call network.wait first.');
             if (!['status', 'method', 'equals', 'contains'].some(key => key in data))
                 throw new Error('Provide a network expectation.');
-            if (data.status !== undefined && result.status !== data.status || data.method && result.method !== data.method.toUpperCase())
-                throw new Error('Network status/method assertion failed.');
+            const checks = [];
+            if (data.status !== undefined)
+                checks.push((0, assertion_result_1.assertionCheck)('status', 'status', result.status === data.status, data.status, result.status));
+            if (data.method)
+                checks.push((0, assertion_result_1.assertionCheck)('method', 'method', result.method === data.method.toUpperCase(), data.method.toUpperCase(), result.method));
             let actual = data.header ? result.headers[data.header.toLowerCase()] : result.body;
             if (data.path)
                 for (const key of data.path.split('.'))
                     actual = actual?.[key];
-            if ('equals' in data && !(0, node_util_1.isDeepStrictEqual)(actual, data.equals) || data.contains !== undefined && !String(actual).includes(data.contains))
-                throw new Error('Network content assertion failed.');
+            const protect = (value) => /password|passcode|secret|token|authorization|cookie|api.?key|otp/i.test((data.header || '') + ' ' + (data.path || '')) ? '[REDACTED]' : value;
+            if ('equals' in data)
+                checks.push((0, assertion_result_1.assertionCheck)('equals', (data.header ? 'header ' + data.header : data.path ? 'body path ' + data.path : 'body') + ' equals', (0, node_util_1.isDeepStrictEqual)(actual, data.equals), protect(data.equals), protect(actual)));
+            if (data.contains !== undefined)
+                checks.push((0, assertion_result_1.assertionCheck)('contains', 'content contains', String(actual).includes(data.contains), protect(data.contains), protect(actual)));
+            (0, assertion_result_1.requireAssertion)('network.expect', 'captured network event ' + JSON.stringify(data.name), checks, reporter, { reason: checks.some(check => check.status === 'failed' && ['status', 'method'].includes(check.key)) ? 'Network status/method assertion failed.' : checks.some(check => check.status === 'failed') ? 'Network content assertion failed.' : undefined });
             return;
         }
         throw new Error(`Unknown network action: ${action}`);
     }
-    async download(action, input) {
+    async download(action, input, reporter) {
         if (action === 'arm') {
             const data = zod_1.z.object({ name: validation_1.name, timeout: validation_1.positive.optional() }).strict().parse(input), key = this.key(data.name), page = this.web.getPage();
             if (this.downloads.has(key))
@@ -240,8 +248,27 @@ class NativeEvents {
                     hash.update(chunk);
                 sha256 = hash.digest('hex');
             }
-            if (data.filename !== undefined && saved.suggested !== data.filename || data.size !== undefined && length !== data.size || data.minSize !== undefined && length < data.minSize || data.contains !== undefined && !body.toString('utf8').includes(data.contains) || data.sha256 !== undefined && sha256 !== data.sha256 || 'json' in data && !(0, node_util_1.isDeepStrictEqual)(JSON.parse(body.toString('utf8')), data.json))
-                throw new Error('Download assertion failed.');
+            const checks = [];
+            if (data.filename !== undefined)
+                checks.push((0, assertion_result_1.assertionCheck)('filename', 'filename', saved.suggested === data.filename, data.filename, saved.suggested));
+            if (data.size !== undefined)
+                checks.push((0, assertion_result_1.assertionCheck)('size', 'size', length === data.size, data.size, length));
+            if (data.minSize !== undefined)
+                checks.push((0, assertion_result_1.assertionCheck)('minSize', 'minimum size', length >= data.minSize, data.minSize, length));
+            if (data.contains !== undefined)
+                checks.push((0, assertion_result_1.assertionCheck)('contains', 'content contains', body.toString('utf8').includes(data.contains), data.contains, body.toString('utf8')));
+            if (data.sha256 !== undefined)
+                checks.push((0, assertion_result_1.assertionCheck)('sha256', 'SHA-256', sha256 === data.sha256, data.sha256, sha256));
+            if ('json' in data) {
+                try {
+                    const actual = JSON.parse(body.toString('utf8'));
+                    checks.push((0, assertion_result_1.assertionCheck)('json', 'JSON content', (0, node_util_1.isDeepStrictEqual)(actual, data.json), data.json, actual));
+                }
+                catch (error) {
+                    checks.push({ ...(0, assertion_result_1.assertionCheck)('json', 'JSON content', false, data.json, body.toString('utf8')), reason: 'Downloaded content is not valid JSON: ' + (0, assertion_result_1.diagnosticValue)(error instanceof Error ? error.message : String(error)) });
+                }
+            }
+            (0, assertion_result_1.requireAssertion)('download.expect', 'saved download ' + JSON.stringify(data.name), checks, reporter, { reason: checks.some(check => check.status === 'failed') ? 'Download assertion failed.' : undefined });
             return;
         }
         throw new Error(`Unknown download action: ${action}`);

package/dist/native/functions.d.ts

@@ -1,9 +1,10 @@
+import { type AssertionReporter } from '../reporting/assertion_result';
 import type { Page } from 'playwright';
 export declare class NativeFunctions {
     private installed;
     private pages;
     private counter;
     private key;
-    execute(page: Page, action: string, input: unknown, timeout: number): Promise<void>;
+    execute(page: Page, action: string, input: unknown, timeout: number, reporter?: AssertionReporter): Promise<void>;
     dispose(): Promise<void>;
 }

package/dist/native/functions.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NativeFunctions = void 0;
+const assertion_result_1 = require("../reporting/assertion_result");
 const zod_1 = require("zod");
 const validation_1 = require("./validation");
 const node_util_1 = require("node:util");
@@ -50,7 +51,7 @@ class NativeFunctions {
     counter = 0;
     key(page, name) { if (!this.pages.has(page))
         this.pages.set(page, ++this.counter); return `${this.pages.get(page)}:${name}`; }
-    async execute(page, action, input, timeout) {
+    async execute(page, action, input, timeout, reporter) {
         if (action === 'install') {
             const data = schema.parse(input);
             if (this.installed.has(this.key(page, data.name)))
@@ -64,7 +65,7 @@ class NativeFunctions {
                 await script?.dispose();
                 throw error;
             }
-            this.installed.set(this.key(page, data.name), { name: data.name, page, script });
+            this.installed.set(this.key(page, data.name), { name: data.name, target: data.target, page, script });
             return;
         }
         if (action === 'restore') {
@@ -81,10 +82,37 @@ class NativeFunctions {
             const data = zod_1.z.object({ name: validation_1.name, count: zod_1.z.number().int().nonnegative().optional(), minCount: zod_1.z.number().int().nonnegative().optional(), args: zod_1.z.array(zod_1.z.unknown()).optional(), timeout: validation_1.positive.optional() }).strict().parse(input);
             if (!['count', 'minCount', 'args'].some(key => key in data))
                 throw new Error('Provide a call count or expected arguments.');
-            await (0, validation_1.poll)(async () => {
-                const calls = await page.evaluate(name => window[Symbol.for('flowstride.function-doubles')]?.[name]?.calls, data.name);
-                return Array.isArray(calls) && (data.count === undefined || calls.length === data.count) && (data.minCount === undefined || calls.length >= data.minCount) && (data.args === undefined || calls.some(call => (0, node_util_1.isDeepStrictEqual)(call, data.args)));
-            }, data.timeout ?? timeout, `function double ${data.name}`);
+            const started = Date.now(), limit = data.timeout ?? timeout;
+            const sensitive = /auth|login|password|passcode|secret|token|cookie|api.?key|otp/i.test(this.installed.get(this.key(page, data.name))?.target || data.name);
+            let latest = (0, assertion_result_1.reportAssertion)('stub.expect', 'function double ' + JSON.stringify(data.name), [{ key: 'calls', label: 'Recorded calls available', status: 'running' }], reporter, { status: 'running', timeout: limit, elapsed: 0 });
+            let closed = false;
+            try {
+                await (0, validation_1.poll)(async () => {
+                    const calls = await page.evaluate(name => window[Symbol.for('flowstride.function-doubles')]?.[name]?.calls, data.name);
+                    const checks = [(0, assertion_result_1.assertionCheck)('calls', 'Recorded calls available', Array.isArray(calls), 'recorded calls', Array.isArray(calls) ? calls.length : 'No function double found on this page')];
+                    if (Array.isArray(calls)) {
+                        if (data.count !== undefined)
+                            checks.push((0, assertion_result_1.assertionCheck)('count', 'call count', calls.length === data.count, data.count, calls.length));
+                        if (data.minCount !== undefined)
+                            checks.push((0, assertion_result_1.assertionCheck)('minCount', 'minimum call count', calls.length >= data.minCount, data.minCount, calls.length));
+                        if (data.args !== undefined)
+                            checks.push((0, assertion_result_1.assertionCheck)('args', 'matching call arguments', calls.some(call => (0, node_util_1.isDeepStrictEqual)(call, data.args)), sensitive ? "[REDACTED]" : data.args, sensitive ? "[REDACTED]" : calls));
+                    }
+                    if (!closed)
+                        latest = (0, assertion_result_1.reportAssertion)('stub.expect', 'function double ' + JSON.stringify(data.name), checks, reporter, { status: 'running', timeout: limit, elapsed: Date.now() - started });
+                    return checks.every(check => check.status === 'passed');
+                }, limit, `function double ${data.name}`);
+                closed = true;
+                reporter?.({ ...latest, status: 'passed', elapsed: Date.now() - started });
+            }
+            catch (error) {
+                closed = true;
+                const result = { ...latest, status: 'failed', elapsed: Date.now() - started, reason: (0, assertion_result_1.diagnosticValue)(error instanceof Error ? error.message : String(error)) };
+                if (!result.checks.some(check => check.status === 'failed'))
+                    result.checks.push({ key: 'read', label: 'Recorded calls could be read', status: 'failed', reason: result.reason });
+                reporter?.(result);
+                throw new assertion_result_1.AssertionFailure(result);
+            }
             return;
         }
         throw new Error(`Unknown stub action: ${action}`);

package/dist/native/runtime.d.ts

@@ -1,3 +1,4 @@
+import type { AssertionResult } from '../reporting/assertion_result';
 import type { FlowstrideConfig } from '../types';
 import { WebAdapter } from '../adapters/web/playwright';
 import { NativeEvents } from './events';
@@ -5,6 +6,8 @@ export declare class NativeRuntime {
     private web;
     private config;
     readonly events: NativeEvents;
+    lastAssertion?: AssertionResult;
+    private assertionGeneration;
     private functions;
     private components;
     constructor(web: WebAdapter, config: FlowstrideConfig);

package/dist/native/runtime.js

@@ -18,6 +18,8 @@ class NativeRuntime {
     web;
     config;
     events;
+    lastAssertion;
+    assertionGeneration = 0;
     functions = new functions_1.NativeFunctions();
     components;
     constructor(web, config) {
@@ -27,6 +29,10 @@ class NativeRuntime {
         this.components = new components_1.NativeComponents(config);
     }
     async execute(command, input = {}) {
+        this.lastAssertion = undefined;
+        const generation = ++this.assertionGeneration;
+        const report = result => { if (generation === this.assertionGeneration)
+            this.lastAssertion = result; };
         const [area, action, extra] = command.split('.');
         if (!action || extra)
             throw new Error(`Unknown native command: flow.${command}`);
@@ -78,18 +84,18 @@ class NativeRuntime {
         if (area === 'assert') {
             if (action !== 'that')
                 throw new Error(`Unknown assertion action: ${action}`);
-            return (0, assertions_1.assertBrowser)(this.web.getPage(), input, this.config.timeout);
+            return (0, assertions_1.assertBrowser)(this.web.getPage(), input, this.config.timeout, report);
         }
         if (area === 'network')
-            return this.events.network(action, input);
+            return this.events.network(action, input, report);
         if (area === 'download')
-            return this.events.download(action, input);
+            return this.events.download(action, input, report);
         if (area === 'stub')
-            return this.functions.execute(this.web.getPage(), action, input, this.config.timeout);
+            return this.functions.execute(this.web.getPage(), action, input, this.config.timeout, report);
         if (area === 'component')
             return this.components.execute(this.web.getPage(), action, input);
         if (area === 'a11y')
-            return (0, accessibility_1.accessibility)(this.web.getPage(), this.config, action, input);
+            return (0, accessibility_1.accessibility)(this.web.getPage(), this.config, action, input, report);
         if (area === 'clock') {
             const clock = this.web.getPage().clock;
             if (action === 'install') {
@@ -149,6 +155,6 @@ class NativeRuntime {
         node_fs_1.default.writeFileSync(file, html, { mode: 0o600 });
         return file;
     }
-    async dispose() { await this.events.dispose(); await this.functions.dispose(); await this.components.dispose(); }
+    async dispose() { this.assertionGeneration++; this.lastAssertion = undefined; await this.events.dispose(); await this.functions.dispose(); await this.components.dispose(); }
 }
 exports.NativeRuntime = NativeRuntime;

package/dist/parser/assertion_contract.d.ts

@@ -0,0 +1,12 @@
+export declare const expectationTypes: Set<string>;
+export declare const apiAssertionConditions: Set<string>;
+export declare function validateExpectationType(type: unknown): void;
+/** Templates are checked after interpolation; literal thresholds fail at parse time. */
+export declare function validateResponseTimeThreshold(value: unknown, allowTemplate?: boolean): number | undefined;
+export declare function validateApiAssertions(assertions: unknown): asserts assertions is {
+    condition: string;
+    value: string;
+}[];
+/** And remains limited to assertions and existing custom assertion plugins. */
+export declare const nativeAssertionCommands: Set<string>;
+export declare function isAssertionStep(action: string, payload: any): boolean;

package/dist/parser/assertion_contract.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nativeAssertionCommands = exports.apiAssertionConditions = exports.expectationTypes = void 0;
+exports.validateExpectationType = validateExpectationType;
+exports.validateResponseTimeThreshold = validateResponseTimeThreshold;
+exports.validateApiAssertions = validateApiAssertions;
+exports.isAssertionStep = isAssertionStep;
+exports.expectationTypes = new Set([
+    'status', 'responseTime', 'resBody', 'resHeader', 'cookie',
+    'visible', 'text', 'value', 'attribute', 'transcript',
+]);
+exports.apiAssertionConditions = new Set([
+    'equals', 'contains', 'to.be', 'to.not.be', 'is', 'is.not',
+    'type.of', 'format', 'matches', 'lessthan', 'greaterthan',
+    'length', 'length.greaterthan', 'length.lessthan',
+    'includes', 'does.not.include', 'has.key', 'does.not.have.key',
+    'is.empty', 'not.empty',
+]);
+function validateExpectationType(type) {
+    if (typeof type !== 'string' || !exports.expectationTypes.has(type)) {
+        throw new Error(`Unsupported flow.expect modifier: ${String(type)}.`);
+    }
+}
+/** Templates are checked after interpolation; literal thresholds fail at parse time. */
+function validateResponseTimeThreshold(value, allowTemplate = false) {
+    if (allowTemplate && typeof value === 'string' &&
+        /\{\{env\.[^}]+\}\}|(?:@|\$)(?:global\[[^\]]+\]|[a-zA-Z_]\w*)/.test(value))
+        return;
+    if ((typeof value !== 'string' && typeof value !== 'number') ||
+        (typeof value === 'string' && value.trim() === '')) {
+        throw new Error('API responseTime threshold must be a finite nonnegative number.');
+    }
+    const threshold = Number(value);
+    if (!Number.isFinite(threshold) || threshold < 0) {
+        throw new Error('API responseTime threshold must be a finite nonnegative number.');
+    }
+    return threshold;
+}
+function validateApiAssertions(assertions) {
+    if (!Array.isArray(assertions) || assertions.length === 0) {
+        throw new Error('API assertion requires at least one supported condition.');
+    }
+    for (const assertion of assertions) {
+        if (!assertion || !exports.apiAssertionConditions.has(assertion.condition)) {
+            throw new Error(`Unsupported API assertion condition: ${String(assertion?.condition)}.`);
+        }
+        if (!['is.empty', 'not.empty'].includes(assertion.condition) && typeof assertion.value !== 'string') {
+            throw new Error(`API assertion ${assertion.condition} requires an expected string.`);
+        }
+    }
+}
+/** And remains limited to assertions and existing custom assertion plugins. */
+exports.nativeAssertionCommands = new Set(['assert.that', 'network.expect', 'download.expect', 'stub.expect', 'a11y.scan', 'a11y.match']);
+function isAssertionStep(action, payload) {
+    return action === 'expect' || action === 'plugin' || action === 'native' && exports.nativeAssertionCommands.has(payload?.pluginMethod);
+}

package/dist/parser/parser.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Parser = void 0;
+const assertion_contract_1 = require("./assertion_contract");
 const lexer_1 = require("./lexer");
 class Parser {
     tokens;
@@ -99,8 +100,8 @@ class Parser {
                 declarations.push(this.parseDeclaration());
             }
             else if (token.type === lexer_1.TokenType.BLOCK) {
-                if (isLocked)
-                    throw new Error(`Line ${token.line}: Terminal Lock Violation. No steps allowed after Then.`);
+                if (isLocked && token.value.toLowerCase().replace(/^stop\./, '') !== 'and')
+                    throw new Error(`Line ${token.line}: Terminal Lock Violation. Only assertion And blocks are allowed after Then.`);
                 const blockToken = this.advance();
                 let rawBlockType = blockToken.value.toLowerCase();
                 if (rawBlockType.startsWith("stop.")) {
@@ -149,7 +150,7 @@ class Parser {
             }
             else if (token.type === lexer_1.TokenType.COMMAND ||
                 token.type === lexer_1.TokenType.ALIAS_COMMAND) {
-                if (isLocked && currentBlockType !== "then") {
+                if (isLocked && currentBlockType !== "then" && currentBlockType !== "and") {
                     throw new Error(`Line ${token.line}: Terminal Lock Violation.`);
                 }
                 const step = this.parseCommand();
@@ -157,8 +158,7 @@ class Parser {
                     step.isStop = true;
                 }
                 if (currentBlockType === "and" &&
-                    step.action !== "expect" &&
-                    step.action !== "plugin") {
+                    !(0, assertion_contract_1.isAssertionStep)(step.action, step.payload)) {
                     throw new Error(`Line ${token.line}: And blocks are strictly for assertions or custom assertion plugins.`);
                 }
                 steps.push(step);
@@ -371,7 +371,13 @@ class Parser {
                 const viaToken = this.consume(lexer_1.TokenType.PREPOSITION, 'Expected "via"');
                 if (viaToken.value.toLowerCase() !== "via")
                     throw new Error(`Line ${viaToken.line}: Expected 'via'`);
-                payload.verb = this.consume(lexer_1.TokenType.COMMAND, "Expected API verb (e.g. POST)").value.toLowerCase();
+                payload.verb = this.consume(lexer_1.TokenType.COMMAND, "Expected API verb (e.g. POST)").value.toLowerCase().replace(/^flow\./, '');
+                if (!['get', 'post', 'put', 'patch', 'delete'].includes(payload.verb)) {
+                    throw new Error('Authentication refresh requires an HTTP verb: get, post, put, patch or delete.');
+                }
+                if (!['401', '403'].includes(payload.targetStatus)) {
+                    throw new Error('Authentication refresh status must be 401 or 403.');
+                }
                 payload.url = this.consume(lexer_1.TokenType.STRING, "Endpoint URL expected").value;
                 payload.headers = [];
                 this.parseApiModifiers(payload);
@@ -507,6 +513,7 @@ class Parser {
                 if (mod.toLowerCase() === "responsetime" && mod !== "responseTime") {
                     throw new Error(`Syntax Error on line ${modToken.line}: Invalid keyword '${mod}'. Flowstride uses strict camelCase. Did you mean 'responseTime'?`);
                 }
+                (0, assertion_contract_1.validateExpectationType)(mod);
                 payload.type = mod;
                 if (mod === "status") {
                     payload.statusCode = this.consume(lexer_1.TokenType.STRING, 'Status code expected (e.g., "200")').value;
@@ -517,6 +524,7 @@ class Parser {
                         throw new Error(`Line ${modToken.line}: Expected 'lessThan' after responseTime`);
                     }
                     payload.threshold = this.consume(lexer_1.TokenType.STRING, "Time threshold expected").value;
+                    (0, assertion_contract_1.validateResponseTimeThreshold)(payload.threshold, true);
                 }
                 else if (mod === "resBody" ||
                     mod === "resHeader" ||

package/dist/reporting/assertion_result.d.ts

@@ -0,0 +1,36 @@
+export type AssertionCheckStatus = 'passed' | 'failed' | 'not_evaluated' | 'running';
+export interface AssertionCheck {
+    key: string;
+    label: string;
+    status: AssertionCheckStatus;
+    expected?: string;
+    actual?: string;
+    reason?: string;
+    children?: AssertionCheck[];
+}
+export interface AssertionResult {
+    command: string;
+    target: string;
+    status: 'passed' | 'failed' | 'running' | 'not_evaluated';
+    checks: AssertionCheck[];
+    timeout?: number;
+    elapsed?: number;
+    reason?: string;
+    sourceFile?: string;
+    sourceLine?: number;
+    profile?: string;
+}
+export type AssertionReporter = (result: AssertionResult) => void;
+/** Diagnostic text is bounded data, including in terminals and exported reports. */
+export declare function diagnosticValue(value: unknown): string;
+export declare function assertionCheck(key: string, label: string, matched: boolean, expected?: unknown, actual?: unknown): AssertionCheck;
+export declare function assertionText(result: AssertionResult): string;
+export declare class AssertionFailure extends Error {
+    readonly assertion: AssertionResult;
+    constructor(assertion: AssertionResult);
+}
+export declare function reportAssertion(command: string, target: string, checks: AssertionCheck[], reporter?: AssertionReporter, metadata?: Partial<AssertionResult>): AssertionResult;
+export declare function requireAssertion(command: string, target: string, checks: AssertionCheck[], reporter?: AssertionReporter, metadata?: Partial<AssertionResult>): void;
+export declare function failedAssertion(result: AssertionResult | undefined, reason: string): AssertionResult | undefined;
+export declare function commandLabel(action: string, payload: any): string;
+export declare function unexecutedAssertion(action: string, payload: any, reason?: string): AssertionResult | undefined;

package/dist/reporting/assertion_result.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AssertionFailure = void 0;
+exports.diagnosticValue = diagnosticValue;
+exports.assertionCheck = assertionCheck;
+exports.assertionText = assertionText;
+exports.reportAssertion = reportAssertion;
+exports.requireAssertion = requireAssertion;
+exports.failedAssertion = failedAssertion;
+exports.commandLabel = commandLabel;
+exports.unexecutedAssertion = unexecutedAssertion;
+const redaction_1 = require("../security/redaction");
+/** Diagnostic text is bounded data, including in terminals and exported reports. */
+function diagnosticValue(value) {
+    let text;
+    try {
+        const safe = (0, redaction_1.redactPayload)(value);
+        text = typeof safe === 'string' ? safe : JSON.stringify(safe);
+    }
+    catch {
+        text = '[unavailable]';
+    }
+    if (text === undefined)
+        text = '(not observed)';
+    return text.replace(/[\x00-\x1f\x7f-\x9f]/g, c => '\\u' + c.charCodeAt(0).toString(16).padStart(4, '0')).slice(0, 1500);
+}
+function assertionCheck(key, label, matched, expected, actual) {
+    return { key, label, status: matched ? 'passed' : 'failed',
+        ...(expected === undefined ? {} : { expected: diagnosticValue(expected) }),
+        ...(actual === undefined ? {} : { actual: diagnosticValue(actual) }) };
+}
+function assertionText(result) {
+    const lines = [`${result.status === 'passed' ? '✔' : result.status === 'not_evaluated' ? '○' : result.status === 'running' ? '◌' : '✖'} flow.${result.command}`];
+    const visit = (check, depth) => {
+        const prefix = '  '.repeat(depth);
+        lines.push(`${prefix}${check.status === 'passed' ? '✔' : check.status === 'failed' ? '✖' : '○'} ${diagnosticValue(check.label)}${check.status === 'not_evaluated' ? ' — Not evaluated' : ''}`);
+        if (check.status === 'failed') {
+            if (check.expected !== undefined)
+                lines.push(`${prefix}    Expected: ${diagnosticValue(check.expected)}`);
+            if (check.actual !== undefined)
+                lines.push(`${prefix}    Actual: ${diagnosticValue(check.actual)}`);
+            if (check.reason)
+                lines.push(`${prefix}    Reason: ${diagnosticValue(check.reason)}`);
+        }
+        for (const child of check.children || [])
+            visit(child, depth + 1);
+    };
+    for (const check of result.checks)
+        visit(check, 1);
+    if (result.status === 'failed' && result.reason)
+        lines.push(`  Reason: ${diagnosticValue(result.reason)}`);
+    if (result.timeout !== undefined)
+        lines.push(`  Timeout: ${result.timeout} ms; elapsed: ${result.elapsed || 0} ms`);
+    if (result.sourceFile)
+        lines.push(`  Location: ${diagnosticValue(result.sourceFile)}${result.sourceLine ? ':' + result.sourceLine : ''}`);
+    if (result.profile)
+        lines.push(`  Profile: ${diagnosticValue(result.profile)}`);
+    return lines.join('\n');
+}
+class AssertionFailure extends Error {
+    assertion;
+    constructor(assertion) {
+        super(`${assertion.reason?.includes('timed out') ? 'Assertion timed out' : 'Assertion failed'}: ${assertion.target}\n${assertionText(assertion)}`);
+        this.assertion = assertion;
+        this.name = 'AssertionFailure';
+    }
+}
+exports.AssertionFailure = AssertionFailure;
+function reportAssertion(command, target, checks, reporter, metadata = {}) {
+    const result = { command, target, status: checks.some(check => check.status === 'failed') ? 'failed' : 'passed', checks, ...metadata };
+    reporter?.(result);
+    return result;
+}
+function requireAssertion(command, target, checks, reporter, metadata = {}) {
+    const result = reportAssertion(command, target, checks, reporter, metadata);
+    if (result.status === 'failed')
+        throw new AssertionFailure(result);
+}
+function failedAssertion(result, reason) {
+    if (!result)
+        return;
+    const copy = structuredClone(result);
+    copy.status = 'failed';
+    copy.reason ||= diagnosticValue(reason.split("\n")[0]);
+    if (/exceeded|timed out|timeout/i.test(reason))
+        copy.elapsed = Math.max(copy.elapsed || 0, copy.timeout || 0);
+    for (const check of copy.checks)
+        if (check.status === 'running')
+            check.status = 'failed';
+    if (!copy.checks.some(check => check.status === 'failed'))
+        copy.checks.push({ key: 'completion', label: 'Command completed within its deadline', status: 'failed', reason: diagnosticValue(reason) });
+    return copy;
+}
+function commandLabel(action, payload) {
+    return action === 'native' && typeof payload?.pluginMethod === 'string' ? 'flow.' + payload.pluginMethod
+        : action === 'plugin' && typeof payload?.pluginAlias === 'string' ? payload.pluginAlias + '.' + payload.pluginMethod : action;
+}
+function unexecutedAssertion(action, payload, reason = 'A previous required step failed.') {
+    if (action !== 'native' || !['assert.that', 'network.expect', 'download.expect', 'stub.expect', 'a11y.scan', 'a11y.match', 'a11y.snapshot'].includes(payload?.pluginMethod))
+        return;
+    const data = payload.data && typeof payload.data === 'object' ? payload.data : {};
+    const fields = payload.pluginMethod === 'assert.that' ? ['role', 'name', 'selector', 'condition'] : Object.keys(data).filter(key => !['timeout', 'name'].includes(key));
+    return { command: payload.pluginMethod, target: payload.pluginMethod, status: 'not_evaluated', reason, checks: fields.slice(0, 100).map(key => ({ key, label: key + ': ' + diagnosticValue(data[key]), status: 'not_evaluated', reason })) };
+}

package/dist/reporting/pdf_generator.js

@@ -34,9 +34,16 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PdfGenerator = void 0;
+const assertion_result_1 = require("./assertion_result");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const playwright_1 = require("playwright");
+const step_status_1 = require("./step_status");
+function escapeHtml(value) {
+    return String(value ?? "").replace(/[&<>"']/g, (character) => ({
+        "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;",
+    })[character]);
+}
 class PdfGenerator {
     async generateTestcasePdf(data, customOutputPath) {
         let outputDir = "";
@@ -79,7 +86,7 @@ class PdfGenerator {
         else if (Array.isArray(data)) {
             scenariosToProcess = data;
         }
-        const groupedScenarios = {};
+        const groupedScenarios = Object.create(null);
         scenariosToProcess.forEach((scenario) => {
             const key = scenario.fileName || "General";
             if (!groupedScenarios[key])
@@ -95,31 +102,29 @@ class PdfGenerator {
             let fileRows = "";
             flatSteps.forEach((step, idx) => {
                 totalSteps++;
-                const status = (step.status || "PENDING").toUpperCase();
-                const isSuccess = status === "PASS" || status === "PASSED" || status === "SUCCESS";
-                const isFail = status === "FAILED" || status === "FAIL";
-                if (isSuccess)
+                const result = (0, step_status_1.stepStatusPresentation)(step.status);
+                if (result.isPassed)
                     passedSteps++;
-                else if (isFail)
+                else if (result.isFailed)
                     failedSteps++;
-                const color = isSuccess ? "#10b981" : isFail ? "#ef4444" : "#64748b";
-                const actualResultText = isFail
-                    ? "Validation Failed"
-                    : "Action verified successfully.";
-                const actualResultColor = isFail ? "#ef4444" : "#64748b";
+                const actionText = step.commandLabel || step.command || step.action || "-";
+                const expectedText = step.description
+                    ? `${step.type ? `${step.type} ` : ""}${step.description}`
+                    : step.expected || "-";
+                const actualResultColor = result.isFailed ? "#ef4444" : "#64748b";
                 fileRows += `
-          <tr>
+          <tr data-step-status="${result.status}">
             <td style="padding: 16px 14px; border-bottom: 1px solid #e2e8f0; color: #64748b; font-weight: 500; width: 50px;">${idx + 1}</td>
-            <td style="padding: 16px 14px; border-bottom: 1px solid #e2e8f0; font-weight: 700; color: #1e293b;">${step.command || "action"}</td>
-            <td style="padding: 16px 14px; border-bottom: 1px solid #e2e8f0; color: #475569; font-style: italic;">${step.type || ""} ${step.description || "-"}</td>
-            <td style="padding: 16px 14px; border-bottom: 1px solid #e2e8f0; color: ${actualResultColor};">${actualResultText}</td>
-            <td style="padding: 16px 14px; border-bottom: 1px solid #e2e8f0; font-weight: 900; font-size: 10px; color: ${color};">${status}</td>
+            <td style="padding: 16px 14px; border-bottom: 1px solid #e2e8f0; font-weight: 700; color: #1e293b;">${escapeHtml(actionText)}</td>
+            <td style="padding: 16px 14px; border-bottom: 1px solid #e2e8f0; color: #475569; font-style: italic;">${escapeHtml(expectedText)}</td>
+            <td style="padding: 16px 14px; border-bottom: 1px solid #e2e8f0; color: ${actualResultColor};">${step.assertion ? `<pre style="white-space:pre-wrap;overflow-wrap:anywhere">${escapeHtml((0, assertion_result_1.assertionText)(step.assertion))}</pre>` : step.error ? `<pre style="white-space:pre-wrap;overflow-wrap:anywhere">${escapeHtml(step.error)}</pre>` : result.actualResult}</td>
+            <td style="padding: 16px 14px; border-bottom: 1px solid #e2e8f0; font-weight: 900; font-size: 10px; color: ${result.color};">${result.label}</td>
           </tr>
         `;
             });
             tablesHtml += `
         <div class="file-separator">
-          <span>📄 ${fileName.toUpperCase()}</span>
+          <span>📄 ${escapeHtml(fileName.toUpperCase())}</span>
         </div>
         <table>
           <thead>
@@ -164,15 +169,15 @@ class PdfGenerator {
         </div>
         <div class="summary">
           <div class="stat-box">
-            <div class="stat-value" style="color: #1e293b;">${totalSteps}</div>
+            <div class="stat-value" data-report-count="total" style="color: #1e293b;">${totalSteps}</div>
             <div style="font-size:10px;color:#64748b;text-transform:uppercase;margin-top:4px;font-weight:700;">Total Steps</div>
           </div>
           <div class="stat-box">
-            <div class="stat-value" style="color:#10b981;">${passedSteps}</div>
+            <div class="stat-value" data-report-count="passed" style="color:#10b981;">${passedSteps}</div>
             <div style="font-size:10px;color:#64748b;text-transform:uppercase;margin-top:4px;font-weight:700;">Passed</div>
           </div>
           <div class="stat-box">
-            <div class="stat-value" style="color:#ef4444;">${failedSteps}</div>
+            <div class="stat-value" data-report-count="failed" style="color:#ef4444;">${failedSteps}</div>
             <div style="font-size:10px;color:#64748b;text-transform:uppercase;margin-top:4px;font-weight:700;">Failed</div>
           </div>
         </div>