playwright-mimic 0.1.0 → 0.1.2

package/dist/mimic/selectorUtils.js

@@ -0,0 +1,251 @@
+import { jsonToStringOrRegex } from './selectorSerialization.js';
+import { getMimic } from './markers.js';
+/**
+ * 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.
+ *
+ * The descriptor uses JSON-serializable formats (StringOrRegexJson), which are
+ * converted to runtime formats (StringOrRegex) as needed when calling Playwright APIs.
+ *
+ * @param page - Playwright Page object (or parent Locator for nested selectors)
+ * @param descriptor - SelectorDescriptor (from JSON)
+ * @param depth - Current recursion depth (internal use, defaults to 0)
+ * @returns Playwright Locator reconstructed from the descriptor
+ */
+export function getFromSelector(page, descriptor, depth = 0) {
+    // Prevent infinite recursion by limiting depth to 10 levels
+    const MAX_DEPTH = 10;
+    if (depth >= MAX_DEPTH) {
+        throw new Error(`Maximum selector nesting depth (${MAX_DEPTH}) exceeded. This may indicate a circular reference in the selector 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) {
+                // Convert JSON format to runtime format for Playwright API
+                const nameValue = jsonToStringOrRegex(descriptor.name);
+                const isRegex = nameValue instanceof RegExp;
+                const roleOptions = isRegex
+                    ? { name: nameValue }
+                    : { name: nameValue, exact: descriptor.exact ?? false };
+                baseLocator = page.getByRole(descriptor.role, roleOptions);
+            }
+            else {
+                baseLocator = page.getByRole(descriptor.role);
+            }
+            // Apply nth() if specified (for radio groups, checkbox groups, etc.)
+            if (descriptor.nth !== undefined) {
+                baseLocator = baseLocator.nth(descriptor.nth);
+            }
+            break;
+        case 'label':
+            {
+                // Convert JSON format to runtime format
+                const labelValue = jsonToStringOrRegex(descriptor.value);
+                const isRegex = labelValue instanceof RegExp;
+                const labelOptions = isRegex
+                    ? {}
+                    : { exact: descriptor.exact ?? false };
+                baseLocator = page.getByLabel(labelValue, labelOptions);
+                // Apply nth() if specified
+                if (descriptor.nth !== undefined) {
+                    baseLocator = baseLocator.nth(descriptor.nth);
+                }
+            }
+            break;
+        case 'placeholder':
+            {
+                // Convert JSON format to runtime format
+                const placeholderValue = jsonToStringOrRegex(descriptor.value);
+                const isRegex = placeholderValue instanceof RegExp;
+                const placeholderOptions = isRegex
+                    ? {}
+                    : { exact: descriptor.exact ?? false };
+                baseLocator = page.getByPlaceholder(placeholderValue, placeholderOptions);
+            }
+            break;
+        case 'alt':
+            {
+                // Convert JSON format to runtime format
+                const altValue = jsonToStringOrRegex(descriptor.value);
+                const isRegex = altValue instanceof RegExp;
+                const altOptions = isRegex
+                    ? {}
+                    : { exact: descriptor.exact ?? false };
+                baseLocator = page.getByAltText(altValue, altOptions);
+            }
+            break;
+        case 'title':
+            {
+                // Convert JSON format to runtime format
+                const titleValue = jsonToStringOrRegex(descriptor.value);
+                const isRegex = titleValue instanceof RegExp;
+                const titleOptions = isRegex
+                    ? {}
+                    : { exact: descriptor.exact ?? false };
+                baseLocator = page.getByTitle(titleValue, titleOptions);
+            }
+            break;
+        case 'text':
+            {
+                // Convert JSON format to runtime format
+                const textValue = jsonToStringOrRegex(descriptor.value);
+                const isRegex = textValue instanceof RegExp;
+                const textOptions = isRegex
+                    ? {}
+                    : { exact: descriptor.exact ?? false };
+                baseLocator = page.getByText(textValue, 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, depth + 1);
+    }
+    return baseLocator;
+}
+/**
+ * Get the mimic ID from a locator
+ *
+ * Retrieves the data-mimic-id attribute value from the element
+ * that the locator points to. This ID is assigned by the markers system.
+ *
+ * @param locator - Playwright Locator to get the mimic ID from
+ * @returns Promise resolving to the mimic ID number, or null if not found
+ */
+export async function getMimicIdFromLocator(locator) {
+    try {
+        // Evaluate directly on the locator to get the mimic ID attribute
+        const mimicId = await locator.evaluate((el) => {
+            const idAttr = el.getAttribute('data-mimic-id');
+            return idAttr ? Number(idAttr) : null;
+        });
+        return mimicId;
+    }
+    catch (error) {
+        // If element not found or error occurs, return null
+        return null;
+    }
+}
+/**
+ * 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 target element
+ * using the markers system (mimic ID).
+ *
+ * The function saves the nested Locator type returned by getFromSelector,
+ * which can be used for further operations on the matched element.
+ *
+ * @param page - Playwright Page object
+ * @param descriptor - SelectorDescriptor to verify
+ * @param targetMimicId - Optional mimic ID to verify the match is correct
+ * @param timeout - Optional timeout in milliseconds for locator operations (default: 30000 = 30 seconds)
+ * @returns Promise resolving to an object with:
+ *   - unique: true if selector is unique (and matches target if provided)
+ *   - locator: The Locator returned by getFromSelector (nested type preserved)
+ */
+export async function verifySelectorUniqueness(page, descriptor, targetMimicId, timeout) {
+    // Default to 30 seconds for selector operations
+    const operationTimeout = timeout ?? 30000;
+    try {
+        // Get the locator from the selector descriptor (preserves nested type)
+        const locator = getFromSelector(page, descriptor);
+        // count() doesn't support timeout, but it's typically fast
+        // The main timeout-sensitive operations are elementHandle() calls below
+        const count = await locator.count();
+        // Must match exactly one element
+        if (count !== 1) {
+            // If multiple matches and we have a target mimic ID, find the index
+            let index;
+            if (count > 1 && targetMimicId !== null && targetMimicId !== undefined) {
+                // Find which index matches the target element
+                for (let i = 0; i < count; i++) {
+                    const nthLocator = locator.nth(i);
+                    const mimicId = await getMimicIdFromLocator(nthLocator);
+                    if (mimicId === targetMimicId) {
+                        index = i;
+                        break;
+                    }
+                }
+            }
+            // Only include index if it's defined
+            const result = {
+                unique: false,
+                locator,
+                count,
+            };
+            if (index !== undefined) {
+                result.index = index;
+            }
+            return result;
+        }
+        // If target mimic ID provided, verify it's the same element
+        if (targetMimicId !== null && targetMimicId !== undefined) {
+            // Get the mimic ID from the matched locator
+            const matchedMimicId = await getMimicIdFromLocator(locator);
+            // If no mimic ID found on matched element, verification fails
+            if (matchedMimicId === null) {
+                return { unique: false, locator };
+            }
+            // Verify the mimic IDs match
+            if (matchedMimicId !== targetMimicId) {
+                return { unique: false, locator };
+            }
+            // Additional verification: ensure the locator from getMimic matches
+            // This double-checks that the selector correctly identifies the element
+            const markerLocator = getMimic(page, targetMimicId);
+            // count() doesn't support timeout, but it's typically fast
+            const markerCount = await markerLocator.count();
+            if (markerCount !== 1) {
+                return { unique: false, locator };
+            }
+            // Verify both locators point to the same element by comparing their positions
+            const locatorElement = await locator.elementHandle({ timeout: operationTimeout });
+            const markerElement = await markerLocator.elementHandle({ timeout: operationTimeout });
+            if (!locatorElement || !markerElement) {
+                return { unique: false, locator };
+            }
+            // Compare elements by their mimic IDs (most reliable)
+            const locatorMimicId = await page.evaluate((el) => {
+                return el.getAttribute('data-mimic-id');
+            }, locatorElement);
+            const markerMimicId = await page.evaluate((el) => {
+                return el.getAttribute('data-mimic-id');
+            }, markerElement);
+            if (locatorMimicId !== markerMimicId || locatorMimicId !== String(targetMimicId)) {
+                return { unique: false, locator };
+            }
+        }
+        return { unique: true, locator, count: 1 };
+    }
+    catch (error) {
+        // If selector is invalid or throws, it's not unique
+        // Still return the locator for potential use
+        try {
+            const locator = getFromSelector(page, descriptor);
+            return { unique: false, locator, count: 0 };
+        }
+        catch {
+            // If we can't even create the locator, return a dummy one
+            // This shouldn't happen in practice, but TypeScript requires a return
+            return { unique: false, locator: page.locator('body'), count: 0 };
+        }
+    }
+}
+//# 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":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAExC;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAoB,EACpB,UAA8B,EAC9B,QAAgB,CAAC;IAEjB,4DAA4D;IAC5D,MAAM,SAAS,GAAG,EAAE,CAAC;IACrB,IAAI,KAAK,IAAI,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,mCAAmC,SAAS,gFAAgF,CAAC,CAAC;IAChJ,CAAC;IACD,IAAI,WAAoB,CAAC;IAEzB,4CAA4C;IAC5C,oFAAoF;IACpF,QAAQ,UAAU,CAAC,IAAI,EAAE,CAAC;QACxB,KAAK,QAAQ;YACX,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;YACjD,MAAM;QAER,KAAK,MAAM;YACT,IAAI,UAAU,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBAClC,2DAA2D;gBAC3D,MAAM,SAAS,GAAG,mBAAmB,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;gBACvD,MAAM,OAAO,GAAG,SAAS,YAAY,MAAM,CAAC;gBAC5C,MAAM,WAAW,GAAG,OAAO;oBACzB,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE;oBACrB,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,IAAI,KAAK,EAAE,CAAC;gBAE1D,WAAW,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YAC7D,CAAC;iBAAM,CAAC;gBACN,WAAW,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;YAChD,CAAC;YACD,qEAAqE;YACrE,IAAI,UAAU,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;gBACjC,WAAW,GAAG,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;YAChD,CAAC;YACD,MAAM;QAER,KAAK,OAAO;YACV,CAAC;gBACC,wCAAwC;gBACxC,MAAM,UAAU,GAAG,mBAAmB,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;gBACzD,MAAM,OAAO,GAAG,UAAU,YAAY,MAAM,CAAC;gBAC7C,MAAM,YAAY,GAAG,OAAO;oBAC1B,CAAC,CAAC,EAAE;oBACJ,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,IAAI,KAAK,EAAE,CAAC;gBAEzC,WAAW,GAAG,IAAI,CAAC,UAAU,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;gBACxD,2BAA2B;gBAC3B,IAAI,UAAU,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;oBACjC,WAAW,GAAG,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;gBAChD,CAAC;YACH,CAAC;YACD,MAAM;QAER,KAAK,aAAa;YAChB,CAAC;gBACC,wCAAwC;gBACxC,MAAM,gBAAgB,GAAG,mBAAmB,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;gBAC/D,MAAM,OAAO,GAAG,gBAAgB,YAAY,MAAM,CAAC;gBACnD,MAAM,kBAAkB,GAAG,OAAO;oBAChC,CAAC,CAAC,EAAE;oBACJ,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,IAAI,KAAK,EAAE,CAAC;gBAEzC,WAAW,GAAG,IAAI,CAAC,gBAAgB,CAAC,gBAAgB,EAAE,kBAAkB,CAAC,CAAC;YAC5E,CAAC;YACD,MAAM;QAER,KAAK,KAAK;YACR,CAAC;gBACC,wCAAwC;gBACxC,MAAM,QAAQ,GAAG,mBAAmB,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;gBACvD,MAAM,OAAO,GAAG,QAAQ,YAAY,MAAM,CAAC;gBAC3C,MAAM,UAAU,GAAG,OAAO;oBACxB,CAAC,CAAC,EAAE;oBACJ,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,IAAI,KAAK,EAAE,CAAC;gBAEzC,WAAW,GAAG,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;YACxD,CAAC;YACD,MAAM;QAER,KAAK,OAAO;YACV,CAAC;gBACC,wCAAwC;gBACxC,MAAM,UAAU,GAAG,mBAAmB,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;gBACzD,MAAM,OAAO,GAAG,UAAU,YAAY,MAAM,CAAC;gBAC7C,MAAM,YAAY,GAAG,OAAO;oBAC1B,CAAC,CAAC,EAAE;oBACJ,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,IAAI,KAAK,EAAE,CAAC;gBAEzC,WAAW,GAAG,IAAI,CAAC,UAAU,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;YAC1D,CAAC;YACD,MAAM;QAER,KAAK,MAAM;YACT,CAAC;gBACC,wCAAwC;gBACxC,MAAM,SAAS,GAAG,mBAAmB,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;gBACxD,MAAM,OAAO,GAAG,SAAS,YAAY,MAAM,CAAC;gBAC5C,MAAM,WAAW,GAAG,OAAO;oBACzB,CAAC,CAAC,EAAE;oBACJ,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,IAAI,KAAK,EAAE,CAAC;gBAEzC,WAAW,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;YACvD,CAAC;YACD,MAAM;QAER,KAAK,KAAK;YACR,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;YAChD,MAAM;QAER;YACE,wEAAwE;YACxE,MAAM,WAAW,GAAU,UAAU,CAAC;YACtC,KAAK,WAAW,CAAC,CAAC,mCAAmC;YACrD,MAAM,IAAI,KAAK,CAAC,0BAA2B,UAAkB,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1E,CAAC;IAED,iFAAiF;IACjF,IAAI,UAAU,CAAC,KAAK,EAAE,CAAC;QACrB,OAAO,eAAe,CAAC,WAAW,EAAE,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IACnE,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,OAAgB;IAEhB,IAAI,CAAC;QACH,iEAAiE;QACjE,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,CAAC,EAAW,EAAE,EAAE;YACrD,MAAM,MAAM,GAAG,EAAE,CAAC,YAAY,CAAC,eAAe,CAAC,CAAC;YAChD,OAAO,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACxC,CAAC,CAAC,CAAC;QACH,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,oDAAoD;QACpD,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,IAAU,EACV,UAA8B,EAC9B,aAA6B,EAC7B,OAAgB;IAEhB,gDAAgD;IAChD,MAAM,gBAAgB,GAAG,OAAO,IAAI,KAAK,CAAC;IAE1C,IAAI,CAAC;QACH,uEAAuE;QACvE,MAAM,OAAO,GAAG,eAAe,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QAClD,2DAA2D;QAC3D,wEAAwE;QACxE,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;QAEpC,iCAAiC;QACjC,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;YAChB,oEAAoE;YACpE,IAAI,KAAyB,CAAC;YAC9B,IAAI,KAAK,GAAG,CAAC,IAAI,aAAa,KAAK,IAAI,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;gBACvE,8CAA8C;gBAC9C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;oBAC/B,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;oBAClC,MAAM,OAAO,GAAG,MAAM,qBAAqB,CAAC,UAAU,CAAC,CAAC;oBACxD,IAAI,OAAO,KAAK,aAAa,EAAE,CAAC;wBAC9B,KAAK,GAAG,CAAC,CAAC;wBACV,MAAM;oBACR,CAAC;gBACH,CAAC;YACH,CAAC;YACD,qCAAqC;YACrC,MAAM,MAAM,GAAyE;gBACnF,MAAM,EAAE,KAAK;gBACb,OAAO;gBACP,KAAK;aACN,CAAC;YACF,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC;YACvB,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,4DAA4D;QAC5D,IAAI,aAAa,KAAK,IAAI,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;YAC1D,4CAA4C;YAC5C,MAAM,cAAc,GAAG,MAAM,qBAAqB,CAAC,OAAO,CAAC,CAAC;YAE5D,8DAA8D;YAC9D,IAAI,cAAc,KAAK,IAAI,EAAE,CAAC;gBAC5B,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;YACpC,CAAC;YAED,6BAA6B;YAC7B,IAAI,cAAc,KAAK,aAAa,EAAE,CAAC;gBACrC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;YACpC,CAAC;YAED,oEAAoE;YACpE,wEAAwE;YACxE,MAAM,aAAa,GAAG,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;YACpD,2DAA2D;YAC3D,MAAM,WAAW,GAAG,MAAM,aAAa,CAAC,KAAK,EAAE,CAAC;YAEhD,IAAI,WAAW,KAAK,CAAC,EAAE,CAAC;gBACtB,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;YACpC,CAAC;YAED,8EAA8E;YAC9E,MAAM,cAAc,GAAG,MAAM,OAAO,CAAC,aAAa,CAAC,EAAE,OAAO,EAAE,gBAAgB,EAAE,CAAC,CAAC;YAClF,MAAM,aAAa,GAAG,MAAM,aAAa,CAAC,aAAa,CAAC,EAAE,OAAO,EAAE,gBAAgB,EAAE,CAAC,CAAC;YAEvF,IAAI,CAAC,cAAc,IAAI,CAAC,aAAa,EAAE,CAAC;gBACtC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;YACpC,CAAC;YAED,sDAAsD;YACtD,MAAM,cAAc,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAW,EAAE,EAAE;gBACzD,OAAO,EAAE,CAAC,YAAY,CAAC,eAAe,CAAC,CAAC;YAC1C,CAAC,EAAE,cAAc,CAAC,CAAC;YAEnB,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAW,EAAE,EAAE;gBACxD,OAAO,EAAE,CAAC,YAAY,CAAC,eAAe,CAAC,CAAC;YAC1C,CAAC,EAAE,aAAa,CAAC,CAAC;YAElB,IAAI,cAAc,KAAK,aAAa,IAAI,cAAc,KAAK,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;gBACjF,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;YACpC,CAAC;QACH,CAAC;QAED,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAC7C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,oDAAoD;QACpD,6CAA6C;QAC7C,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,eAAe,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;YAClD,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;QAC9C,CAAC;QAAC,MAAM,CAAC;YACP,0DAA0D;YAC1D,sEAAsE;YACtE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;QACpE,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/mimic/storage.d.ts

@@ -0,0 +1,110 @@
+/**
+ * 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;
+/**
+ * Generate a hash from step text to create a unique identifier
+ *
+ * @param stepText - The step text (Gherkin step)
+ * @returns SHA-256 hash of the step text (first 16 characters for readability)
+ */
+export declare function hashStepText(stepText: string): string;
+/**
+ * Extract test file name from full file path
+ *
+ * @param testFilePath - Full path to the test file
+ * @returns Test file name without extension (e.g., "buttons-variety" from "buttons-variety.spec.ts")
+ */
+export declare function getTestFileName(testFilePath: string): string;
+/**
+ * Get the mimic directory path for a test file
+ *
+ * @param testFilePath - Full path to the test file
+ * @returns Path to the __mimic__ directory
+ */
+export declare function getMimicDir(testFilePath: string): string;
+/**
+ * Get the mimic file path for a test file
+ *
+ * @param testFilePath - Full path to the test file
+ * @returns Full path to the mimic JSON file (e.g., "__mimic__/agentic.mimic.json")
+ */
+export declare function getMimicFilePath(testFilePath: string): string;
+/**
+ * Get the snapshot directory path for a test file (legacy support)
+ *
+ * @param testFilePath - Directory path of the test file
+ * @returns Path to the .mimic-snapshots directory
+ * @deprecated Use getMimicDir instead
+ */
+export declare function getSnapshotDir(testFilePath: string): string;
+/**
+ * Get the snapshot file path for a specific test (legacy support)
+ *
+ * @param testFilePath - Directory path of the test file
+ * @param testHash - Hash identifier for the test
+ * @returns Full path to the snapshot JSON file
+ * @deprecated Use getMimicFilePath instead
+ */
+export declare function getSnapshotPath(testFilePath: string, testHash: string): string;
+/**
+ * Read a snapshot from disk
+ *
+ * @param testFilePath - Full path to 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
+ *
+ * Saves all tests from a test file into a single JSON file in __mimic__ directory.
+ * Updates existing test entry if testHash already exists, otherwise adds new test.
+ *
+ * @param testFilePath - Full path to 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 and flags if the snapshot exists.
+ *
+ * @param testFilePath - Full path to 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)
+ * - Flags don't indicate it should be skipped
+ *
+ * Note: Even in troubleshoot mode, we use snapshots if they've passed.
+ * Regeneration will happen only if replay fails.
+ *
+ * @param testFilePath - Full path to the test file
+ * @param testHash - Hash identifier for the test
+ * @param troubleshootMode - Whether troubleshoot mode is enabled (unused, kept for compatibility)
+ * @param expectedStepCount - Expected number of steps (optional)
+ * @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,EAAgB,MAAM,YAAY,CAAC;AAEzD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIrD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIrD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAK5D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAGxD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAI7D;AA2BD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAG9E;AAGD;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAwB1B;AA6BD;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAChC,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,IAAI,CAAC,CA8Gf;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,CA4Df;AAED;;;;;;;;;;;;;;;;GAgBG;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,CA0DlB"}