flowstride 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flowstride.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,183 @@
+# Flowstride OS
+
+**The next-generation, BDD-flavored End-to-End Testing Framework.**
+
+Flowstride OS combines the human-readable structure of Behavior-Driven Development (BDD) with the raw execution power of Playwright. It allows QA engineers and developers to write robust, maintainable UI and API tests using an intuitive domain-specific language (DSL), while providing a rich, interactive React dashboard to monitor, debug, and replay test runs in real time.
+
+---
+
+## Why Flowstride?
+
+Traditional E2E frameworks force you to choose between highly technical code (which non-developers struggle to read) or rigid low-code tools (which lack flexibility). Flowstride bridges the gap:
+
+- **Plain-English Selectors**: Target elements spatially (`"Submit" near "Cancel"`) or by text, eliminating brittle CSS/XPath dependencies.
+- **Unified UI & API Testing**: Execute browser actions and REST/GraphQL API calls within the exact same scenario.
+- **Live Visual Dashboard**: Watch your tests run step-by-step, inspect DOM snapshots, trace network activity, and manually replay API requests directly from the UI.
+- **Built-in State Management**: Save and inject browser sessions (cookies, local storage) with a single command to bypass repetitive login steps.
+
+---
+
+## Installation & Quick Start
+
+Flowstride requires Node.js 18 or higher.
+
+**1. Install globally (or as a dev dependency in your project):**
+npm install -g flowstride
+
+**2. Initialize a new Flowstride workspace:**
+flowstride init
+
+_(This creates the default directory structure (`/flows`, `/reports`, `/plugins`) and generates a `welcome.flow` sample file.)_
+
+**3. Run your first test:**
+flowstride run flows/welcome.flow
+
+_(This command executes your test while instantly booting up the local Flowstride Dashboard on `http://localhost:5173`.)_
+
+---
+
+## The `.flow` Syntax
+
+Flowstride utilizes a custom `.flow` file extension. It seamlessly pairs descriptive BDD steps (Given, When, And, Then) with direct, executable `flow.` commands.
+
+Here is an example of a standard UI and API flow:
+
+```bash
+// Signing up a new user via API call.
+Given "User signup via API call"
+  flow.post "/api/signup" with reqBody
+  """
+  {
+      "firstName": "Mike",
+      "lastName": "Doe",
+      "dob": "1995-05-10",
+      "sex": "male",
+      "email": "user@flowstridemail.com",
+      "password": "$randomPassword"
+  }
+  """
+  flow.extract resBody "userId" as "newUserId"
+  flow.expect status "201"
+
+// Approving the new user from admin via API call
+When "A new signup user is approved by the Admin"
+  flow.post "/api/approve" with reqBody
+  """
+  {
+      "userId": "@newUserId"
+  }
+  """
+
+And "Confirm Status Code is 200"
+  flow.expect status "200"
+
+And "Confirm resBody message is successful"
+  flow.expect resBody "message" equals "User approved successfully"
+
+And "Confirm user status to be active"
+  flow.expect resBody "user.status" equals "active"
+
+// Using the newly registered user credentials to login via the UI
+When "User lands on home page"
+  flow.open "/login"
+
+And "User clicks on Log in, near Sign Up"
+  flow.click "Log in" near "Sign up"
+
+And "User inputs newly created credentials"
+  flow.type "Email" "user@flowstridemail.com"
+  flow.type "Password" "@randomPassword" // Reusing the random password from API call
+
+Then "Click on Login button"
+  flow.click button "Login"
+
+```
+
+---
+
+## Command Reference
+
+### Browser Navigation & Context
+
+| Command    | Example                        | Description                                                      |
+| :--------- | :----------------------------- | :--------------------------------------------------------------- |
+| `open`     | `flow.open "https://site.com"` | Navigates the browser to the specified URL.                      |
+| `switchTo` | `flow.switchTo "next"`         | Switches to a new tab or window by title/URL or relation.        |
+| `close`    | `flow.close "Modal Title"`     | Geometrically calculates and clicks the close button of a modal. |
+
+### UI Actions
+
+| Command      | Example                                   | Description                                                     |
+| :----------- | :---------------------------------------- | :-------------------------------------------------------------- |
+| `click`      | `flow.click "Submit"`                     | Clicks an element based on text, CSS, or spatial relation.      |
+| `forceClick` | `flow.forceClick "#hidden-btn"`           | Bypasses Playwright's actionability checks to force a click.    |
+| `type`       | `flow.type "Email" "test@test.com"`       | Types value into an input field matching the target.            |
+| `passcode`   | `flow.passcode "OTP" "123456"`            | Specifically handles split OTP/Passcode input arrays.           |
+| `select`     | `flow.select "Option 1" from "Dropdown"`  | Selects an option from a native select or custom portal.        |
+| `check`      | `flow.check "Terms and Conditions"`       | Checks a checkbox or radio button.                              |
+| `upload`     | `flow.upload "Avatar" "path/to/file.jpg"` | Uploads a local file to a file input element.                   |
+| `drag`       | `flow.drag "Item A" into "Zone B"`        | Drags a source element and drops it into a destination element. |
+
+### Assertions
+
+| Command          | Example                                | Description                                            |
+| :--------------- | :------------------------------------- | :----------------------------------------------------- |
+| `expect visible` | `flow.expect visible "Success"`        | Asserts an element is attached to the DOM and visible. |
+| `expect text`    | `flow.expect text "Error"`             | Asserts specific text is present in the UI.            |
+| `expect value`   | `flow.expect value "Username" "admin"` | Asserts the input value of a targeted field.           |
+
+### Session Management
+
+| Command        | Example                    | Description                                                                   |
+| :------------- | :------------------------- | :---------------------------------------------------------------------------- |
+| `save session` | `flow.save session "Auth"` | Captures current cookies/storage into memory (add `persist` to save to disk). |
+| `use session`  | `flow.use session "Auth"`  | Injects previously saved cookies/storage directly into the browser.           |
+
+### API Testing
+
+| Command                        | Example                                       | Description                                                        |
+| :----------------------------- | :-------------------------------------------- | :----------------------------------------------------------------- |
+| `get`, `post`, `put`, `delete` | `flow.post "/api/users" with reqBody "{...}"` | Executes HTTP requests natively via Undici.                        |
+| `extract`                      | `flow.extract resBody "token" as "jwt"`       | Parses API responses and saves data to a local or global variable. |
+| `expect status`                | `flow.expect status "200"`                    | Asserts the HTTP status code of the last API call.                 |
+
+_(For a complete list of commands, API assertions, and plugin integration rules, please see the official documentation)._
+
+---
+
+## Interactive Dashboard
+
+Running a `.flow` file automatically boots the Flowstride Dashboard.
+
+- **Live Execution:** Watch tests execute in real-time with an integrated screencast.
+- **Step Diagnostics:** Click on any step (Pass or Fail) to view exact execution context, error stack traces, and a DOM snapshot with the target element highlighted.
+- **Network Interception:** View all intercepted XHR/Fetch requests. You can click **Replay** on any API log to independently re-execute the request from the Node.js backend natively.
+- **Soft Kill & Rerun:** Use the top navigation bar to seamlessly abort running tests, clear state, and restart execution without touching the terminal.
+
+---
+
+## Flowstride OS vs. Enterprise
+
+**Flowstride OS** is free, fully featured, and highly capable for individual developers and standard QA teams.
+
+**Flowstride Enterprise** (`flowstride.io`) unlocks advanced capabilities for massive-scale automation:
+
+- **Distributed Parallel Execution Grid**: Run thousands of tests simultaneously across dynamically spun-up workers.
+- **AI Auto-Healing**: Let AI automatically fix broken or outdated selectors during test execution based on DOM analysis.
+- **Automated FlowMail (OTP/2FA)**: Fully native email extraction (`flow.getOtp`) to bypass complex 2FA flows.
+- **High-Fidelity PDF Exports**: Programmatic, C-suite ready PDF report generation.
+- **Cloud Storage & History**: Store all your test runs in the cloud to access and reference them at any time.
+- **Native Integrations**: Seamlessly connect your testing workflows directly with Jira and Slack.
+- **Massive Team Collaboration**: Scale your operations by connecting with 70+ team members in a shared workspace.
+
+---
+
+## Contributing
+
+We welcome contributions from the community! Whether you are fixing bugs, proposing new features, or improving documentation, please feel free to open an issue or submit a Pull Request.
+
+When submitting a PR, please ensure you test your changes against the core parser (`src/parser/`) and the Playwright web adapter (`src/adapters/web/`).
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

package/dist/adapters/api/undici.d.ts

@@ -0,0 +1,46 @@
+import { FlowstrideConfig } from "../../types";
+export interface ApiState {
+    status: number | null;
+    body: any | null;
+    headers: Record<string, string | string[] | undefined> | null;
+    responseTime: number;
+}
+export declare class ApiAdapter {
+    private config;
+    private globalHeaders;
+    private onUnauthorized?;
+    private lastStatus;
+    private lastBody;
+    private lastHeaders;
+    private lastResponseTime;
+    constructor(config: FlowstrideConfig);
+    setGlobalHeader(name: string, value: string): void;
+    setUnauthorizedHandler(handler: () => Promise<void>): void;
+    getState(): ApiState;
+    resetState(): void;
+    get(path: string, headers?: {
+        key: string;
+        value: string;
+    }[]): Promise<void>;
+    delete(path: string, headers?: {
+        key: string;
+        value: string;
+    }[]): Promise<void>;
+    post(path: string, headers: {
+        key: string;
+        value: string;
+    }[], body?: string): Promise<void>;
+    put(path: string, headers: {
+        key: string;
+        value: string;
+    }[], body?: string): Promise<void>;
+    patch(path: string, headers: {
+        key: string;
+        value: string;
+    }[], body?: string): Promise<void>;
+    graphql(path: string, headers: {
+        key: string;
+        value: string;
+    }[], bodyContent: string): Promise<void>;
+    private execute;
+}

package/dist/adapters/api/undici.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiAdapter = void 0;
+const undici_1 = require("undici");
+class ApiAdapter {
+    config;
+    globalHeaders = {};
+    onUnauthorized;
+    lastStatus = null;
+    lastBody = null;
+    lastHeaders = null;
+    lastResponseTime = 0;
+    constructor(config) {
+        this.config = config;
+    }
+    setGlobalHeader(name, value) {
+        this.globalHeaders[name] = value;
+    }
+    setUnauthorizedHandler(handler) {
+        this.onUnauthorized = handler;
+    }
+    getState() {
+        if (this.lastStatus === null) {
+            throw new Error("No API request has been executed yet to extract state from.");
+        }
+        return {
+            status: this.lastStatus,
+            body: this.lastBody,
+            headers: this.lastHeaders,
+            responseTime: this.lastResponseTime,
+        };
+    }
+    resetState() {
+        this.lastStatus = null;
+        this.lastBody = null;
+        this.lastHeaders = null;
+        this.lastResponseTime = 0;
+    }
+    async get(path, headers = []) {
+        return this.execute("GET", path, headers);
+    }
+    async delete(path, headers = []) {
+        return this.execute("DELETE", path, headers);
+    }
+    async post(path, headers, body) {
+        return this.execute("POST", path, headers, body);
+    }
+    async put(path, headers, body) {
+        return this.execute("PUT", path, headers, body);
+    }
+    async patch(path, headers, body) {
+        return this.execute("PATCH", path, headers, body);
+    }
+    async graphql(path, headers, bodyContent) {
+        let finalPayload = bodyContent;
+        try {
+            JSON.parse(bodyContent);
+        }
+        catch {
+            finalPayload = JSON.stringify({ query: bodyContent.trim() });
+        }
+        const hasContentType = headers.some((h) => h.key.toLowerCase() === "content-type");
+        if (!hasContentType)
+            headers.push({ key: "Content-Type", value: "application/json" });
+        return this.execute("POST", path, headers, finalPayload);
+    }
+    async execute(method, path, headersArray = [], body) {
+        const url = this.config.baseUrl && !path.startsWith("http")
+            ? `${this.config.baseUrl.replace(/\/$/, "")}${path.startsWith("/") ? path : `/${path}`}`
+            : path;
+        const requestHeaders = {
+            "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36 Flowstride/1.0",
+            Accept: "application/json, text/plain, */*",
+            ...this.globalHeaders,
+        };
+        let hasContentType = false;
+        headersArray.forEach((h) => {
+            requestHeaders[h.key] = h.value;
+            if (h.key.toLowerCase() === "content-type")
+                hasContentType = true;
+        });
+        if (body && !hasContentType) {
+            requestHeaders["Content-Type"] = "application/json";
+        }
+        const makeRequest = async () => {
+            const startTime = Date.now();
+            const response = await (0, undici_1.request)(url, {
+                method,
+                headers: requestHeaders,
+                body: body ? body : undefined,
+            });
+            const responseTime = Date.now() - startTime;
+            const text = await response.body.text();
+            let parsedBody = text;
+            try {
+                parsedBody = text ? JSON.parse(text) : null;
+            }
+            catch { }
+            return {
+                status: response.statusCode,
+                headers: response.headers,
+                body: parsedBody,
+                responseTime,
+            };
+        };
+        let res = await makeRequest();
+        if ((res.status === 401 || res.status === 403) && this.onUnauthorized) {
+            await this.onUnauthorized();
+            Object.assign(requestHeaders, this.globalHeaders);
+            res = await makeRequest();
+        }
+        this.lastStatus = res.status;
+        this.lastHeaders = res.headers;
+        this.lastBody = res.body;
+        this.lastResponseTime = res.responseTime;
+    }
+}
+exports.ApiAdapter = ApiAdapter;

package/dist/adapters/web/playwright.d.ts

@@ -0,0 +1,51 @@
+import { Page } from "playwright";
+import { FlowstrideConfig } from "../../types";
+export declare class WebAdapter {
+    private config;
+    private browser;
+    private context;
+    private page;
+    private discoveredPages;
+    private dialogHandler;
+    constructor(config: FlowstrideConfig);
+    getPage(): Page;
+    initialise(audioInjectionPath?: string): Promise<void>;
+    acceptDialog(): Promise<void>;
+    rejectDialog(): Promise<void>;
+    injectAudio(filePath: string): Promise<void>;
+    switchTo(target: string): Promise<void>;
+    injectStorage(cookies?: any[], localStorage?: Record<string, string>, fallbackDomain?: string): Promise<void>;
+    getState(): Promise<{
+        cookies: any[];
+        localStorage: Record<string, string>;
+        sessionStorage: Record<string, string>;
+    }>;
+    getCurrentUrl(): string;
+    navigate(url: string): Promise<void>;
+    synthesizeCurl(method: string, url: string, headers: Record<string, string>, postData: string | null): string;
+    private checkAmbiguity;
+    close(targetText: string): Promise<void>;
+    click(selector: string, elementType?: string): Promise<void>;
+    type(selector: string, value: string, elementType?: string): Promise<void>;
+    passcode(selector: string, value: string, elementType?: string): Promise<void>;
+    check(selector: string, elementType?: string): Promise<void>;
+    uncheck(selector: string, elementType?: string): Promise<void>;
+    upload(selector: string, filePath: string, elementType?: string): Promise<void>;
+    set(selector: string, value: string, elementType?: string): Promise<void>;
+    private fallbackCalendarSelect;
+    select(option: string, selector: string, elementType?: string): Promise<void>;
+    drag(sourceSelector: string, destinationSelector: string): Promise<void>;
+    forceClick(selector: string, elementType?: string): Promise<void>;
+    forceType(selector: string, value: string, elementType?: string): Promise<void>;
+    expectVisible(selector: string, elementType?: string): Promise<void>;
+    expectText(text: string, fuzzy?: boolean, elementType?: string): Promise<void>;
+    expectValue(selector: string, val: string, elementType?: string): Promise<void>;
+    expectTranscript(expectedText: string): Promise<void>;
+    getAttribute(selector: string, attr: string, elementType?: string): Promise<string | null>;
+    private isRawCssSelector;
+    private buildHeuristicSelector;
+    private getLocator;
+    clearHUD(): Promise<void>;
+    updateHUD(id: string, text: string, status: string, error?: string): Promise<void>;
+    shutdown(videoTargetPath?: string): Promise<void>;
+}