@vijaypjavvadi/bdd2pw 1.0.0

package/dist/cli.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * Commander CLI entry. Thin shell over `src/index.ts`.
+ * See docs/SCOPE.md §8.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const path = __importStar(require("path"));
+const index_1 = require("./index");
+const logger_1 = require("./utils/logger");
+const program = new commander_1.Command();
+program
+    .name("bdd2pw")
+    .description("Scaffold runnable Playwright TypeScript tests from Gherkin .feature files.")
+    .version(require("../package.json").version);
+program
+    .command("scaffold")
+    .description("Read a .feature file + URL, emit Page Objects + spec into a Playwright TS repo.")
+    .argument("<feature>", "Path to a Gherkin .feature file")
+    .requiredOption("--url <url>", "URL of the page under test")
+    .requiredOption("--page <Name>", "Page Object class name (PascalCase)")
+    .requiredOption("--repo <dir>", "Target Playwright TS repo (created if missing)")
+    .option("--pages <list>", "Comma-separated list of additional Page Object names")
+    .option("--storage-state <path>", "Pre-authenticated storage state JSON")
+    .option("--headed", "Show browser during MCP scan", false)
+    .option("--snapshot-file <path>", "Read elements from a JSON file instead of launching a browser")
+    .option("--no-discovery", "Skip page discovery entirely (rule-only probing). Field-referencing rules will fall to TODO.")
+    .option("--llm <provider>", "Enable LLM fallback: anthropic | openai | gemini")
+    .option("--governance-url <url>", "ai-governance sidecar URL", "http://localhost:8004")
+    .option("--templates <dir>", "Override default project template directory")
+    .option("--dry-run", "Print plan, write nothing", false)
+    .option("--no-validate", "Skip tsc --noEmit step")
+    .option("--telemetry", "Enable local SQLite failure telemetry", false)
+    .option("--force", "Overwrite existing spec files", false)
+    .action(async (feature, opts) => {
+    try {
+        const result = await (0, index_1.scaffold)({
+            feature: path.resolve(feature),
+            url: opts.url,
+            page: opts.page,
+            repo: path.resolve(opts.repo),
+            pages: opts.pages?.split(",").map((s) => s.trim()),
+            storageState: opts.storageState,
+            headed: opts.headed,
+            llm: opts.llm,
+            governanceUrl: opts.governanceUrl,
+            templates: opts.templates,
+            dryRun: opts.dryRun,
+            noValidate: opts.noValidate === false,
+            telemetry: opts.telemetry,
+            force: opts.force,
+            snapshotFile: opts.snapshotFile,
+            // Commander negates --no-discovery into opts.discovery=false
+            noDiscovery: opts.discovery === false,
+        });
+        logger_1.logger.info({ result }, "scaffold complete");
+    }
+    catch (err) {
+        logger_1.logger.error({ err }, "scaffold failed");
+        process.exit(exitCodeFor(err));
+    }
+});
+program
+    .command("analyze")
+    .description("Dry-run: parse .feature, scan URL, print locator + binding preview.")
+    .argument("<feature>", "Path to a Gherkin .feature file")
+    .requiredOption("--url <url>", "URL to scan")
+    .option("--storage-state <path>", "Pre-authenticated storage state JSON")
+    .option("--headed", "Show browser during MCP scan", false)
+    .action(async (feature, opts) => {
+    try {
+        const result = await (0, index_1.analyze)({
+            feature: path.resolve(feature),
+            url: opts.url,
+            storageState: opts.storageState,
+            headed: opts.headed,
+        });
+        console.log(JSON.stringify(result, null, 2));
+    }
+    catch (err) {
+        logger_1.logger.error({ err }, "analyze failed");
+        process.exit(exitCodeFor(err));
+    }
+});
+program
+    .command("update-pom")
+    .description("Re-scan a URL and merge new locators into an existing Page Object.")
+    .requiredOption("--page <Name>", "Page Object class name")
+    .requiredOption("--url <url>", "URL to re-scan")
+    .requiredOption("--repo <dir>", "Existing Playwright TS repo")
+    .option("--storage-state <path>", "Pre-authenticated storage state JSON")
+    .option("--headed", "Show browser during MCP scan", false)
+    .option("--templates <dir>", "Override default project template directory")
+    .action(async (opts) => {
+    try {
+        const result = await (0, index_1.updatePom)({
+            page: opts.page,
+            url: opts.url,
+            repo: path.resolve(opts.repo),
+            storageState: opts.storageState,
+            headed: opts.headed,
+            templates: opts.templates,
+        });
+        logger_1.logger.info({ result }, "update-pom complete");
+    }
+    catch (err) {
+        logger_1.logger.error({ err }, "update-pom failed");
+        process.exit(exitCodeFor(err));
+    }
+});
+program
+    .command("serve")
+    .description("Start the bdd2pw HTTP service.")
+    .option("--port <port>", "Port to listen on", "4300")
+    .action(async (opts) => {
+    const { startServer } = await Promise.resolve().then(() => __importStar(require("./server")));
+    await startServer({ port: Number(opts.port) });
+});
+/**
+ * Map error → CLI exit code. See docs/ARCHITECTURE.md §7.
+ */
+function exitCodeFor(err) {
+    const name = err?.name ?? "";
+    switch (name) {
+        case "GherkinParseError":
+            return 2;
+        case "FileSystemError":
+            return 3;
+        case "McpError":
+        case "GovernanceError":
+            return 4;
+        case "EmitterConsistencyError":
+            return 5;
+        default:
+            return 1;
+    }
+}
+program.parseAsync(process.argv).catch((err) => {
+    logger_1.logger.error({ err }, "fatal");
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/discovery/mcpClient.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Page discovery client.
+ *
+ * Two implementations behind one entrypoint:
+ *   1. **Real browser** (Phase 1b, this file). Launches Chromium via
+ *      `playwright`, navigates to the URL, walks the DOM, returns a flat
+ *      `ElementIR[]`-shaped accessibility list.
+ *   2. **File snapshot** (Phase 1a fallback). Reads a pre-captured JSON
+ *      snapshot when `opts.snapshotFile` is set. Useful for offline / CI /
+ *      no-network tests, and for scenarios where you've captured a known-good
+ *      page state and don't want to re-scan every run.
+ *
+ * The orchestrator picks based on whether `snapshotFile` is set. Both
+ * implementations return the same `PageSnapshot` shape so `parseSnapshot`
+ * downstream is unaware of the choice.
+ *
+ * **AQ-2 resolved:** uses `playwright` directly, not `@playwright/mcp`.
+ * MCP is an LLM-control protocol; we just need a one-shot programmatic
+ * browser. Direct Playwright is one fewer process, one fewer protocol
+ * layer, no JSON-RPC overhead. The MCP framing only made sense if we were
+ * letting an LLM drive the browser interactively — we're not.
+ *
+ * **Optional dependency.** `playwright` is in `optionalDependencies`. The
+ * scanner imports it dynamically and surfaces a clear install hint in
+ * `McpError` if it's missing.
+ */
+export declare class McpError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+export interface ScanPageOptions {
+    url: string;
+    /** Pre-authenticated storage state JSON path (Playwright format). */
+    storageState?: string;
+    /** Show the browser window. Default: headless. */
+    headed?: boolean;
+    /**
+     * If set, read snapshot from this JSON file instead of launching a
+     * browser. Used by tests, CI without network, and pinned-fixture runs.
+     */
+    snapshotFile?: string;
+    /** ms to wait for `networkidle` after navigation. Default: 5000. */
+    waitForNetworkIdleMs?: number;
+}
+export interface PageSnapshot {
+    url: string;
+    title: string;
+    /** Flat list of element descriptors (snapshotParser handles flat-array shape). */
+    accessibilityTree: unknown;
+    /** Raw outer HTML of <body>, length-capped — used by some downstream heuristics. */
+    domSnapshot: string;
+}
+export declare function scanPage(opts: ScanPageOptions): Promise<PageSnapshot>;

package/dist/discovery/mcpClient.js

@@ -0,0 +1,326 @@
+"use strict";
+/// <reference lib="dom" />
+/**
+ * Page discovery client.
+ *
+ * Two implementations behind one entrypoint:
+ *   1. **Real browser** (Phase 1b, this file). Launches Chromium via
+ *      `playwright`, navigates to the URL, walks the DOM, returns a flat
+ *      `ElementIR[]`-shaped accessibility list.
+ *   2. **File snapshot** (Phase 1a fallback). Reads a pre-captured JSON
+ *      snapshot when `opts.snapshotFile` is set. Useful for offline / CI /
+ *      no-network tests, and for scenarios where you've captured a known-good
+ *      page state and don't want to re-scan every run.
+ *
+ * The orchestrator picks based on whether `snapshotFile` is set. Both
+ * implementations return the same `PageSnapshot` shape so `parseSnapshot`
+ * downstream is unaware of the choice.
+ *
+ * **AQ-2 resolved:** uses `playwright` directly, not `@playwright/mcp`.
+ * MCP is an LLM-control protocol; we just need a one-shot programmatic
+ * browser. Direct Playwright is one fewer process, one fewer protocol
+ * layer, no JSON-RPC overhead. The MCP framing only made sense if we were
+ * letting an LLM drive the browser interactively — we're not.
+ *
+ * **Optional dependency.** `playwright` is in `optionalDependencies`. The
+ * scanner imports it dynamically and surfaces a clear install hint in
+ * `McpError` if it's missing.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpError = void 0;
+exports.scanPage = scanPage;
+const fs = __importStar(require("fs-extra"));
+class McpError extends Error {
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "McpError";
+    }
+}
+exports.McpError = McpError;
+async function scanPage(opts) {
+    if (opts.snapshotFile) {
+        return scanPageFromFile(opts.snapshotFile);
+    }
+    return scanPageWithBrowser(opts);
+}
+// ─── File-snapshot fallback ────────────────────────────────────────────────
+async function scanPageFromFile(snapshotFile) {
+    if (!(await fs.pathExists(snapshotFile))) {
+        throw new McpError(`Snapshot file not found: ${snapshotFile}`);
+    }
+    let parsed;
+    try {
+        parsed = await fs.readJSON(snapshotFile);
+    }
+    catch (err) {
+        throw new McpError(`Could not parse snapshot JSON: ${snapshotFile}`, err);
+    }
+    return {
+        url: parsed.url ?? "",
+        title: parsed.title ?? "",
+        accessibilityTree: parsed.accessibilityTree ?? parsed.elements ?? [],
+        domSnapshot: parsed.domSnapshot ?? "",
+    };
+}
+// ─── Real browser scanner (Phase 1b) ───────────────────────────────────────
+async function scanPageWithBrowser(opts) {
+    // Dynamic import — `playwright` is an optional dependency. If the user
+    // hasn't installed it, surface an actionable error rather than a stack trace.
+    let chromium;
+    try {
+        ({ chromium } = await Promise.resolve().then(() => __importStar(require("playwright"))));
+    }
+    catch (err) {
+        throw new McpError("Page discovery requires `playwright`. Install it in your project " +
+            "(`npm install -D playwright`) and run `npx playwright install chromium`. " +
+            "Alternatively, pre-capture a snapshot.json and pass --snapshot-file.", err);
+    }
+    let browser;
+    try {
+        browser = await chromium.launch({ headless: !opts.headed });
+    }
+    catch (err) {
+        throw new McpError("Could not launch chromium. Did you run `npx playwright install chromium`?", err);
+    }
+    try {
+        const ctx = await browser.newContext(opts.storageState ? { storageState: opts.storageState } : {});
+        const page = await ctx.newPage();
+        try {
+            await page.goto(opts.url, {
+                waitUntil: "networkidle",
+                timeout: opts.waitForNetworkIdleMs ?? 5000,
+            });
+        }
+        catch (err) {
+            // Network-idle is best-effort; some SPAs never reach it. Fall back to
+            // domcontentloaded — the page DOM is at least populated.
+            try {
+                await page.goto(opts.url, { waitUntil: "domcontentloaded", timeout: 10000 });
+            }
+            catch (innerErr) {
+                throw new McpError(`Could not navigate to ${opts.url}: ${innerErr.message}`, innerErr);
+            }
+        }
+        const title = await page.title().catch(() => "");
+        // Walk the DOM and extract every "interesting" element with a stable
+        // descriptor. The selector list covers anything a Gherkin step would
+        // plausibly target. Each descriptor maps 1:1 onto `ElementIR`, so
+        // `snapshotParser` (already in place) handles it without changes.
+        //
+        // The status/notification id+class patterns at the bottom catch elements
+        // like `<div id="error">` and `<div class="alert-warning">` that don't
+        // have an explicit ARIA role but are clearly named after their purpose.
+        // Without these, "Then I should see an error message" can't find a POM
+        // field and falls back to `page.getByText(...)` which often matches twice
+        // (real error + instructional copy on the page).
+        const elements = await page.evaluate(() => {
+            const SELECTORS = [
+                "input",
+                "textarea",
+                "select",
+                "button",
+                "a",
+                "[role]",
+                "[data-testid]",
+                "[aria-label]",
+                "h1",
+                "h2",
+                "h3",
+                "h4",
+                "h5",
+                "h6",
+                "label",
+                "[type=submit]",
+                // Status / notification regions — catch by id or class hint
+                "[id*=error i]",
+                "[id*=alert i]",
+                "[id*=message i]",
+                "[id*=warning i]",
+                "[id*=success i]",
+                "[id*=notification i]",
+                "[class*=error i]",
+                "[class*=alert i]",
+                "[class*=notification i]",
+                "[class*=banner i]",
+            ].join(",");
+            function getLabelFor(el) {
+                const id = el.getAttribute("id");
+                if (id) {
+                    const lab = document.querySelector(`label[for="${CSS.escape(id)}"]`);
+                    if (lab && lab.textContent)
+                        return lab.textContent.trim();
+                }
+                const wrapping = el.closest("label");
+                if (wrapping && wrapping.textContent)
+                    return wrapping.textContent.trim();
+                return undefined;
+            }
+            function bestCss(el) {
+                const id = el.getAttribute("id");
+                if (id)
+                    return "#" + id;
+                const cls = typeof el.className === "string"
+                    ? el.className.trim().split(/\s+/)[0]
+                    : undefined;
+                if (cls)
+                    return "." + cls;
+                return undefined;
+            }
+            /**
+             * Implicit ARIA role for native HTML elements. Without this, picker
+             * falls through `getByRole` (which requires a role) to `getByText` —
+             * which is brittle on pages where the same text appears in multiple
+             * places (button label vs instructional copy). Promoting `<button>`
+             * to `role: "button"` lets the picker emit
+             *   page.getByRole("button", { name: "Submit" })
+             * which is what the user authoring tests by hand would write.
+             */
+            function implicitRole(el, tag) {
+                const explicit = el.getAttribute("role");
+                if (explicit)
+                    return explicit;
+                if (tag === "button")
+                    return "button";
+                if (tag === "a" && el.hasAttribute("href"))
+                    return "link";
+                if (tag === "select")
+                    return "combobox";
+                if (tag === "textarea")
+                    return "textbox";
+                if (/^h[1-6]$/.test(tag))
+                    return "heading";
+                if (tag === "input") {
+                    const type = (el.getAttribute("type") || "text").toLowerCase();
+                    if (type === "submit" || type === "button" || type === "reset")
+                        return "button";
+                    if (type === "checkbox")
+                        return "checkbox";
+                    if (type === "radio")
+                        return "radio";
+                    if (type === "search")
+                        return "searchbox";
+                    if (type === "range")
+                        return "slider";
+                    if (type === "number")
+                        return "spinbutton";
+                    // text, email, password, tel, url, etc. → textbox
+                    return "textbox";
+                }
+                return undefined;
+            }
+            /**
+             * Filter out elements that are visually absent (display:none, hidden,
+             * or zero-sized). Decorative wrapper divs and screen-reader-only
+             * spans are not what test steps target.
+             *
+             * EXCEPTION: status regions (error / alert / notification banners)
+             * are *intended* to be hidden until triggered. Bypass the visibility
+             * check when the id or class hints at a status role, otherwise the
+             * `<div id="error">` element disappears from the POM and step
+             * matcher falls back to a non-unique getByText.
+             */
+            const STATUS_HINT = /error|alert|message|warning|success|notification|status/i;
+            function isLikelyStatusRegion(el) {
+                const id = el.getAttribute("id") || "";
+                const cls = typeof el.className === "string"
+                    ? el.className
+                    : "";
+                return STATUS_HINT.test(id) || STATUS_HINT.test(cls);
+            }
+            function isVisible(el) {
+                const r = el.getBoundingClientRect();
+                if (r.width === 0 || r.height === 0)
+                    return false;
+                const cs = window.getComputedStyle(el);
+                if (cs.display === "none" || cs.visibility === "hidden" || cs.opacity === "0") {
+                    return false;
+                }
+                return true;
+            }
+            const seen = new Set();
+            const out = [];
+            const all = document.querySelectorAll(SELECTORS);
+            all.forEach((el) => {
+                if (seen.has(el))
+                    return;
+                seen.add(el);
+                // Status regions bypass the visibility filter
+                if (!isLikelyStatusRegion(el) && !isVisible(el))
+                    return;
+                const tag = el.tagName.toLowerCase();
+                const role = implicitRole(el, tag);
+                const ariaLabel = el.getAttribute("aria-label") || undefined;
+                const placeholder = el.getAttribute("placeholder") || undefined;
+                const testId = el.getAttribute("data-testid") || undefined;
+                const text = (el.textContent || "").trim().replace(/\s+/g, " ").slice(0, 200);
+                // Accessible name — best-effort: aria-label > visible text (for
+                // buttons/links/headings) > placeholder.
+                let name = ariaLabel;
+                if (!name && /^(button|a|h[1-6]|label)$/.test(tag) && text)
+                    name = text;
+                // For native form controls promoted to role:button via type=submit
+                if (!name && role === "button" && el.value) {
+                    name = el.value;
+                }
+                out.push({
+                    tag,
+                    role,
+                    name,
+                    label: getLabelFor(el),
+                    placeholder,
+                    testId,
+                    text: text || undefined,
+                    cssSelector: bestCss(el),
+                });
+            });
+            return out;
+        });
+        const domSnapshot = await page
+            .evaluate(() => document.body.outerHTML.slice(0, 50000))
+            .catch(() => "");
+        return {
+            url: opts.url,
+            title,
+            accessibilityTree: elements,
+            domSnapshot,
+        };
+    }
+    finally {
+        await browser.close().catch(() => undefined);
+    }
+}
+//# sourceMappingURL=mcpClient.js.map

package/dist/discovery/mcpClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpClient.js","sourceRoot":"","sources":["../../src/discovery/mcpClient.ts"],"names":[],"mappings":"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"}

package/dist/discovery/snapshotParser.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Convert a `PageSnapshot` into a flat list of `ElementIR` candidates that
+ * the locator picker can rank.
+ *
+ * Accepts two snapshot shapes:
+ *   1) `accessibilityTree` is already an array of element-shaped objects
+ *      (the file-snapshot fallback uses this — easy to author by hand)
+ *   2) `accessibilityTree` is a Playwright a11y tree node (with `children[]`)
+ *      — flattened recursively.
+ */
+import type { ElementIR } from "../types";
+import type { PageSnapshot } from "./mcpClient";
+export declare function parseSnapshot(snapshot: PageSnapshot): ElementIR[];

package/dist/discovery/snapshotParser.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Convert a `PageSnapshot` into a flat list of `ElementIR` candidates that
+ * the locator picker can rank.
+ *
+ * Accepts two snapshot shapes:
+ *   1) `accessibilityTree` is already an array of element-shaped objects
+ *      (the file-snapshot fallback uses this — easy to author by hand)
+ *   2) `accessibilityTree` is a Playwright a11y tree node (with `children[]`)
+ *      — flattened recursively.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSnapshot = parseSnapshot;
+function parseSnapshot(snapshot) {
+    const tree = snapshot.accessibilityTree;
+    if (Array.isArray(tree)) {
+        return tree.map(toElementIR);
+    }
+    if (tree && typeof tree === "object") {
+        const out = [];
+        walk(tree, out);
+        return out;
+    }
+    return [];
+}
+function walk(node, out) {
+    if (!node)
+        return;
+    // Skip the synthetic root node if it has no role
+    if (node.role || node.name || node.tag) {
+        out.push(toElementIR(node));
+    }
+    for (const child of node.children ?? []) {
+        walk(child, out);
+    }
+}
+function toElementIR(raw) {
+    return {
+        role: raw.role || undefined,
+        name: raw.name || undefined,
+        label: raw.label || undefined,
+        placeholder: raw.placeholder || undefined,
+        testId: raw.testId || raw["data-testid"] || undefined,
+        text: raw.text || raw.innerText || undefined,
+        cssSelector: raw.cssSelector || raw.css || undefined,
+        xpath: raw.xpath || undefined,
+        tag: raw.tag || raw.tagName?.toLowerCase() || "",
+        bounds: raw.bounds,
+    };
+}
+//# sourceMappingURL=snapshotParser.js.map

package/dist/discovery/snapshotParser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshotParser.js","sourceRoot":"","sources":["../../src/discovery/snapshotParser.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;AAKH,sCAWC;AAXD,SAAgB,aAAa,CAAC,QAAsB;IAClD,MAAM,IAAI,GAAG,QAAQ,CAAC,iBAAiB,CAAC;IACxC,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,OAAO,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC/B,CAAC;IACD,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QACrC,MAAM,GAAG,GAAgB,EAAE,CAAC;QAC5B,IAAI,CAAC,IAAW,EAAE,GAAG,CAAC,CAAC;QACvB,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,SAAS,IAAI,CAAC,IAAS,EAAE,GAAgB;IACvC,IAAI,CAAC,IAAI;QAAE,OAAO;IAClB,iDAAiD;IACjD,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;QACvC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC;IAC9B,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,IAAI,EAAE,EAAE,CAAC;QACxC,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACnB,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,GAAQ;IAC3B,OAAO;QACL,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,SAAS;QAC3B,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,SAAS;QAC3B,KAAK,EAAE,GAAG,CAAC,KAAK,IAAI,SAAS;QAC7B,WAAW,EAAE,GAAG,CAAC,WAAW,IAAI,SAAS;QACzC,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,aAAa,CAAC,IAAI,SAAS;QACrD,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,SAAS,IAAI,SAAS;QAC5C,WAAW,EAAE,GAAG,CAAC,WAAW,IAAI,GAAG,CAAC,GAAG,IAAI,SAAS;QACpD,KAAK,EAAE,GAAG,CAAC,KAAK,IAAI,SAAS;QAC7B,GAAG,EAAE,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE;QAChD,MAAM,EAAE,GAAG,CAAC,MAAM;KACnB,CAAC;AACJ,CAAC"}