playwright-mimic 0.1.0 → 0.1.1

package/dist/mimic/selectorUtils.js

@@ -0,0 +1,144 @@
+/**
+ * Reconstruct a Playwright Locator from a stored SelectorDescriptor
+ *
+ * This function recursively builds a locator from a selector descriptor,
+ * handling nested selectors by chaining locator method calls.
+ *
+ * @param page - Playwright Page object (or parent Locator for nested selectors)
+ * @param descriptor - SelectorDescriptor (can be from JSON)
+ * @returns Playwright Locator reconstructed from the descriptor
+ */
+export function getFromSelector(page, descriptor) {
+    let baseLocator;
+    // Build base locator based on selector type
+    // Both Page and Locator have the same locator methods, so we can call them directly
+    switch (descriptor.type) {
+        case 'testid':
+            baseLocator = page.getByTestId(descriptor.value);
+            break;
+        case 'role':
+            if (descriptor.name !== undefined) {
+                // Handle regex patterns
+                const nameValue = descriptor.name instanceof RegExp
+                    ? descriptor.name
+                    : descriptor.name;
+                const roleOptions = descriptor.name instanceof RegExp
+                    ? { name: nameValue }
+                    : { name: nameValue, exact: descriptor.exact ?? false };
+                baseLocator = page.getByRole(descriptor.role, roleOptions);
+            }
+            else {
+                baseLocator = page.getByRole(descriptor.role);
+            }
+            break;
+        case 'label':
+            {
+                const labelOptions = descriptor.value instanceof RegExp
+                    ? {}
+                    : { exact: descriptor.exact ?? false };
+                baseLocator = page.getByLabel(descriptor.value, labelOptions);
+            }
+            break;
+        case 'placeholder':
+            {
+                const placeholderOptions = descriptor.value instanceof RegExp
+                    ? {}
+                    : { exact: descriptor.exact ?? false };
+                baseLocator = page.getByPlaceholder(descriptor.value, placeholderOptions);
+            }
+            break;
+        case 'alt':
+            {
+                const altOptions = descriptor.value instanceof RegExp
+                    ? {}
+                    : { exact: descriptor.exact ?? false };
+                baseLocator = page.getByAltText(descriptor.value, altOptions);
+            }
+            break;
+        case 'title':
+            {
+                const titleOptions = descriptor.value instanceof RegExp
+                    ? {}
+                    : { exact: descriptor.exact ?? false };
+                baseLocator = page.getByTitle(descriptor.value, titleOptions);
+            }
+            break;
+        case 'text':
+            {
+                const textOptions = descriptor.value instanceof RegExp
+                    ? {}
+                    : { exact: descriptor.exact ?? false };
+                baseLocator = page.getByText(descriptor.value, textOptions);
+            }
+            break;
+        case 'css':
+            baseLocator = page.locator(descriptor.selector);
+            break;
+        default:
+            // TypeScript exhaustiveness check - if we reach here, a case is missing
+            const _exhaustive = descriptor;
+            void _exhaustive; // Suppress unused variable warning
+            throw new Error(`Unknown selector type: ${descriptor.type}`);
+    }
+    // If there's a nested child selector, recursively build it from the base locator
+    if (descriptor.child) {
+        return getFromSelector(baseLocator, descriptor.child);
+    }
+    return baseLocator;
+}
+/**
+ * Verify that a selector uniquely identifies the target element
+ *
+ * This function checks if a locator built from a SelectorDescriptor matches
+ * exactly one element, and optionally verifies it matches the original target element.
+ *
+ * @param page - Playwright Page object
+ * @param descriptor - SelectorDescriptor to verify
+ * @param targetElementHandle - Optional element handle to verify the match is correct
+ * @returns Promise resolving to true if selector is unique (and matches target if provided)
+ */
+export async function verifySelectorUniqueness(page, descriptor, targetElementHandle) {
+    try {
+        const locator = getFromSelector(page, descriptor);
+        const count = await locator.count();
+        // Must match exactly one element
+        if (count !== 1) {
+            return false;
+        }
+        // If target element provided, verify it's the same element
+        if (targetElementHandle) {
+            const matchedElement = await locator.elementHandle();
+            if (!matchedElement) {
+                return false;
+            }
+            // Compare elements by checking if they have the same properties
+            // We'll compare by getting a unique identifier from both elements
+            const targetId = await page.evaluate((el) => {
+                // Create a unique identifier: tag + id + text + position
+                const rect = el.getBoundingClientRect();
+                return JSON.stringify({
+                    tag: el.tagName,
+                    id: el.id,
+                    text: (el.textContent || '').substring(0, 50),
+                    position: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
+                });
+            }, targetElementHandle);
+            const matchedId = await page.evaluate((el) => {
+                const rect = el.getBoundingClientRect();
+                return JSON.stringify({
+                    tag: el.tagName,
+                    id: el.id,
+                    text: (el.textContent || '').substring(0, 50),
+                    position: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
+                });
+            }, matchedElement);
+            return targetId === matchedId;
+        }
+        return true;
+    }
+    catch (error) {
+        // If selector is invalid or throws, it's not unique
+        return false;
+    }
+}
+//# sourceMappingURL=selectorUtils.js.map

package/dist/mimic/selectorUtils.js.map

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

package/dist/mimic/storage.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Snapshot Storage Module
+ *
+ * Handles reading, writing, and managing test execution snapshots.
+ * Snapshots store successful test executions as JSON files for fast replay.
+ */
+import type { Snapshot } from './types.js';
+/**
+ * Generate a hash from test text to create a unique identifier
+ *
+ * @param testText - The test text (mimic template string)
+ * @returns SHA-256 hash of the test text (first 16 characters for readability)
+ */
+export declare function hashTestText(testText: string): string;
+/**
+ * Get the snapshot directory path for a test file
+ *
+ * @param testFilePath - Directory path of the test file
+ * @returns Path to the .mimic-snapshots directory
+ */
+export declare function getSnapshotDir(testFilePath: string): string;
+/**
+ * Get the snapshot file path for a specific test
+ *
+ * @param testFilePath - Directory path of the test file
+ * @param testHash - Hash identifier for the test
+ * @returns Full path to the snapshot JSON file
+ */
+export declare function getSnapshotPath(testFilePath: string, testHash: string): string;
+/**
+ * Read a snapshot from disk
+ *
+ * @param testFilePath - Directory path of the test file
+ * @param testHash - Hash identifier for the test
+ * @returns Snapshot object if found, null otherwise
+ */
+export declare function getSnapshot(testFilePath: string, testHash: string): Promise<Snapshot | null>;
+/**
+ * Save a snapshot to disk
+ *
+ * @param testFilePath - Directory path of the test file
+ * @param snapshot - Snapshot object to save
+ * @returns Promise that resolves when snapshot is saved
+ */
+export declare function saveSnapshot(testFilePath: string, snapshot: Snapshot): Promise<void>;
+/**
+ * Record a test failure timestamp
+ *
+ * Updates the snapshot's lastFailedAt timestamp if the snapshot exists.
+ *
+ * @param testFilePath - Directory path of the test file
+ * @param testHash - Hash identifier for the test
+ * @param failedStepIndex - Index of the step that failed (optional)
+ * @param failedStepText - Text of the step that failed (optional)
+ * @param error - Error message (optional)
+ * @returns Promise that resolves when failure is recorded
+ */
+export declare function recordFailure(testFilePath: string, testHash: string, failedStepIndex?: number, failedStepText?: string, error?: string): Promise<void>;
+/**
+ * Determine if a snapshot should be used for replay
+ *
+ * A snapshot should be used if:
+ * - It exists
+ * - lastPassedAt is more recent than lastFailedAt (or lastFailedAt is null)
+ *
+ * Note: Even in troubleshoot mode, we use snapshots if they've passed.
+ * Regeneration only happens if replay fails.
+ *
+ * @param testFilePath - Directory path of the test file
+ * @param testHash - Hash identifier for the test
+ * @param troubleshootMode - Whether troubleshoot mode is enabled (unused, kept for compatibility)
+ * @returns true if snapshot should be used, false otherwise
+ */
+export declare function shouldUseSnapshot(testFilePath: string, testHash: string, _troubleshootMode?: boolean, expectedStepCount?: number): Promise<boolean>;
+//# sourceMappingURL=storage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/mimic/storage.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIrD;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAG9E;AAoBD;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAoB1B;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CACjC,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,eAAe,CAAC,EAAE,MAAM,EACxB,cAAc,CAAC,EAAE,MAAM,EACvB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAiCf;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,iBAAiB,CACrC,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,iBAAiB,GAAE,OAAe,EAClC,iBAAiB,CAAC,EAAE,MAAM,GACzB,OAAO,CAAC,OAAO,CAAC,CAwClB"}

package/dist/mimic/storage.js

@@ -0,0 +1,197 @@
+/**
+ * Snapshot Storage Module
+ *
+ * Handles reading, writing, and managing test execution snapshots.
+ * Snapshots store successful test executions as JSON files for fast replay.
+ */
+import { createHash } from 'crypto';
+import fs from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * Generate a hash from test text to create a unique identifier
+ *
+ * @param testText - The test text (mimic template string)
+ * @returns SHA-256 hash of the test text (first 16 characters for readability)
+ */
+export function hashTestText(testText) {
+    const hash = createHash('sha256');
+    hash.update(testText.trim());
+    return hash.digest('hex').substring(0, 16);
+}
+/**
+ * Get the snapshot directory path for a test file
+ *
+ * @param testFilePath - Directory path of the test file
+ * @returns Path to the .mimic-snapshots directory
+ */
+export function getSnapshotDir(testFilePath) {
+    return join(testFilePath, '.mimic-snapshots');
+}
+/**
+ * Get the snapshot file path for a specific test
+ *
+ * @param testFilePath - Directory path of the test file
+ * @param testHash - Hash identifier for the test
+ * @returns Full path to the snapshot JSON file
+ */
+export function getSnapshotPath(testFilePath, testHash) {
+    const snapshotDir = getSnapshotDir(testFilePath);
+    return join(snapshotDir, `${testHash}.json`);
+}
+/**
+ * Ensure the snapshot directory exists
+ *
+ * @param testFilePath - Directory path of the test file
+ * @returns Promise that resolves when directory is created or already exists
+ */
+async function ensureSnapshotDir(testFilePath) {
+    const snapshotDir = getSnapshotDir(testFilePath);
+    try {
+        await fs.mkdir(snapshotDir, { recursive: true });
+    }
+    catch (error) {
+        // Directory might already exist, which is fine
+        if (error instanceof Error && !error.message.includes('EEXIST')) {
+            throw error;
+        }
+    }
+}
+/**
+ * Read a snapshot from disk
+ *
+ * @param testFilePath - Directory path of the test file
+ * @param testHash - Hash identifier for the test
+ * @returns Snapshot object if found, null otherwise
+ */
+export async function getSnapshot(testFilePath, testHash) {
+    if (!testFilePath) {
+        return null;
+    }
+    const snapshotPath = getSnapshotPath(testFilePath, testHash);
+    try {
+        const content = await fs.readFile(snapshotPath, 'utf-8');
+        const snapshot = JSON.parse(content);
+        return snapshot;
+    }
+    catch (error) {
+        // File doesn't exist or is invalid - return null
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return null;
+        }
+        // For other errors (parse errors, etc.), log and return null
+        console.warn(`Failed to read snapshot at ${snapshotPath}:`, error);
+        return null;
+    }
+}
+/**
+ * Save a snapshot to disk
+ *
+ * @param testFilePath - Directory path of the test file
+ * @param snapshot - Snapshot object to save
+ * @returns Promise that resolves when snapshot is saved
+ */
+export async function saveSnapshot(testFilePath, snapshot) {
+    if (!testFilePath) {
+        return;
+    }
+    await ensureSnapshotDir(testFilePath);
+    const snapshotPath = getSnapshotPath(testFilePath, snapshot.testHash);
+    // Update timestamps
+    const now = new Date().toISOString();
+    snapshot.lastPassedAt = now;
+    if (!snapshot.createdAt) {
+        snapshot.createdAt = now;
+    }
+    await fs.writeFile(snapshotPath, JSON.stringify(snapshot, null, 2), 'utf-8');
+}
+/**
+ * Record a test failure timestamp
+ *
+ * Updates the snapshot's lastFailedAt timestamp if the snapshot exists.
+ *
+ * @param testFilePath - Directory path of the test file
+ * @param testHash - Hash identifier for the test
+ * @param failedStepIndex - Index of the step that failed (optional)
+ * @param failedStepText - Text of the step that failed (optional)
+ * @param error - Error message (optional)
+ * @returns Promise that resolves when failure is recorded
+ */
+export async function recordFailure(testFilePath, testHash, failedStepIndex, failedStepText, error) {
+    if (!testFilePath) {
+        return;
+    }
+    const snapshot = await getSnapshot(testFilePath, testHash);
+    if (!snapshot) {
+        // Create a minimal snapshot just for failure tracking
+        const failureSnapshot = {
+            testHash,
+            testText: '',
+            createdAt: new Date().toISOString(),
+            lastPassedAt: null,
+            lastFailedAt: new Date().toISOString(),
+            steps: [],
+        };
+        await saveSnapshot(testFilePath, failureSnapshot);
+        return;
+    }
+    // Update existing snapshot with failure info
+    snapshot.lastFailedAt = new Date().toISOString();
+    // Store failure details if provided
+    if (failedStepIndex !== undefined || failedStepText || error) {
+        snapshot.failureDetails = {
+            failedStepIndex,
+            failedStepText,
+            error,
+        };
+    }
+    await saveSnapshot(testFilePath, snapshot);
+}
+/**
+ * Determine if a snapshot should be used for replay
+ *
+ * A snapshot should be used if:
+ * - It exists
+ * - lastPassedAt is more recent than lastFailedAt (or lastFailedAt is null)
+ *
+ * Note: Even in troubleshoot mode, we use snapshots if they've passed.
+ * Regeneration only happens if replay fails.
+ *
+ * @param testFilePath - Directory path of the test file
+ * @param testHash - Hash identifier for the test
+ * @param troubleshootMode - Whether troubleshoot mode is enabled (unused, kept for compatibility)
+ * @returns true if snapshot should be used, false otherwise
+ */
+export async function shouldUseSnapshot(testFilePath, testHash, _troubleshootMode = false, expectedStepCount) {
+    // Use snapshots even in troubleshoot mode if they've passed
+    // Regeneration will happen only if replay fails
+    if (!testFilePath) {
+        return false;
+    }
+    const snapshot = await getSnapshot(testFilePath, testHash);
+    if (!snapshot) {
+        return false;
+    }
+    // Validate that snapshot has at least as many steps as expected input lines
+    if (expectedStepCount !== undefined) {
+        // Count unique steps in snapshot (by stepIndex)
+        const uniqueStepIndices = new Set(snapshot.steps.map((step) => step.stepIndex));
+        const snapshotStepCount = uniqueStepIndices.size;
+        if (snapshotStepCount < expectedStepCount) {
+            // Snapshot is incomplete - don't use it
+            return false;
+        }
+    }
+    // If never passed, don't use snapshot
+    if (!snapshot.lastPassedAt) {
+        return false;
+    }
+    // If never failed, use snapshot
+    if (!snapshot.lastFailedAt) {
+        return true;
+    }
+    // Compare timestamps: use snapshot if pass is more recent than failure
+    const passTime = new Date(snapshot.lastPassedAt).getTime();
+    const failTime = new Date(snapshot.lastFailedAt).getTime();
+    return passTime > failTime;
+}
+//# sourceMappingURL=storage.js.map

package/dist/mimic/storage.js.map

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

package/dist/mimic/types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Snapshot-related Type Definitions
+ *
+ * Types for storing and replaying test execution snapshots.
+ */
+import type { NavigationAction } from './schema/action.js';
+import type { ClickActionResult } from './schema/action.js';
+import type { FormActionResult } from './forms.js';
+import type { TargetInfo } from './selector.js';
+/**
+ * A single step in a test execution snapshot
+ */
+export interface SnapshotStep {
+    /** Index of the step in the test (0-based) */
+    stepIndex: number;
+    /** Original step text (Gherkin step) */
+    stepText: string;
+    /** Type of action (navigation, click, form update) */
+    actionKind: 'navigation' | 'click' | 'form update';
+    /** Full action details (varies by actionKind) */
+    actionDetails: NavigationAction | ClickActionResult | FormActionResult;
+    /** Target element information (for click and form actions) */
+    targetElement?: TargetInfo & {
+        selector?: string;
+    };
+    /** Timestamp when this step was executed */
+    executedAt: string;
+}
+/**
+ * Complete snapshot of a test execution
+ */
+export interface Snapshot {
+    /** Hash identifier for this test */
+    testHash: string;
+    /** Original test text (mimic template string) */
+    testText: string;
+    /** When this snapshot was first created */
+    createdAt: string;
+    /** When the test last passed (ISO timestamp) */
+    lastPassedAt: string | null;
+    /** When the test last failed (ISO timestamp, null if never failed) */
+    lastFailedAt: string | null;
+    /** Array of executed steps */
+    steps: SnapshotStep[];
+}
+/**
+ * Result of executing a single step (for snapshot creation)
+ */
+export interface StepExecutionResult {
+    /** Index of the step in the test (0-based) */
+    stepIndex: number;
+    /** Original step text (Gherkin step) */
+    stepText: string;
+    /** Type of action (navigation, click, form update) */
+    actionKind: 'navigation' | 'click' | 'form update';
+    /** Full action details (varies by actionKind) */
+    actionDetails: NavigationAction | ClickActionResult | FormActionResult;
+    /** Target element information (for click and form actions) */
+    targetElement?: TargetInfo & {
+        selector?: string;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/mimic/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,UAAU,EAAE,YAAY,GAAG,OAAO,GAAG,aAAa,CAAC;IACnD,iDAAiD;IACjD,aAAa,EAAE,gBAAgB,GAAG,iBAAiB,GAAG,gBAAgB,CAAC;IACvE,8DAA8D;IAC9D,aAAa,CAAC,EAAE,UAAU,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,sEAAsE;IACtE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,8BAA8B;IAC9B,KAAK,EAAE,YAAY,EAAE,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,UAAU,EAAE,YAAY,GAAG,OAAO,GAAG,aAAa,CAAC;IACnD,iDAAiD;IACjD,aAAa,EAAE,gBAAgB,GAAG,iBAAiB,GAAG,gBAAgB,CAAC;IACvE,8DAA8D;IAC9D,aAAa,CAAC,EAAE,UAAU,GAAG;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACpD"}

package/dist/mimic/types.js

@@ -0,0 +1,7 @@
+/**
+ * Snapshot-related Type Definitions
+ *
+ * Types for storing and replaying test execution snapshots.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/mimic/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/mimic/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/mimic.d.ts

@@ -4,23 +4,47 @@
 import { Page, TestInfo } from '@playwright/test';
 import type { LanguageModel } from 'ai';
 export type Mimic = (steps: TemplateStringsArray, ...args: unknown[]) => Promise<void>;
+/**
+ * Test context that tracks previous state and actions for better decision-making
+ */
+export interface TestContext {
+    /** Previous steps that have been executed */
+    previousSteps: Array<{
+        stepIndex: number;
+        stepText: string;
+        actionKind: string;
+        url?: string;
+        pageTitle?: string;
+    }>;
+    /** Current page state */
+    currentState: {
+        url: string;
+        pageTitle: string;
+    };
+    /** Total number of steps in the test */
+    totalSteps: number;
+    /** Current step index */
+    currentStepIndex: number;
+}
 /**
  * Minimal flow function that takes a Playwright page and input string
  *
  * @param page - Playwright Page object
  * @param input - Input string to process
+ * @param testFilePath - Directory path of the test file (for snapshot storage)
+ * @param troubleshootMode - Whether troubleshoot mode is enabled
  * @returns Flow execution result with validated context
  */
-export declare function mimic(input: string, { page, brains, testInfo }: {
+export declare function mimic(input: string, { page, brains, testInfo, testFilePath, troubleshootMode }: {
     page: Page;
     brains: LanguageModel;
-    eyes: LanguageModel;
-    testInfo?: TestInfo;
+    testInfo: TestInfo | undefined;
+    testFilePath?: string;
+    troubleshootMode?: boolean;
 }): Promise<void>;
 export declare const createMimic: (config: {
     page: Page;
     brains: LanguageModel;
-    eyes: LanguageModel;
     testInfo?: TestInfo;
 }) => (prompt: TemplateStringsArray, ...args: unknown[]) => Promise<void>;
 //# sourceMappingURL=mimic.d.ts.map

package/dist/mimic.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mimic.d.ts","sourceRoot":"","sources":["../src/mimic.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAQ,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AAQxC,MAAM,MAAM,KAAK,GAAG,CAAC,KAAK,EAAE,oBAAoB,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAGvF;;;;;;GAMG;AACH,wBAAsB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE;IACrE,IAAI,EAAE,IAAI,CAAC;IACX,MAAM,EAAE,aAAa,CAAC;IACtB,IAAI,EAAE,aAAa,CAAC;IACpB,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB,iBAwCA;AAeD,eAAO,MAAM,WAAW,GAAI,QAAQ;IAClC,IAAI,EAAE,IAAI,CAAC;IACX,MAAM,EAAE,aAAa,CAAC;IACtB,IAAI,EAAE,aAAa,CAAC;IACpB,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB,MACe,QAAQ,oBAAoB,EAAE,GAAG,MAAM,OAAO,EAAE,kBAI/D,CAAA"}
+{"version":3,"file":"mimic.d.ts","sourceRoot":"","sources":["../src/mimic.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAQ,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,IAAI,CAAC;AAiBxC,MAAM,MAAM,KAAK,GAAG,CAAC,KAAK,EAAE,oBAAoB,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEvF;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,aAAa,EAAE,KAAK,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC,CAAC;IACH,yBAAyB;IACzB,YAAY,EAAE;QACZ,GAAG,EAAE,MAAM,CAAC;QACZ,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,yBAAyB;IACzB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAoHD;;;;;;;;GAQG;AACH,wBAAsB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,gBAAgB,EAAE,EAAE;IACrG,IAAI,EAAE,IAAI,CAAC;IACX,MAAM,EAAE,aAAa,CAAC;IACtB,QAAQ,EAAE,QAAQ,GAAG,SAAS,CAAC;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B,iBAsUA;AAeD,eAAO,MAAM,WAAW,GAAI,QAAQ;IAClC,IAAI,EAAE,IAAI,CAAC;IACX,MAAM,EAAE,aAAa,CAAC;IACtB,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB,MASe,QAAQ,oBAAoB,EAAE,GAAG,MAAM,OAAO,EAAE,kBAU/D,CAAA"}