@browserflow-ai/exploration 0.0.6

package/dist/locator-candidates.js

@@ -0,0 +1,358 @@
+// @browserflow-ai/exploration - Locator candidate generation
+/**
+ * Implicit ARIA roles for common HTML elements
+ */
+const IMPLICIT_ROLES = {
+    a: 'link',
+    button: 'button',
+    input: 'textbox',
+    select: 'combobox',
+    textarea: 'textbox',
+    img: 'img',
+    nav: 'navigation',
+    main: 'main',
+    header: 'banner',
+    footer: 'contentinfo',
+    aside: 'complementary',
+    article: 'article',
+    section: 'region',
+    form: 'form',
+    table: 'table',
+    ul: 'list',
+    ol: 'list',
+    li: 'listitem',
+    dialog: 'dialog',
+    menu: 'menu',
+    option: 'option',
+    progress: 'progressbar',
+    meter: 'meter',
+    h1: 'heading',
+    h2: 'heading',
+    h3: 'heading',
+    h4: 'heading',
+    h5: 'heading',
+    h6: 'heading',
+};
+/**
+ * Maximum text length for text-based locators
+ */
+const MAX_TEXT_LENGTH = 50;
+/**
+ * LocatorCandidateGenerator - Generates ranked locator options for elements
+ *
+ * Uses multiple strategies to find elements:
+ * - Element refs from agent-browser snapshots
+ * - Test IDs (data-testid, data-test, etc.)
+ * - ARIA roles and labels
+ * - Text content matching
+ * - CSS selectors
+ * - XPath expressions
+ */
+export class LocatorCandidateGenerator {
+    preferredStrategies;
+    maxCandidates;
+    constructor(config = {}) {
+        this.preferredStrategies = config.preferredStrategies ?? [
+            'ref',
+            'testid',
+            'role',
+            'text',
+            'css',
+        ];
+        this.maxCandidates = config.maxCandidates ?? 5;
+    }
+    /**
+     * Generate locator candidates for an element based on natural language query
+     *
+     * @param query - Natural language description (e.g., "Submit button in the form")
+     * @param snapshot - Browser snapshot containing element refs
+     * @returns Promise resolving to ranked list of locator strings
+     */
+    async generateCandidates(query, snapshot) {
+        const candidates = await this.findCandidates(query, snapshot);
+        return candidates.slice(0, this.maxCandidates).map((c) => c.locator);
+    }
+    /**
+     * Generate detailed locator candidates with metadata
+     *
+     * @param query - Natural language description
+     * @param snapshot - Browser snapshot
+     * @returns Promise resolving to ranked list of candidates with scores
+     */
+    async generateDetailedCandidates(query, snapshot) {
+        const candidates = await this.findCandidates(query, snapshot);
+        return candidates.slice(0, this.maxCandidates);
+    }
+    /**
+     * Generate all applicable locator candidates for a known element
+     *
+     * @param element - Element information
+     * @returns Promise resolving to ranked list of candidates
+     */
+    async generateCandidatesForElement(element) {
+        const candidates = [];
+        // 1. Ref locator (highest confidence - direct reference)
+        candidates.push(this.generateRefLocator(element.ref));
+        // 2. Test ID locator (if present)
+        const testId = element.testId || element.attributes?.['data-testid'] || element.attributes?.['data-test'];
+        if (testId) {
+            candidates.push(this.generateTestIdLocator(testId));
+        }
+        // 3. Role locator (explicit or implicit)
+        const role = element.role || IMPLICIT_ROLES[element.tag];
+        if (role) {
+            const name = element.ariaLabel || (element.text && element.text.length <= MAX_TEXT_LENGTH ? element.text : undefined);
+            candidates.push(this.generateRoleLocator(role, name));
+        }
+        // 4. Text locator (if text is short enough)
+        if (element.text && element.text.length > 0 && element.text.length <= MAX_TEXT_LENGTH) {
+            // Use exact match for shorter text
+            const exact = element.text.length <= 30;
+            candidates.push(this.generateTextLocator(element.text, exact));
+        }
+        // 5. CSS selector (always as fallback)
+        const cssSelector = this.generateCssSelectorForElement(element);
+        candidates.push({
+            locator: cssSelector,
+            type: 'css',
+            confidence: this.calculateCssConfidence(element),
+            description: 'CSS selector',
+        });
+        // Sort by confidence (highest first)
+        return candidates.sort((a, b) => b.confidence - a.confidence);
+    }
+    /**
+     * Find candidate locators matching a query
+     */
+    async findCandidates(query, snapshot) {
+        // Handle empty query
+        if (!query || query.trim() === '') {
+            return [];
+        }
+        const normalizedQuery = query.toLowerCase().trim();
+        const refs = (snapshot.refs || {});
+        // Handle empty snapshot
+        if (Object.keys(refs).length === 0) {
+            return [];
+        }
+        // Find matching elements
+        const matchedElements = [];
+        for (const [ref, refData] of Object.entries(refs)) {
+            const element = this.parseElementFromRef(ref, refData);
+            const matchScore = this.calculateMatchScore(element, normalizedQuery);
+            if (matchScore > 0) {
+                matchedElements.push({ element, score: matchScore });
+            }
+        }
+        // Sort by match score (best match first)
+        matchedElements.sort((a, b) => b.score - a.score);
+        // Take the best matching element and generate candidates for it
+        if (matchedElements.length === 0) {
+            return [];
+        }
+        const bestMatch = matchedElements[0];
+        return this.generateCandidatesForElement(bestMatch.element);
+    }
+    /**
+     * Parse element info from snapshot ref data
+     */
+    parseElementFromRef(ref, refData) {
+        return {
+            ref,
+            tag: refData.tag || 'div',
+            role: refData.role,
+            text: refData.text,
+            ariaLabel: refData.ariaLabel,
+            testId: refData.testId,
+            className: refData.className,
+            id: refData.id,
+            attributes: refData.attributes,
+        };
+    }
+    /**
+     * Calculate how well an element matches the query
+     * Returns a score from 0 (no match) to 1 (perfect match)
+     */
+    calculateMatchScore(element, normalizedQuery) {
+        let score = 0;
+        const queryTerms = normalizedQuery.split(/\s+/);
+        // Match by text content
+        if (element.text) {
+            const normalizedText = element.text.toLowerCase();
+            if (normalizedText === normalizedQuery) {
+                score += 1.0; // Exact match
+            }
+            else if (normalizedText.includes(normalizedQuery)) {
+                score += 0.8; // Contains query
+            }
+            else {
+                // Check if all query terms are in the text
+                const matchedTerms = queryTerms.filter((term) => normalizedText.includes(term));
+                score += (matchedTerms.length / queryTerms.length) * 0.6;
+            }
+        }
+        // Match by aria-label
+        if (element.ariaLabel) {
+            const normalizedLabel = element.ariaLabel.toLowerCase();
+            if (normalizedLabel === normalizedQuery) {
+                score += 0.9;
+            }
+            else if (normalizedLabel.includes(normalizedQuery)) {
+                score += 0.7;
+            }
+            else {
+                const matchedTerms = queryTerms.filter((term) => normalizedLabel.includes(term));
+                score += (matchedTerms.length / queryTerms.length) * 0.5;
+            }
+        }
+        // Match by tag name
+        const normalizedTag = element.tag.toLowerCase();
+        if (queryTerms.includes(normalizedTag)) {
+            score += 0.4;
+        }
+        // Match by role
+        if (element.role) {
+            const normalizedRole = element.role.toLowerCase();
+            if (queryTerms.includes(normalizedRole)) {
+                score += 0.5;
+            }
+        }
+        else {
+            // Check implicit role
+            const implicitRole = IMPLICIT_ROLES[element.tag];
+            if (implicitRole && queryTerms.includes(implicitRole)) {
+                score += 0.4;
+            }
+        }
+        // Match by test ID
+        if (element.testId) {
+            const normalizedTestId = element.testId.toLowerCase().replace(/[-_]/g, ' ');
+            const matchedTerms = queryTerms.filter((term) => normalizedTestId.includes(term));
+            score += (matchedTerms.length / queryTerms.length) * 0.3;
+        }
+        // Match by class name
+        if (element.className) {
+            const normalizedClasses = element.className.toLowerCase().replace(/[-_]/g, ' ');
+            const matchedTerms = queryTerms.filter((term) => normalizedClasses.includes(term));
+            score += (matchedTerms.length / queryTerms.length) * 0.2;
+        }
+        return Math.min(score, 1.0); // Cap at 1.0
+    }
+    /**
+     * Generate a CSS selector for an element
+     */
+    generateCssSelectorForElement(element) {
+        // Prefer ID if available (most specific)
+        if (element.id) {
+            return `#${this.escapeCssSelector(element.id)}`;
+        }
+        // Build selector from tag and classes
+        let selector = element.tag;
+        if (element.className) {
+            const classes = element.className.split(/\s+/).filter((c) => c.length > 0);
+            if (classes.length > 0) {
+                // Use first 2 classes for specificity without being too brittle
+                const selectedClasses = classes.slice(0, 2);
+                selector += selectedClasses.map((c) => `.${this.escapeCssSelector(c)}`).join('');
+            }
+        }
+        return selector;
+    }
+    /**
+     * Escape special characters in CSS selectors
+     */
+    escapeCssSelector(value) {
+        return value.replace(/([!"#$%&'()*+,./:;<=>?@[\\\]^`{|}~])/g, '\\$1');
+    }
+    /**
+     * Calculate CSS selector confidence based on element attributes
+     */
+    calculateCssConfidence(element) {
+        // ID-based selectors are more stable
+        if (element.id) {
+            return 0.75;
+        }
+        // Class-based selectors are moderately stable
+        if (element.className) {
+            return 0.6;
+        }
+        // Tag-only selectors are least stable
+        return 0.4;
+    }
+    /**
+     * Generate a locator from element ref
+     */
+    generateRefLocator(ref) {
+        return {
+            locator: `@${ref}`,
+            type: 'ref',
+            confidence: 1.0,
+            description: 'Element reference from snapshot',
+        };
+    }
+    /**
+     * Generate a locator from test ID
+     */
+    generateTestIdLocator(testId) {
+        return {
+            locator: `[data-testid="${testId}"]`,
+            type: 'testid',
+            confidence: 0.95,
+            description: 'Test ID selector',
+        };
+    }
+    /**
+     * Generate a locator from ARIA role
+     */
+    generateRoleLocator(role, name) {
+        const locator = name ? `role=${role}[name="${name}"]` : `role=${role}`;
+        return {
+            locator,
+            type: 'role',
+            confidence: name ? 0.9 : 0.85,
+            description: `ARIA role: ${role}${name ? ` with name "${name}"` : ''}`,
+        };
+    }
+    /**
+     * Generate a locator from text content
+     */
+    generateTextLocator(text, exact = false) {
+        const locator = exact ? `text="${text}"` : `text~="${text}"`;
+        return {
+            locator,
+            type: 'text',
+            confidence: exact ? 0.85 : 0.7,
+            description: `Text content${exact ? ' (exact)' : ' (partial)'}`,
+        };
+    }
+    /**
+     * Generate a CSS selector locator
+     */
+    generateCssLocator(selector) {
+        return {
+            locator: selector,
+            type: 'css',
+            confidence: 0.8,
+            description: 'CSS selector',
+        };
+    }
+    /**
+     * Get the maximum number of candidates to return
+     */
+    getMaxCandidates() {
+        return this.maxCandidates;
+    }
+    /**
+     * Set the maximum number of candidates to return
+     */
+    setMaxCandidates(max) {
+        this.maxCandidates = max;
+    }
+    /**
+     * Get the preferred strategies in order
+     */
+    getPreferredStrategies() {
+        return [...this.preferredStrategies];
+    }
+}
+//# sourceMappingURL=locator-candidates.js.map

package/dist/locator-candidates.js.map

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

package/dist/step-executor.d.ts

@@ -0,0 +1,99 @@
+import type { BrowserSession } from './explorer';
+import type { SpecStep, StepResult, StepExecution, AIAdapter } from './adapters/types';
+/**
+ * Configuration for step execution
+ */
+export interface StepExecutorConfig {
+    browser?: BrowserSession;
+    adapter?: AIAdapter;
+    baseUrl?: string;
+    defaultTimeout?: number;
+    screenshotDir?: string;
+    captureBeforeScreenshots?: boolean;
+    captureAfterScreenshots?: boolean;
+    customActionHandlers?: Record<string, (step: SpecStep, browser: BrowserSession) => Promise<StepExecution>>;
+}
+/**
+ * StepExecutor - Executes individual spec steps against a browser session
+ *
+ * Handles:
+ * - Navigation: navigate, back, forward, refresh
+ * - Interaction: click, fill, type, select, check, press
+ * - Waiting: wait for element, text, url, time
+ * - Assertions: verify_state with various checks
+ * - Capture: screenshot, scroll
+ */
+export declare class StepExecutor {
+    private browser?;
+    private adapter?;
+    private baseUrl;
+    private defaultTimeout;
+    private screenshotDir;
+    private captureBeforeScreenshots;
+    private captureAfterScreenshots;
+    private customActionHandlers;
+    constructor(config?: StepExecutorConfig);
+    /**
+     * Configure the executor with browser and adapter (for lazy initialization)
+     */
+    configure(config: {
+        browser?: BrowserSession;
+        adapter?: AIAdapter;
+        baseUrl?: string;
+    }): void;
+    /**
+     * Check if executor is properly configured
+     */
+    isConfigured(): boolean;
+    /**
+     * Execute a single step
+     *
+     * @param step - The step definition from the spec
+     * @param stepIndex - Index of this step in the spec
+     * @returns Promise resolving to step result
+     */
+    execute(step: SpecStep, stepIndex?: number): Promise<StepResult>;
+    /**
+     * Execute a single action based on step type
+     */
+    private executeAction;
+    private executeNavigate;
+    private executeBack;
+    private executeForward;
+    private executeRefresh;
+    private executeClick;
+    private executeFill;
+    private executeType;
+    private executeSelect;
+    private executeCheck;
+    private executePress;
+    private executeWait;
+    private executeVerifyState;
+    private executeScreenshot;
+    private executeScroll;
+    private executeScrollIntoView;
+    private executeIdentifyElement;
+    private executeAIVerify;
+    private executeCustom;
+    /**
+     * Resolve target to element ref
+     */
+    private resolveTarget;
+    /**
+     * Find element in snapshot by selector/query
+     */
+    private findElementInSnapshot;
+    /**
+     * Capture a screenshot
+     */
+    private captureScreenshot;
+    /**
+     * Get the default timeout value
+     */
+    getDefaultTimeout(): number;
+    /**
+     * Get the screenshot directory
+     */
+    getScreenshotDir(): string;
+}
+//# sourceMappingURL=step-executor.d.ts.map

package/dist/step-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-executor.d.ts","sourceRoot":"","sources":["../src/step-executor.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EACV,QAAQ,EACR,UAAU,EACV,aAAa,EACb,SAAS,EAGV,MAAM,kBAAkB,CAAC;AAe1B;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,oBAAoB,CAAC,EAAE,MAAM,CAC3B,MAAM,EACN,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,aAAa,CAAC,CACpE,CAAC;CACH;AAUD;;;;;;;;;GASG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAC,CAAiB;IACjC,OAAO,CAAC,OAAO,CAAC,CAAY;IAC5B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,wBAAwB,CAAU;IAC1C,OAAO,CAAC,uBAAuB,CAAU;IACzC,OAAO,CAAC,oBAAoB,CAG1B;gBAEU,MAAM,GAAE,kBAAuB;IAW3C;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE;QAAE,OAAO,CAAC,EAAE,cAAc,CAAC;QAAC,OAAO,CAAC,EAAE,SAAS,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAM5F;;OAEG;IACH,YAAY,IAAI,OAAO;IAIvB;;;;;;OAMG;IACG,OAAO,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,GAAE,MAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAwEzE;;OAEG;YACW,aAAa;YAiEb,eAAe;YAsBf,WAAW;YAWX,cAAc;YAWd,cAAc;YAad,YAAY;YAyBZ,WAAW;YA0BX,WAAW;YA0BX,aAAa;YA0Bb,YAAY;YA0BZ,YAAY;YAwBZ,WAAW;YAiDX,kBAAkB;YA8ElB,iBAAiB;YASjB,aAAa;YAeb,qBAAqB;YA0BrB,sBAAsB;YA8BtB,eAAe;YAYf,aAAa;IAgB3B;;OAEG;YACW,aAAa;IA0B3B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAyB7B;;OAEG;YACW,iBAAiB;IAgB/B;;OAEG;IACH,iBAAiB,IAAI,MAAM;IAI3B;;OAEG;IACH,gBAAgB,IAAI,MAAM;CAG3B"}