flowstride 1.0.18 → 1.0.20-rc.2

package/dist/game/bridge.d.ts

@@ -0,0 +1,13 @@
+/** Register observable state and explicitly test-only fixtures in a browser game. */
+export interface GameBridgeOptions {
+    readState?: () => unknown;
+    locate?: (id: string) => {
+        x: number;
+        y: number;
+    };
+    testMode?: boolean;
+    fixtures?: Record<string, (data: unknown) => unknown>;
+}
+export declare function registerGame(options: GameBridgeOptions): {
+    dispose(): void;
+};

package/dist/game/bridge.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerGame = registerGame;
+function registerGame(options) {
+    if (typeof window === 'undefined')
+        throw new Error('Game bridges must be registered in the browser.');
+    if (typeof options.readState !== 'function' && typeof options.locate !== 'function')
+        throw new Error('A game bridge requires readState or locate.');
+    const bridge = { readState: options.readState, locate: options.locate,
+        testMode: options.testMode === true,
+        fixtures: options.testMode === true ? options.fixtures || {} : {} };
+    window.__FLOWSTRIDE_GAME__ = bridge;
+    return { dispose() { if (window.__FLOWSTRIDE_GAME__ === bridge)
+            delete window.__FLOWSTRIDE_GAME__; } };
+}

package/dist/game/sdk.d.ts

@@ -0,0 +1,27 @@
+import type { Page } from 'playwright';
+import type { FlowstrideConfig } from '../types';
+export declare class GameSDK {
+    private page;
+    private config;
+    private snapshots;
+    private states;
+    constructor(page: () => Page, config: FlowstrideConfig);
+    private timeout;
+    private bridgeReady;
+    private point;
+    private touch;
+    tap(options: any): Promise<void>;
+    drag(options: any): Promise<void>;
+    swipe(options: any): Promise<void>;
+    key(options: any): Promise<void>;
+    checkpoint(options: any): Promise<string>;
+    snapshot(options: any): Promise<void>;
+    private difference;
+    expectVisual(options: any): Promise<number>;
+    state(options?: any): Promise<any>;
+    expectState(options: any): Promise<void>;
+    snapshotState(options: any): Promise<void>;
+    expectPreserved(options: any): Promise<void>;
+    fixture(options: any): Promise<any>;
+    select(options: any): Promise<void>;
+}

package/dist/game/sdk.js

@@ -0,0 +1,255 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GameSDK = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const strict_1 = __importDefault(require("node:assert/strict"));
+const promises_1 = require("node:timers/promises");
+class GameSDK {
+    page;
+    config;
+    snapshots = new Map();
+    states = new Map();
+    constructor(page, config) {
+        this.page = page;
+        this.config = config;
+    }
+    timeout() { return this.config.timeout; }
+    async bridgeReady(method) {
+        await this.page().waitForFunction(method => {
+            const bridge = window.__FLOWSTRIDE_GAME__;
+            return !!bridge && (!method || typeof bridge[method] === 'function');
+        }, method, { timeout: this.timeout() });
+    }
+    async point(options) {
+        const canvas = this.page().locator(options.canvas || 'canvas');
+        await canvas.waitFor({ state: 'visible', timeout: this.timeout() });
+        const box = await canvas.boundingBox();
+        if (!box || box.width <= 0 || box.height <= 0)
+            throw new Error('Canvas has no usable bounds.');
+        let { x, y } = options;
+        if (!Number.isFinite(x) || !Number.isFinite(y))
+            throw new Error('Canvas coordinates must be finite.');
+        if ((options.unit || 'relative') === 'relative') {
+            x *= box.width;
+            y *= box.height;
+        }
+        else if (options.unit !== 'pixels')
+            throw new Error('Coordinate unit must be relative or pixels.');
+        if (x < 0 || x >= box.width || y < 0 || y >= box.height)
+            throw new Error('Canvas coordinate is outside its bounds.');
+        const point = { x: box.x + x, y: box.y + y };
+        await canvas.evaluate((element, point) => {
+            if (document.elementFromPoint(point.x, point.y) !== element)
+                throw new Error('Canvas target is covered or outside the viewport.');
+        }, point);
+        return point;
+    }
+    touch(options) {
+        const input = options.input || (this.config.device === 'desktop' ? 'mouse' : 'touch');
+        if (!['mouse', 'touch'].includes(input))
+            throw new Error('input must be mouse or touch.');
+        return input === 'touch';
+    }
+    async tap(options) {
+        const point = await this.point(options);
+        if (this.touch(options))
+            await this.page().touchscreen.tap(point.x, point.y);
+        else
+            await this.page().mouse.click(point.x, point.y);
+    }
+    async drag(options) {
+        const from = await this.point({ ...options, ...options.from });
+        const to = await this.point({ ...options, ...options.to });
+        const duration = options.duration ?? 250;
+        if (!Number.isFinite(duration) || duration < 0 || duration > this.timeout())
+            throw new Error('Invalid gesture duration.');
+        if (this.touch(options)) {
+            const session = await this.page().context().newCDPSession(this.page());
+            try {
+                await session.send('Input.dispatchTouchEvent', { type: 'touchStart', touchPoints: [from] });
+                for (let i = 1; i <= 10; i++) {
+                    await session.send('Input.dispatchTouchEvent', { type: 'touchMove', touchPoints: [{ x: from.x + (to.x - from.x) * i / 10, y: from.y + (to.y - from.y) * i / 10 }] });
+                    await (0, promises_1.setTimeout)(duration / 10);
+                }
+            }
+            finally {
+                try {
+                    await session.send('Input.dispatchTouchEvent', { type: 'touchEnd', touchPoints: [] });
+                }
+                finally {
+                    await session.detach();
+                }
+            }
+        }
+        else {
+            await this.page().mouse.move(from.x, from.y);
+            await this.page().mouse.down();
+            try {
+                for (let i = 1; i <= 10; i++) {
+                    await this.page().mouse.move(from.x + (to.x - from.x) * i / 10, from.y + (to.y - from.y) * i / 10);
+                    await (0, promises_1.setTimeout)(duration / 10);
+                }
+            }
+            finally {
+                await this.page().mouse.up();
+            }
+        }
+    }
+    async swipe(options) { return this.drag({ ...options, input: 'touch' }); }
+    async key(options) {
+        const key = typeof options === 'string' ? options : options.key;
+        const duration = typeof options === 'string' ? 0 : options.duration ?? 0;
+        if (typeof key !== 'string' || !key || !Number.isFinite(duration) || duration < 0 || duration > this.timeout())
+            throw new Error('Invalid key or duration.');
+        const keys = key === '+' ? [key] : key.split('+');
+        const pressed = [];
+        try {
+            for (const part of keys) {
+                await this.page().keyboard.down(part);
+                pressed.push(part);
+            }
+            if (duration)
+                await (0, promises_1.setTimeout)(duration);
+        }
+        finally {
+            const released = await Promise.allSettled(pressed.reverse().map(part => this.page().keyboard.up(part)));
+            if (released.some(result => result.status === 'rejected'))
+                throw new Error('Failed to release game keyboard input.');
+        }
+    }
+    async checkpoint(options) {
+        const name = typeof options === 'string' ? options : options.name;
+        if (typeof name !== 'string' || !/^[a-zA-Z0-9_-]+$/.test(name))
+            throw new Error('Checkpoint name must use letters, digits, underscores or hyphens.');
+        const directory = this.config.artifactsDir || node_path_1.default.resolve('flowstride-artifacts');
+        node_fs_1.default.mkdirSync(directory, { recursive: true });
+        const prefix = this.config.testFile ? this.config.testFile.replace(/[^a-zA-Z0-9_.-]/g, '_') + '-' : '';
+        const file = node_path_1.default.join(directory, prefix + name + '.png');
+        if (typeof options === 'object' && options.canvas)
+            await this.page().locator(options.canvas).screenshot({ path: file });
+        else
+            await this.page().screenshot({ path: file });
+        return file;
+    }
+    async snapshot(options) {
+        if (!options?.name || typeof options.name !== 'string')
+            throw new Error('snapshot requires a name.');
+        const buffer = await this.page().locator(options.canvas || 'canvas').screenshot();
+        this.snapshots.set(options.name, buffer);
+    }
+    async difference(before, after) {
+        return this.page().evaluate(async ({ before, after }) => {
+            async function pixels(data) {
+                const image = new Image();
+                image.src = 'data:image/png;base64,' + data;
+                await image.decode();
+                const canvas = document.createElement('canvas');
+                canvas.width = image.width;
+                canvas.height = image.height;
+                const context = canvas.getContext('2d');
+                context.drawImage(image, 0, 0);
+                return { data: context.getImageData(0, 0, canvas.width, canvas.height).data, width: canvas.width, height: canvas.height };
+            }
+            const a = await pixels(before), b = await pixels(after);
+            if (a.width !== b.width || a.height !== b.height)
+                throw new Error('Visual comparison dimensions differ.');
+            let changed = 0;
+            for (let i = 0; i < a.data.length; i += 4)
+                if (Math.abs(a.data[i] - b.data[i]) + Math.abs(a.data[i + 1] - b.data[i + 1]) + Math.abs(a.data[i + 2] - b.data[i + 2]) + Math.abs(a.data[i + 3] - b.data[i + 3]) > 60)
+                    changed++;
+            return changed / (a.width * a.height);
+        }, { before: before.toString('base64'), after: after.toString('base64') });
+    }
+    async expectVisual(options) {
+        let before;
+        if (options.baseline)
+            before = node_fs_1.default.readFileSync(node_path_1.default.resolve(options.baseline));
+        else
+            before = this.snapshots.get(options.name);
+        if (!before)
+            throw new Error('Visual snapshot or baseline is missing.');
+        const ratio = await this.difference(before, await this.page().locator(options.canvas || 'canvas').screenshot());
+        const min = options.minChange ?? 0, max = options.maxChange ?? (options.minChange === undefined ? 0 : 1);
+        if (![min, max].every(Number.isFinite) || min < 0 || max > 1 || min > max)
+            throw new Error('Visual change thresholds must satisfy 0 <= min <= max <= 1.');
+        (0, strict_1.default)(ratio >= min && ratio <= max, `Canvas changed by ${ratio}; expected between ${min} and ${max}.`);
+        return ratio;
+    }
+    async state(options = {}) {
+        await this.bridgeReady('readState');
+        return this.page().evaluate(async (field) => {
+            const bridge = window.__FLOWSTRIDE_GAME__;
+            if (!bridge?.readState)
+                throw new Error('Game state bridge is not registered.');
+            let value = await bridge.readState();
+            for (const part of field?.split('.') || []) {
+                if (['__proto__', 'constructor', 'prototype'].includes(part) || value == null || !Object.hasOwn(value, part))
+                    throw new Error(`Game state field is unavailable: ${field}`);
+                value = value[part];
+            }
+            return value;
+        }, options.path);
+    }
+    async expectState(options) {
+        if (!options || !Object.hasOwn(options, 'equals'))
+            throw new Error('expectState requires equals.');
+        const deadline = Date.now() + this.timeout();
+        let actual;
+        let observed = false;
+        do {
+            try {
+                actual = await this.state(options);
+                observed = true;
+                strict_1.default.deepStrictEqual(actual, options.equals);
+                return;
+            }
+            catch { }
+            await (0, promises_1.setTimeout)(50);
+        } while (Date.now() < deadline);
+        if (!observed)
+            throw new Error('Game state was not readable before the timeout.');
+        strict_1.default.deepStrictEqual(actual, options.equals, `Game state did not reach the expected value: ${options.path || 'root'}`);
+    }
+    async snapshotState(options) {
+        if (!options?.name)
+            throw new Error('snapshotState requires name.');
+        this.states.set(options.name, { path: options.path, value: await this.state(options) });
+    }
+    async expectPreserved(options) {
+        if (!this.states.has(options.name))
+            throw new Error('State snapshot missing.');
+        const snapshot = this.states.get(options.name);
+        strict_1.default.deepStrictEqual(await this.state({ path: options.path ?? snapshot.path }), snapshot.value, 'Game state changed.');
+    }
+    async fixture(options) {
+        await this.bridgeReady();
+        return this.page().evaluate(async ({ name, data }) => {
+            const bridge = window.__FLOWSTRIDE_GAME__;
+            if (!bridge?.testMode || !Object.hasOwn(bridge.fixtures || {}, name) || typeof bridge.fixtures[name] !== 'function')
+                throw new Error('Named fixture is unavailable in this environment.');
+            return bridge.fixtures[name](data);
+        }, { name: options.name, data: options.data });
+    }
+    async select(options) {
+        if (typeof options?.id !== 'string' || !options.id.trim())
+            throw new Error('select requires a nonempty game object ID.');
+        await this.bridgeReady('locate');
+        const point = await this.page().evaluate(async (id) => {
+            const bridge = window.__FLOWSTRIDE_GAME__;
+            if (!bridge?.locate)
+                throw new Error('Game object bridge is not registered.');
+            return bridge.locate(id);
+        }, options.id);
+        if (!Number.isFinite(point.x) || !Number.isFinite(point.y))
+            throw new Error('Invalid object coordinates.');
+        if (this.touch(options))
+            await this.page().touchscreen.tap(point.x, point.y);
+        else
+            await this.page().mouse.click(point.x, point.y);
+    }
+}
+exports.GameSDK = GameSDK;

package/dist/game/three-bridge.d.ts

@@ -0,0 +1,18 @@
+/** Browser-side integration. Import from flowstride/dist/game/three-bridge.
+ * The application supplies its own Three.js constructors; no second Three.js
+ * runtime, scene reconstruction, renderer or animation loop is created. */
+export interface ThreeGameBridgeOptions {
+    scene: any;
+    camera: any;
+    canvas: HTMLCanvasElement;
+    Vector3: new (...args: any[]) => any;
+    Raycaster: new (...args: any[]) => any;
+    objects?: Record<string, any>;
+    readState?: () => unknown;
+    testMode?: boolean;
+    fixtures?: Record<string, (data: unknown) => unknown>;
+}
+export declare function registerThreeGame(options: ThreeGameBridgeOptions): {
+    registerObject(id: string, object: any): void;
+    dispose(): void;
+};

package/dist/game/three-bridge.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerThreeGame = registerThreeGame;
+function registerThreeGame(options) {
+    if (!(options.canvas instanceof HTMLCanvasElement))
+        throw new Error('A live game canvas is required.');
+    const objects = new Map(Object.entries(options.objects || {}));
+    const locate = (id) => {
+        let object = objects.get(id);
+        if (!object)
+            options.scene.traverse((candidate) => { if (candidate.userData?.flowstrideId === id) {
+                if (object)
+                    throw new Error(`Duplicate game object ID: ${id}`);
+                object = candidate;
+            } });
+        if (!object)
+            throw new Error(`Game object not found: ${id}`);
+        let cursor = object;
+        while (cursor) {
+            if (cursor.visible === false)
+                throw new Error(`Game object is hidden: ${id}`);
+            cursor = cursor.parent;
+        }
+        options.scene.updateMatrixWorld(true);
+        options.camera.updateMatrixWorld(true);
+        options.camera.updateProjectionMatrix();
+        const local = object.userData?.flowstridePickPoint;
+        const point = local ? object.localToWorld(new options.Vector3(...local)) : object.getWorldPosition(new options.Vector3());
+        point.project(options.camera);
+        if (![point.x, point.y, point.z].every(Number.isFinite) || Math.abs(point.x) > 1 || Math.abs(point.y) > 1 || Math.abs(point.z) > 1)
+            throw new Error(`Game object is outside the camera: ${id}`);
+        const ray = new options.Raycaster();
+        ray.layers.mask = options.camera.layers.mask;
+        ray.setFromCamera({ x: point.x, y: point.y }, options.camera);
+        const hits = ray.intersectObjects(options.scene.children, true);
+        const front = hits.find((hit) => { let node = hit.object; while (node) {
+            if (node.visible === false)
+                return false;
+            node = node.parent;
+        } return true; });
+        cursor = front?.object;
+        while (cursor && cursor !== object)
+            cursor = cursor.parent;
+        if (!cursor)
+            throw new Error(`Game object is occluded or not pickable: ${id}`);
+        const rect = options.canvas.getBoundingClientRect();
+        const x = rect.left + (point.x + 1) * rect.width / 2, y = rect.top + (1 - point.y) * rect.height / 2;
+        if (!rect.width || !rect.height || x < 0 || y < 0 || x >= innerWidth || y >= innerHeight || document.elementFromPoint(x, y) !== options.canvas)
+            throw new Error(`Game object is covered or outside the viewport: ${id}`);
+        return { x, y };
+    };
+    const bridge = { locate, readState: options.readState, testMode: options.testMode === true,
+        fixtures: options.testMode === true ? options.fixtures || {} : {} };
+    window.__FLOWSTRIDE_GAME__ = bridge;
+    return { registerObject(id, object) { if (!id || objects.has(id))
+            throw new Error('Game object ID must be unique and nonempty.'); objects.set(id, object); },
+        dispose() { if (window.__FLOWSTRIDE_GAME__ === bridge)
+            delete window.__FLOWSTRIDE_GAME__; } };
+}

package/dist/parser/lexer.js

@@ -331,6 +331,10 @@ class Lexer {
                     "img",
                     "burger",
                     "hamburger",
+                    "table",
+                    "tr",
+                    "th",
+                    "td",
                 ].includes(lowerIdent)) {
                     tokens.push({
                         type: TokenType.ELEMENT,

package/dist/parser/parser.js

@@ -319,11 +319,27 @@ class Parser {
                     extTarget !== "reqHeader") {
                     throw new Error(`Syntax Error on line ${extTargetToken.line}: Invalid keyword '${extTarget}'. Flowstride uses strict camelCase. Did you mean 'reqHeader'?`);
                 }
-                if (!["resBody", "resHeader", "cookie"].includes(extTarget)) {
-                    throw new Error(`Line ${extTargetToken.line}: Expected 'resBody', 'resHeader', or 'cookie' after extract`);
+                if (![
+                    "resBody",
+                    "resHeader",
+                    "cookie",
+                    "text",
+                    "value",
+                    "attribute",
+                ].includes(extTarget)) {
+                    throw new Error(`Line ${extTargetToken.line}: Expected 'resBody', 'resHeader', 'cookie', 'text', 'value', or 'attribute' after extract`);
                 }
                 payload.target = extTarget;
-                payload.jsonPath = this.consume(lexer_1.TokenType.STRING, "JSONPath or Key expected").value;
+                if (["resBody", "resHeader", "cookie"].includes(extTarget)) {
+                    payload.jsonPath = this.consume(lexer_1.TokenType.STRING, "JSONPath or Key expected").value;
+                }
+                else {
+                    this.consumeOptionalElement(payload);
+                    payload.selector = this.parseSmartSelectorPayload();
+                    if (extTarget === "attribute") {
+                        payload.attribute = this.consume(lexer_1.TokenType.STRING, "Attribute name expected").value;
+                    }
+                }
                 const asToken = this.advance();
                 if (asToken.value.toLowerCase() !== "as") {
                     throw new Error(`Line ${asToken.line}: Expected 'as' after extraction target`);

package/dist/runner/flow_orchestrator.d.ts

@@ -4,6 +4,8 @@ export declare class FlowOrchestrator {
     private worker;
     private workerCount;
     private config?;
+    static readonly nativeCIProtocol = 1;
+    readonly nativeEventProtocol = 1;
     private wss;
     private httpServer;
     private globalTestScenarios;
@@ -13,6 +15,8 @@ export declare class FlowOrchestrator {
     constructor(worker: FlowWorker, workerCount?: number, config?: FlowstrideConfig | undefined);
     private forwardToDashboard;
     private executeTestRun;
-    start(targetPath: string): Promise<void>;
+    start(targetPath: string): Promise<boolean>;
+    abort(): void;
+    close(): Promise<void>;
     private handleExportPdfRequest;
 }

package/dist/runner/flow_orchestrator.js

@@ -48,6 +48,8 @@ class FlowOrchestrator {
     worker;
     workerCount;
     config;
+    static nativeCIProtocol = 1;
+    nativeEventProtocol = 1;
     wss = null;
     httpServer = null;
     globalTestScenarios = [];
@@ -64,6 +66,7 @@ class FlowOrchestrator {
         });
     }
     forwardToDashboard(type, payload) {
+        this.config?.onRunEvent?.({ type, payload });
         if (this.wss) {
             this.wss.clients.forEach((client) => {
                 if (client.readyState === 1)
@@ -76,10 +79,18 @@ class FlowOrchestrator {
         let filesToProcess = [];
         const stats = fs.statSync(targetPath);
         if (stats.isDirectory()) {
-            filesToProcess = fs
+            const allFlowFiles = fs
                 .readdirSync(targetPath)
-                .filter((f) => f.endsWith(".flow"))
+                .filter((f) => f.endsWith(".flow"));
+            const priorityQueue = allFlowFiles
+                .filter((f) => f.endsWith(".first.flow"))
+                .sort()
                 .map((f) => path.join(targetPath, f));
+            const standardQueue = allFlowFiles
+                .filter((f) => !f.endsWith(".first.flow"))
+                .sort()
+                .map((f) => path.join(targetPath, f));
+            filesToProcess = [...priorityQueue, ...standardQueue];
         }
         else {
             filesToProcess = [targetPath];
@@ -103,10 +114,14 @@ class FlowOrchestrator {
         this.worker.on("worker_event", listener);
         await this.worker.runBatch(filesToProcess);
         this.worker.off("worker_event", listener);
-        this.forwardToDashboard("RUN_COMPLETE", { status: "success" });
+        const passed = ![...this.stepStatusRegistry.values()].some(status => ['failed', 'running', 'not_tested'].includes(status));
+        this.forwardToDashboard("RUN_COMPLETE", { status: passed ? 'success' : 'failed' });
+        return passed;
     }
     async start(targetPath) {
         try {
+            if (this.config?.ci)
+                return await this.executeTestRun(targetPath);
             this.httpServer = http.createServer((req, res) => {
                 res.setHeader("Access-Control-Allow-Origin", "*");
                 if (req.url && req.url.startsWith("/videos/")) {
@@ -304,8 +319,8 @@ class FlowOrchestrator {
                         else {
                             console.log(chalk_1.default.gray("[Dashboard]: Headless mode active. Bypassing UI auto-launch..."));
                         }
-                        await this.executeTestRun(targetPath);
-                        resolve(undefined);
+                        const result = await this.executeTestRun(targetPath);
+                        resolve(result);
                     }
                     catch (err) {
                         reject(err);
@@ -317,11 +332,20 @@ class FlowOrchestrator {
             throw e;
         }
     }
+    abort() {
+        this.worker.abort();
+    }
+    async close() {
+        if (this.disconnectTimer)
+            clearTimeout(this.disconnectTimer);
+        this.wss?.clients.forEach(client => client.terminate());
+        this.wss?.close();
+        this.httpServer?.close();
+    }
     async handleExportPdfRequest(testScenariosFromUI) {
         try {
-            const spinner = (0, ora_1.default)(chalk_1.default.blue("Compiling high-fidelity PDF report...")).start();
+            const spinner = (0, ora_1.default)(chalk_1.default.blue("Compiling high fidelity PDF report...")).start();
             const pdfPath = await this.pdfGenerator.generateTestcasePdf(testScenariosFromUI);
-            // Convert the saved PDF to base64 to trigger the native browser download UI
             const pdfBuffer = fs.readFileSync(pdfPath);
             const base64Data = pdfBuffer.toString("base64");
             this.forwardToDashboard("EXPORT_PDF_RES", { base64: base64Data });