playwright-mimic 0.1.0 → 0.1.1

package/dist/mimic/schema/action.js

@@ -0,0 +1,204 @@
+// zod-schemas.ts
+import { z } from "zod";
+/**
+ * Shared: identifiers and primitive helpers
+ */
+export const zPoint = z.object({
+    x: z.number().describe("X coordinate relative to the page or element bounding box."),
+    y: z.number().describe("Y coordinate relative to the page or element bounding box."),
+});
+export const zMouseButton = z.enum(["left", "middle", "right"]).describe("Mouse button to use.");
+export const zModifierKeys = z
+    .array(z.enum(["Alt", "Control", "Meta", "Shift"]))
+    .describe("Zero or more modifier keys held for this action.")
+    .default([]);
+export const zFrameDescription = z.object({
+    pageGuid: z.string().describe("Stable GUID for the page instance."),
+    pageAlias: z.string().describe("Human-friendly alias for the page (e.g., 'main', 'popup-1')."),
+    framePath: z.array(z.string()).describe("Ordered list of frame selectors/aliases from top to target frame."),
+});
+/**
+ * ACTION INTENT (PASS 1): coarse category only
+ * Keep this small so an LLM can commit early with high accuracy.
+ */
+export const zActionKind = z
+    .enum(["click", "form update", "navigation", "assertion", "other"])
+    .describe("High-level action category.");
+export const zGeneralActionPlan = z.object({
+    kind: zActionKind.describe("Coarse action category chosen first."),
+    description: z
+        .string()
+        .describe("the reasoning behind the classification based on the literal intent of the Gherkin step."),
+});
+/**
+ * ACTION SUBTYPE (PASS 2): constrained sub-choices within the category? maybe add as object with values or special
+ */
+export const zMouseType = z
+    .enum(["click", "doubleClick", "hover"])
+    .describe("Specific mouse action.");
+export const zFormUpdateTypes = z
+    .enum(["press", "type", "fill", 'select', 'uncheck', 'check', 'setInputFiles', 'clear'])
+    .describe("Specific form action to update the form.");
+export const zNavigationType = z
+    .enum(["openPage", "navigate", "closePage", 'goBack', 'goForward', 'refresh', 'openInNewTab'])
+    .describe("Specific navigation action.");
+export const zAssertionType = z
+    .enum(["text visible", "value visible", "checked visible", "aria snapshot visible", "screenshot of element"])
+    .describe("Assertion subtype.");
+export const zMouseAction = z.object({
+    type: zMouseType,
+    params: z.object({
+        button: zMouseButton.nullish().default("left").describe("Optional, mouse button to use, not needed for hover, for others it will be left click by default."),
+        position: zPoint.nullish().describe("Optional relative offset inside the target element."),
+        modifiers: zModifierKeys.nullish().describe("Optional modifier keys to use, not needed for hover, for others it will be no modifiers by default."),
+    }),
+});
+export const zFormUpdateAction = z.object({
+    type: zFormUpdateTypes,
+    params: z.object({
+        value: z.string().describe("Value to set for the form update."),
+        modifiers: zModifierKeys.nullish().describe("Optional modifier keys to use for the form update."),
+    }),
+});
+// TODO: navigation or opening pop ups needs more work most likely
+export const zNavigationAction = z.object({
+    type: zNavigationType,
+    params: z.object({
+        url: z
+            .string()
+            .nullable()
+            .describe("URL to navigate to. Must be a valid URL (starting with http:// or https://) for 'openPage' and 'navigate' types. Empty string for other navigation types (goBack, goForward, refresh, closePage)."),
+    }),
+    /**
+     * Human-readable description of this navigation action for test annotations
+     * Should clearly describe what navigation is happening (e.g., "Navigate to login page", "Go back to previous page")
+     */
+    description: z.string().describe("Human-readable description of this navigation action for test annotations"),
+});
+/**
+ * Click action result schema
+ * Contains top candidate elements matched against a Gherkin step
+ */
+export const zClickActionResult = z.object({
+    /**
+     * Array of up to 5 candidate elements, ranked by likelihood
+     * Each candidate includes its index in the original TargetInfo array
+     */
+    candidates: z
+        .array(z.object({
+        /**
+         * Index in the original TargetInfo array (0-based)
+         * Used to reference back to the captured element
+         */
+        index: z.number().int().min(0).describe("Index in the original TargetInfo array (0-based)"),
+        /**
+         * Element tag name (e.g., 'button', 'a', 'input')
+         */
+        tag: z.string().describe("Element tag name"),
+        /**
+         * Visible text content of the element
+         */
+        text: z.string().describe("Visible text content"),
+        /**
+         * Element ID attribute if present
+         */
+        id: z.string().nullable().describe("Element ID attribute if present"),
+        /**
+         * Inferred or explicit ARIA role
+         */
+        role: z.string().nullable().describe("Inferred or explicit ARIA role"),
+        /**
+         * Associated label text (from label element or aria-labelledby)
+         */
+        label: z.string().nullable().describe("Associated label text"),
+        /**
+         * aria-label attribute value
+         */
+        ariaLabel: z.string().nullable().describe("aria-label attribute value"),
+        /**
+         * Optional confidence score (0-1) indicating match likelihood
+         * Using nullable instead of optional for compatibility with OpenAI structured outputs
+         */
+        confidence: z.number().min(0).nullable().describe("Confidence score (0-1) indicating match likelihood"),
+        /**
+         * Human-readable description of this element for test annotations
+         * Should be a clear, concise description that identifies the element (e.g., "Submit button", "Login link", "Email input field")
+         */
+        description: z.string().describe("Human-readable description of this element for test annotations"),
+    }))
+        .max(5)
+        .describe("Top 5 candidate elements ranked by likelihood"),
+    /**
+     * Single click type for all candidates
+     * Determined from the Gherkin step (e.g., "right click", "double click")
+     */
+    clickType: z
+        .enum(["left", "right", "double", "middle", "hover"])
+        .describe("Click type determined from the Gherkin step"),
+    /**
+     * Brief explanation of the matching logic and reasoning
+     */
+    reasoning: z.string().describe("Brief explanation of the matching logic and reasoning"),
+});
+// TODO: this maybe needs to be more complex? to make sure it gives the right value and such
+export const zAssertionAction = z.object({
+    type: zAssertionType,
+    params: z.object({
+        expected: z.string().describe("Expected value to assert."),
+    }),
+});
+// TODO: this probably will need to just be logged for now
+export const zOtherAction = z.object({
+    type: z.literal("custom"),
+    params: z.record(z.string(), z.unknown()).describe("Custom parameters for the action."),
+});
+/**
+ * ACTION SUBTYPE (PASS 2): Union of all subtype schemas with kind
+ * This allows progressive refinement: first get kind, then get specific subtype.
+ */
+export const zActionPass2 = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("mouse") }).merge(zMouseAction),
+    z.object({ kind: z.literal("form update") }).merge(zFormUpdateAction),
+    z.object({ kind: z.literal("navigation") }).merge(zNavigationAction),
+    z.object({ kind: z.literal("assertion") }).merge(zAssertionAction),
+    z.object({ kind: z.literal("other") }).merge(zOtherAction),
+]).describe("Action subtype determined after choosing action kind.");
+/**
+ * ACTION DETAILS (PASS 3): parameters, selector link, and signals
+ * Each subtype has a focused schema to minimize ambiguity.
+ */
+// Mouse params
+export const zMouseParams = z.object({
+    button: zMouseButton.default("left"),
+    clickCount: z.number().int().min(1).max(2).default(1).describe("1 for click, 2 for double-click."),
+    position: zPoint.nullish().describe("Optional relative offset inside the target element."),
+    modifiers: zModifierKeys,
+});
+// Keyboard params
+export const zKeyboardPressParams = z.object({
+    key: z
+        .string()
+        .describe("Single key to press. Use Playwright key names (e.g., 'Enter', 'Tab', 'ArrowDown', 'Control+K')."),
+    modifiers: zModifierKeys,
+});
+export const zKeyboardTypeParams = z.object({
+    text: z.string().describe("Literal text to type (respects existing cursor/focus)."),
+    delayMs: z.number().int().min(0).default(0).describe("Optional delay per character."),
+});
+export const zKeyboardFillParams = z.object({
+    value: z.string().describe("Final value of the input after filling (replaces existing content)."),
+});
+// Navigation params
+export const zOpenPageParams = z.object({
+    url: z.string().url().describe("Absolute URL to open in a new page/tab/context."),
+});
+export const zNavigateParams = z.object({
+    url: z.string().describe("URL or path to navigate current page to."),
+});
+export const zClosePageParams = z.object({
+    reason: z.string().nullish().describe("Optional rationale for closing (cleanup, end of flow, etc.)."),
+});
+// export type SelectorPlan = z.infer<typeof zSelectorPlan>;
+// export type ActionPlan = z.infer<typeof zActionPlan>;
+// export type ActionInContext = z.infer<typeof zActionInContext>;
+//# sourceMappingURL=action.js.map

package/dist/mimic/schema/action.js.map

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

package/dist/mimic/selector.d.ts

@@ -0,0 +1,139 @@
+import { Locator, Page } from '@playwright/test';
+import type { SelectorDescriptor } from './selectorDescriptor.js';
+/**
+ * TargetInfo: Normalized metadata for a candidate element
+ *
+ * This represents an element that could be targeted by a Gherkin step.
+ * Collected via Playwright page.evaluate in the browser context.
+ */
+export type TargetInfo = {
+    tag: string;
+    text: string;
+    id: string | null;
+    role: string | null;
+    label: string | null;
+    ariaLabel: string | null;
+    typeAttr: string | null;
+    nameAttr: string | null;
+    href: string | null;
+    dataset: Record<string, string>;
+    nthOfType: number;
+};
+/**
+ * Element category types for classification
+ */
+export type ElementCategory = 'clickable' | 'form' | 'text';
+/**
+ * Comprehensive element information for selector generation
+ */
+export interface SelectorElement {
+    /** Element category: clickable, form, or text */
+    category: ElementCategory;
+    /** HTML tag name */
+    tag: string;
+    /** Primary visible text content */
+    text: string;
+    /** All text-related attributes combined for context */
+    descriptiveText: string;
+    /** Element ID if present */
+    id: string | null;
+    /** Inferred or explicit ARIA role */
+    role: string | null;
+    /** Associated label text */
+    label: string | null;
+    /** aria-label attribute */
+    ariaLabel: string | null;
+    /** alt text for images */
+    altText: string | null;
+    /** title attribute */
+    title: string | null;
+    /** placeholder text for inputs */
+    placeholder: string | null;
+    /** aria-describedby text */
+    ariaDescribedBy: string | null;
+    /** Input type attribute */
+    typeAttr: string | null;
+    /** Name attribute */
+    nameAttr: string | null;
+    /** href for links */
+    href: string | null;
+    /** value attribute for form elements */
+    value: string | null;
+    /** All data-* attributes */
+    dataset: Record<string, string>;
+    /** nth-of-type index (1-based) */
+    nthOfType: number;
+    /** CSS selector path for this element */
+    selector: string;
+    /** Whether element is visible */
+    isVisible: boolean;
+}
+/**
+ * Result structure containing all categorized elements
+ */
+export interface SelectorResult {
+    /** All clickable/interactive elements (buttons, links, etc.) */
+    clickableElements: SelectorElement[];
+    /** All form input elements */
+    formElements: SelectorElement[];
+    /** All text/content elements */
+    textElements: SelectorElement[];
+    /** Total count of all elements */
+    totalCount: number;
+}
+/**
+ * Options for capturing target elements
+ */
+export interface CaptureTargetsOptions {
+    /**
+     * If true, only capture interactable elements (buttons, links, inputs, etc.)
+     * If false (default), capture both interactive and content elements
+     */
+    interactableOnly?: boolean;
+}
+/**
+ * Capture target elements from the page
+ *
+ * @param page - Playwright Page object
+ * @param options - Optional configuration for capturing targets
+ * @returns Promise resolving to array of TargetInfo objects
+ */
+export declare function captureTargets(page: Page, options?: CaptureTargetsOptions): Promise<TargetInfo[]>;
+/**
+ * Build the best Playwright locator for a given target element
+ *
+ * Follows Playwright's recommended selector priority:
+ * 1. data-testid (use page.getByTestId()) - #1 recommendation, most stable
+ * 2. Role-based (use page.getByRole()) - #2 recommendation, accessibility-based
+ * 3. Text-based (use page.getByText()) - #3 recommendation, good for visible text
+ * 4. CSS selectors as fallback (ID, data attributes, name, tag selectors)
+ *
+ * If a locator matches multiple elements, this function will evaluate each
+ * and return the one that best matches the target information.
+ *
+ * @param page - Playwright Page object
+ * @param target - TargetInfo object containing element metadata
+ * @returns Playwright Locator for the target element, prioritized by Playwright's best practices
+ */
+export declare function buildSelectorForTarget(page: Page, target?: TargetInfo): Promise<Locator | null>;
+/**
+ * Generate the best Playwright selector for a given element
+ *
+ * Analyzes an element and its parent hierarchy to find the best selector
+ * following Playwright's recommended practices. Verifies uniqueness at each step.
+ *
+ * Priority order:
+ * 1. data-testid → getByTestId()
+ * 2. role + name (aria-label/label) → getByRole()
+ * 3. label → getByLabel()
+ * 4. placeholder → getByPlaceholder()
+ * 5. alt → getByAltText()
+ * 6. title → getByTitle()
+ * 7. text → getByText()
+ * 8. CSS fallback (ID, name, tag + nth-of-type)
+ *
+ * @param locator - Playwright Locator pointing to the target element
+ * @returns Promise resolving to SelectorDescriptor that uniquely identifies the element
+ */
+export declare function generateBestSelectorForElement(locator: Locator): Promise<SelectorDescriptor>;
+//# sourceMappingURL=selector.d.ts.map

package/dist/mimic/selector.d.ts.map

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