playwright-mimic 0.1.1 → 0.1.2

package/dist/mimic/selector.js

@@ -1,4 +1,4 @@
-import { verifySelectorUniqueness } from './selectorDescriptor.js';
+import { verifySelectorUniqueness, getMimicIdFromLocator } from './selectorUtils.js';
 ;
 /**
  * Capture target elements from the page
@@ -196,12 +196,20 @@ export async function captureTargets(page, options = {}) {
         }
         /**
          * Get all data-* attributes
+         *
+         * @param element - Element to extract data attributes from
+         * @returns Record of camelCase data attribute keys to their values
          */
         function getDataset(element) {
             const dataset = {};
             for (const attr of element.attributes) {
                 if (attr.name.startsWith('data-')) {
-                    const key = attr.name.replace(/^data-/, '').replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+                    // Convert data-test-id to testId (camelCase)
+                    // Note: No type annotations in arrow function to avoid serialization issues in page.evaluate
+                    // @param {string} _match - Full match string (unused, but required by replace callback)
+                    // @param {string} letter - Captured letter group to uppercase
+                    // @ts-expect-error - Type annotations removed to prevent serialization issues in browser context
+                    const key = attr.name.replace(/^data-/, '').replace(/-([a-z])/g, (_match, letter) => letter.toUpperCase());
                     dataset[key] = attr.value;
                 }
             }
@@ -468,7 +476,12 @@ async function scoreElementMatch(elementIndex, locator, target) {
         const dataset = {};
         for (const attr of el.attributes) {
             if (attr.name.startsWith('data-')) {
-                const key = attr.name.replace(/^data-/, '').replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+                // Convert data-test-id to testId (camelCase)
+                // Note: No type annotations in arrow function to avoid serialization issues in locator.evaluate
+                // @param {string} _match - Full match string (unused, but required by replace callback)
+                // @param {string} letter - Captured letter group to uppercase
+                // @ts-expect-error - Type annotations removed to prevent serialization issues in browser context
+                const key = attr.name.replace(/^data-/, '').replace(/-([a-z])/g, (_match, letter) => letter.toUpperCase());
                 dataset[key] = attr.value;
             }
         }
@@ -707,132 +720,466 @@ export async function buildSelectorForTarget(page, target) {
  * 8. CSS fallback (ID, name, tag + nth-of-type)
  *
  * @param locator - Playwright Locator pointing to the target element
+ * @param options - Optional configuration
+ * @param options.timeout - Timeout in milliseconds for element operations (default: 30000 = 30 seconds)
  * @returns Promise resolving to SelectorDescriptor that uniquely identifies the element
  */
-export async function generateBestSelectorForElement(locator) {
+export async function generateBestSelectorForElement(locator, options) {
     const page = locator.page();
-    const targetElementHandle = await locator.elementHandle();
+    // Default to 30 seconds (30000ms) for selector generation
+    // This provides reasonable timeout while avoiding excessive waits
+    const timeout = options?.timeout ?? 30000;
+    // Check if page is closed before attempting any operations
+    if (page.isClosed()) {
+        throw new Error('Cannot generate selector: page, context or browser has been closed. This may happen if a previous action closed the page unexpectedly.');
+    }
+    // Check if locator matches any elements before attempting to get element handle
+    // This provides faster failure when element doesn't exist (avoids waiting for evaluate timeouts)
+    let count;
+    try {
+        count = await locator.count();
+    }
+    catch (error) {
+        // If page closed, throw a more descriptive error
+        if (page.isClosed() || (error?.message && error.message.includes('closed'))) {
+            throw new Error('Cannot get element count: page, context or browser has been closed. This may happen if a previous action closed the page unexpectedly.');
+        }
+        throw error;
+    }
+    if (count === 0) {
+        throw new Error('Cannot generate selector: element not found. The locator does not match any elements on the page.');
+    }
+    // Get mimic ID from the locator using the markers system
+    // This replaces the old targetElementHandle approach for verification
+    // Only call this after we've verified the element exists (count > 0)
+    const targetMimicId = await getMimicIdFromLocator(locator);
+    // If no mimic ID found, we can't verify uniqueness with markers
+    // This could happen if markers haven't been installed yet
+    // We'll still try to generate a selector, but verification will be less strict
+    // Get element handle from locator for page.evaluate() calls
+    // We still need this for browser context evaluation
+    let targetElementHandle;
+    try {
+        targetElementHandle = await locator.elementHandle({ timeout });
+    }
+    catch (error) {
+        // Check if page closed during element handle retrieval
+        if (page.isClosed() || (error?.message && error.message.includes('closed'))) {
+            throw new Error('Cannot get element handle: page, context or browser has been closed. This may happen if a previous action closed the page unexpectedly.');
+        }
+        throw error;
+    }
     if (!targetElementHandle) {
         throw new Error('Cannot get element handle from locator');
     }
+    // Double-check page is still open before evaluate
+    if (page.isClosed()) {
+        throw new Error('Page closed before evaluation: page, context or browser has been closed. This may happen if a previous action closed the page unexpectedly.');
+    }
     // Get element information in browser context
-    const elementInfo = await page.evaluate((element) => {
-        // @ts-ignore - window is available in browser context
-        const win = window;
-        // @ts-ignore - document is available in browser context
-        const doc = document;
-        /**
-         * Get visible text content
-         */
-        function getVisibleText(el) {
-            const style = win.getComputedStyle(el);
-            if (style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0') {
-                return '';
+    let elementInfo;
+    try {
+        elementInfo = await page.evaluate((element) => {
+            // @ts-ignore - window is available in browser context
+            const win = window;
+            // @ts-ignore - document is available in browser context
+            const doc = document;
+            // Inline all logic to avoid nested functions that get transformed by toolchain
+            // Get visible text - inline logic
+            const style = win.getComputedStyle(element);
+            const isVisible = style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0';
+            const text = isVisible ? (element.textContent || '').trim().replace(/\s+/g, ' ') : '';
+            // Get label - inline logic
+            let label = null;
+            const ariaLabelAttr = element.getAttribute('aria-label');
+            if (ariaLabelAttr) {
+                label = ariaLabelAttr.trim();
             }
-            return (el.textContent || '').trim().replace(/\s+/g, ' ');
-        }
-        /**
-         * Get label text via various methods
-         */
-        function getLabel(el) {
-            const ariaLabel = el.getAttribute('aria-label');
-            if (ariaLabel)
-                return ariaLabel.trim();
-            const labelledBy = el.getAttribute('aria-labelledby');
-            if (labelledBy) {
-                const labelEl = doc.getElementById(labelledBy);
-                if (labelEl)
-                    return (labelEl.textContent || '').trim();
+            else {
+                const labelledBy = element.getAttribute('aria-labelledby');
+                if (labelledBy) {
+                    const labelEl = doc.getElementById(labelledBy);
+                    if (labelEl)
+                        label = (labelEl.textContent || '').trim();
+                }
+                if (!label && element.id) {
+                    const labelFor = doc.querySelector('label[for="' + element.id + '"]');
+                    if (labelFor)
+                        label = (labelFor.textContent || '').trim();
+                }
+                if (!label) {
+                    const parentLabel = element.closest('label');
+                    if (parentLabel)
+                        label = (parentLabel.textContent || '').trim();
+                }
             }
-            if (el.id) {
-                const label = doc.querySelector(`label[for="${el.id}"]`);
-                if (label)
-                    return (label.textContent || '').trim();
+            // Infer role - inline logic
+            let role = element.getAttribute('role');
+            if (!role) {
+                const tag = element.tagName.toLowerCase();
+                if (tag === 'button') {
+                    role = 'button';
+                }
+                else if (tag === 'a') {
+                    role = 'link';
+                }
+                else if (tag === 'input') {
+                    const inputType = element.type;
+                    if (inputType === 'button' || inputType === 'submit' || inputType === 'reset') {
+                        role = 'button';
+                    }
+                    else if (inputType === 'checkbox') {
+                        role = 'checkbox';
+                    }
+                    else if (inputType === 'radio') {
+                        role = 'radio';
+                    }
+                    else {
+                        role = 'textbox';
+                    }
+                }
+                else if (tag === 'select') {
+                    role = 'combobox';
+                }
+                else if (tag === 'textarea') {
+                    role = 'textbox';
+                }
+                else if (tag === 'img') {
+                    role = 'img';
+                }
             }
-            const parentLabel = el.closest('label');
-            if (parentLabel)
-                return (parentLabel.textContent || '').trim();
-            return null;
-        }
-        /**
-         * Infer ARIA role from element
-         */
-        function inferRole(el) {
-            const explicitRole = el.getAttribute('role');
-            if (explicitRole)
-                return explicitRole;
-            const tag = el.tagName.toLowerCase();
-            const roleMap = {
-                'button': 'button',
-                'a': 'link',
-                'input': el.type === 'button' || el.type === 'submit' || el.type === 'reset' ? 'button' :
-                    el.type === 'checkbox' ? 'checkbox' :
-                        el.type === 'radio' ? 'radio' : 'textbox',
-                'select': 'combobox',
-                'textarea': 'textbox',
-                'img': 'img',
-            };
-            return roleMap[tag] || null;
-        }
-        /**
-         * Get dataset (data-* attributes)
-         */
-        function getDataset(el) {
+            // Get dataset - inline logic with simple replace (no arrow function)
             const dataset = {};
-            for (const attr of el.attributes) {
-                if (attr.name.startsWith('data-')) {
-                    const key = attr.name.replace(/^data-/, '').replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
-                    dataset[key] = attr.value;
+            for (let i = 0; i < element.attributes.length; i++) {
+                const attr = element.attributes[i];
+                if (attr && attr.name && attr.name.startsWith('data-')) {
+                    // Convert data-test-id to testId (camelCase) - using simple string manipulation
+                    let key = attr.name.replace(/^data-/, '');
+                    // Replace -x with X (camelCase conversion)
+                    let result = '';
+                    let capitalizeNext = false;
+                    for (let j = 0; j < key.length; j++) {
+                        const char = key[j];
+                        if (char) {
+                            if (char === '-') {
+                                capitalizeNext = true;
+                            }
+                            else {
+                                result += capitalizeNext ? char.toUpperCase() : char;
+                                capitalizeNext = false;
+                            }
+                        }
+                    }
+                    dataset[result] = attr.value;
                 }
             }
-            return dataset;
-        }
-        /**
-         * Get nth-of-type index
-         */
-        function getNthOfType(el) {
-            const tag = el.tagName;
-            let index = 1;
-            let sibling = el.previousElementSibling;
+            // Get nth-of-type - inline logic
+            const tagName = element.tagName;
+            let nthOfType = 1;
+            let sibling = element.previousElementSibling;
             while (sibling) {
-                if (sibling.tagName === tag) {
-                    index++;
+                if (sibling.tagName === tagName) {
+                    nthOfType++;
                 }
                 sibling = sibling.previousElementSibling;
             }
-            return index;
+            return {
+                tag: element.tagName.toLowerCase(),
+                text: text,
+                id: element.id || null,
+                role: role,
+                label: label,
+                ariaLabel: element.getAttribute('aria-label') || null,
+                placeholder: element.getAttribute('placeholder') || null,
+                alt: element.getAttribute('alt') || null,
+                title: element.getAttribute('title') || null,
+                typeAttr: element.type || null,
+                nameAttr: element.getAttribute('name') || null,
+                dataset: dataset,
+                nthOfType: nthOfType,
+            };
+        }, targetElementHandle);
+    }
+    catch (error) {
+        // Enhanced error reporting to help identify the exact location of the issue
+        const errorMessage = error?.message || String(error);
+        const errorStack = error?.stack || '';
+        // Check if page is closed - this is a common issue
+        if (page.isClosed() || errorMessage.includes('closed') || errorMessage.includes('Target page')) {
+            throw new Error(`Cannot generate selector: page, context or browser has been closed. ` +
+                `This may happen if a previous action (like form submission or navigation) closed the page unexpectedly. ` +
+                `Original error: ${errorMessage}`);
         }
-        return {
-            tag: element.tagName.toLowerCase(),
-            text: getVisibleText(element),
-            id: element.id || null,
-            role: inferRole(element),
-            label: getLabel(element),
-            ariaLabel: element.getAttribute('aria-label') || null,
-            placeholder: element.getAttribute('placeholder') || null,
-            alt: element.getAttribute('alt') || null,
-            title: element.getAttribute('title') || null,
-            typeAttr: element.type || null,
-            nameAttr: element.getAttribute('name') || null,
-            dataset: getDataset(element),
-            nthOfType: getNthOfType(element),
-        };
-    }, targetElementHandle);
+        // Check if this is the __name error
+        if (errorMessage.includes('__name') || errorStack.includes('__name')) {
+            console.error('Error in generateBestSelectorForElement - page.evaluate failed');
+            console.error('Error message:', errorMessage);
+            console.error('Error stack:', errorStack);
+            console.error('This error typically occurs when TypeScript type annotations are used in arrow functions within page.evaluate');
+            console.error('Please check for any remaining type annotations in the evaluate function');
+        }
+        throw new Error(`Failed to evaluate element in browser context: ${errorMessage}. ` +
+            `This may be caused by TypeScript type annotations in the evaluate function. ` +
+            `Original error: ${errorStack}`);
+    }
+    // Find the best parent/ancestor selector by checking multiple levels and selector types
+    // This handles cases where the locator was created from a parent chain
+    // Returns the best parent selector found, or null if none found
+    const findBestParentSelector = async () => {
+        // Check if page is still open before parent evaluation
+        if (page.isClosed()) {
+            throw new Error('Page closed during parent selector search: page, context or browser has been closed.');
+        }
+        let parentCandidates;
+        try {
+            parentCandidates = await page.evaluate((element) => {
+                const candidates = [];
+                let current = element.parentElement;
+                let depth = 0;
+                const maxDepth = 10; // Limit depth to avoid going too far up
+                while (current && current.tagName !== 'BODY' && current.tagName !== 'HTML' && depth < maxDepth) {
+                    // Get all relevant information about this ancestor
+                    const testId = current.getAttribute('data-testid');
+                    const role = current.getAttribute('role');
+                    const id = current.id;
+                    const ariaLabel = current.getAttribute('aria-label');
+                    const label = current.getAttribute('aria-labelledby');
+                    // Get visible text for role/text matching
+                    const style = window.getComputedStyle(current);
+                    const isVisible = style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0';
+                    const text = isVisible ? (current.textContent || '').trim().replace(/\s+/g, ' ').substring(0, 100) : '';
+                    // Infer role if not explicitly set
+                    let inferredRole = role;
+                    if (!inferredRole) {
+                        const tag = current.tagName.toLowerCase();
+                        if (tag === 'section' || tag === 'article' || tag === 'aside' || tag === 'nav' || tag === 'main' || tag === 'header' || tag === 'footer') {
+                            inferredRole = tag;
+                        }
+                        else if (tag === 'form') {
+                            inferredRole = 'form';
+                        }
+                    }
+                    // Get dataset
+                    const dataset = {};
+                    for (let i = 0; i < current.attributes.length; i++) {
+                        const attr = current.attributes[i];
+                        if (attr && attr.name && attr.name.startsWith('data-')) {
+                            let key = attr.name.replace(/^data-/, '');
+                            let result = '';
+                            let capitalizeNext = false;
+                            for (let j = 0; j < key.length; j++) {
+                                const char = key[j];
+                                if (char) {
+                                    if (char === '-') {
+                                        capitalizeNext = true;
+                                    }
+                                    else {
+                                        result += capitalizeNext ? char.toUpperCase() : char;
+                                        capitalizeNext = false;
+                                    }
+                                }
+                            }
+                            dataset[result] = attr.value;
+                        }
+                    }
+                    candidates.push({
+                        depth,
+                        testId,
+                        role: inferredRole,
+                        id,
+                        ariaLabel,
+                        label,
+                        text,
+                        dataset,
+                        tag: current.tagName.toLowerCase(),
+                    });
+                    current = current.parentElement;
+                    depth++;
+                }
+                return candidates;
+            }, targetElementHandle);
+        }
+        catch (error) {
+            // If page closed during parent evaluation, just return null (parent selector is optional)
+            const errorMessage = error?.message || String(error);
+            if (page.isClosed() || errorMessage.includes('closed') || errorMessage.includes('Target page')) {
+                console.warn('Page closed during parent selector evaluation, skipping parent selector');
+                return null;
+            }
+            // For other errors, log but don't fail - parent selector is optional
+            console.warn('Error evaluating parent candidates:', errorMessage);
+            return null;
+        }
+        // Safety check: ensure parentCandidates is valid
+        if (!parentCandidates || !Array.isArray(parentCandidates)) {
+            return null;
+        }
+        // Try to find the best parent selector, prioritizing:
+        // 1. testid (unique)
+        // 2. role with name/text (unique)
+        // 3. role alone (unique)
+        // 4. label (unique)
+        // 5. id (CSS fallback - only if no unique selector found after searching all candidates)
+        // Continue searching through all candidates to find the best unique selector
+        // Track the best non-unique non-CSS selector as fallback (only if no unique selector found)
+        let bestFallbackSelector = null;
+        // Track CSS selectors separately - only use as last resort after exhausting all candidates
+        let bestCssFallbackSelector = null;
+        for (const candidate of parentCandidates) {
+            // Priority 1: testid
+            const dataset = candidate.dataset;
+            if (dataset && dataset.testid) {
+                const parentDescriptor = {
+                    type: 'testid',
+                    value: dataset.testid,
+                };
+                // Check if this parent selector is unique
+                const parentLocator = page.getByTestId(dataset.testid);
+                const count = await parentLocator.count();
+                if (count === 1) {
+                    return parentDescriptor;
+                }
+                // Store as fallback if we don't have one yet
+                if (!bestFallbackSelector) {
+                    bestFallbackSelector = parentDescriptor;
+                }
+                // Continue searching for a unique selector
+                continue;
+            }
+            // Priority 2: role with name/text
+            if (candidate.role) {
+                const name = candidate.ariaLabel || candidate.text;
+                if (name && name.trim() && name.length < 100) {
+                    const parentDescriptor = {
+                        type: 'role',
+                        role: candidate.role,
+                        name: name.trim(),
+                        exact: false,
+                    };
+                    const parentLocator = page.getByRole(candidate.role, { name: name.trim() });
+                    const count = await parentLocator.count();
+                    if (count === 1) {
+                        return parentDescriptor;
+                    }
+                    // Try with exact match
+                    const parentDescriptorExact = {
+                        type: 'role',
+                        role: candidate.role,
+                        name: name.trim(),
+                        exact: true,
+                    };
+                    const parentLocatorExact = page.getByRole(candidate.role, { name: name.trim(), exact: true });
+                    const countExact = await parentLocatorExact.count();
+                    if (countExact === 1) {
+                        return parentDescriptorExact;
+                    }
+                    // Store as fallback if we don't have one yet
+                    if (!bestFallbackSelector) {
+                        bestFallbackSelector = parentDescriptor;
+                    }
+                    // Continue searching for a unique selector
+                    continue;
+                }
+                // Role without name - check if unique
+                const parentDescriptor = {
+                    type: 'role',
+                    role: candidate.role,
+                };
+                const parentLocator = page.getByRole(candidate.role);
+                const count = await parentLocator.count();
+                // If unique, return it
+                if (count === 1) {
+                    return parentDescriptor;
+                }
+                // Store as fallback if we don't have one yet
+                if (!bestFallbackSelector) {
+                    bestFallbackSelector = parentDescriptor;
+                }
+                // Continue searching for a unique selector
+                continue;
+            }
+            // Priority 3: label (for form elements)
+            if (candidate.label) {
+                const parentDescriptor = {
+                    type: 'label',
+                    value: candidate.label,
+                    exact: false,
+                };
+                const parentLocator = page.getByLabel(candidate.label);
+                const count = await parentLocator.count();
+                if (count === 1) {
+                    return parentDescriptor;
+                }
+                // Store as fallback if we don't have one yet
+                if (!bestFallbackSelector) {
+                    bestFallbackSelector = parentDescriptor;
+                }
+                // Continue searching for a unique selector
+                continue;
+            }
+            // Priority 4: id (CSS - only store as fallback, don't return until we've checked all candidates)
+            if (candidate.id) {
+                const parentDescriptor = {
+                    type: 'css',
+                    selector: `#${candidate.id}`,
+                };
+                const parentLocator = page.locator(`#${candidate.id}`);
+                const count = await parentLocator.count();
+                if (count === 1) {
+                    return parentDescriptor;
+                }
+                // Store CSS selector as fallback only if we don't have one yet
+                // CSS selectors are only used if we've exhausted all candidates
+                if (!bestCssFallbackSelector) {
+                    bestCssFallbackSelector = parentDescriptor;
+                }
+                // Continue searching for a unique selector
+                continue;
+            }
+        }
+        // If we found a unique selector, it would have been returned above
+        // First try non-CSS fallback (preferred over CSS)
+        if (bestFallbackSelector) {
+            return bestFallbackSelector;
+        }
+        // Only use CSS selector as last resort if we've exhausted all candidates and found no unique selector
+        if (bestCssFallbackSelector) {
+            return bestCssFallbackSelector;
+        }
+        // No suitable parent selector found
+        return null;
+    };
+    const bestParentSelector = await findBestParentSelector();
     // Try to find selector on element itself first
     const tryElementSelector = async () => {
         // Priority 1: data-testid
-        if (elementInfo.dataset.testid) {
+        const dataset = elementInfo.dataset;
+        if (dataset && dataset.testid) {
             const descriptor = {
                 type: 'testid',
-                value: elementInfo.dataset.testid,
+                value: dataset.testid,
             };
-            if (await verifySelectorUniqueness(page, descriptor, targetElementHandle)) {
+            const verification = await verifySelectorUniqueness(page, descriptor, targetMimicId ?? null, timeout);
+            if (verification.unique) {
                 return descriptor;
             }
         }
-        // Priority 2: role + name
-        if (elementInfo.role) {
-            const name = elementInfo.ariaLabel || elementInfo.label || elementInfo.text;
+        // Priority 2: role + name (when we have label/ariaLabel - prefer role+label over placeholder)
+        // Check role first when we have a label, as role+label is preferred over placeholder
+        if (elementInfo.role && (elementInfo.label || elementInfo.ariaLabel)) {
+            // Prioritize label for form elements (textbox, combobox, checkbox, radio)
+            // Label text is more reliable than aria-label or text content for form inputs
+            const isFormElement = ['textbox', 'combobox', 'checkbox', 'radio'].includes(elementInfo.role);
+            // For form elements, prefer label > ariaLabel > text (don't use placeholder here)
+            // For other elements, prefer ariaLabel > label > text
+            let name = null;
+            if (isFormElement) {
+                name = elementInfo.label?.trim() || elementInfo.ariaLabel?.trim() || elementInfo.text?.trim() || null;
+            }
+            else {
+                // For images and other elements, use ariaLabel, label, or text
+                name = elementInfo.ariaLabel?.trim() || elementInfo.label?.trim() || elementInfo.text?.trim() || null;
+            }
             if (name && name.trim()) {
                 // Try exact match first
                 const descriptorExact = {
@@ -841,9 +1188,14 @@ export async function generateBestSelectorForElement(locator) {
                     name: name.trim(),
                     exact: true,
                 };
-                if (await verifySelectorUniqueness(page, descriptorExact, targetElementHandle)) {
+                const verificationExact = await verifySelectorUniqueness(page, descriptorExact, targetMimicId ?? null);
+                if (verificationExact.unique) {
                     return descriptorExact;
                 }
+                // If not unique but we have an index, use nth() for focused selector
+                if (verificationExact.index !== undefined && verificationExact.count && verificationExact.count > 1) {
+                    return { ...descriptorExact, nth: verificationExact.index };
+                }
                 // Try non-exact match
                 const descriptor = {
                     type: 'role',
@@ -851,71 +1203,143 @@ export async function generateBestSelectorForElement(locator) {
                     name: name.trim(),
                     exact: false,
                 };
-                if (await verifySelectorUniqueness(page, descriptor, targetElementHandle)) {
+                const verification = await verifySelectorUniqueness(page, descriptor, targetMimicId ?? null, timeout);
+                if (verification.unique) {
                     return descriptor;
                 }
-            }
-            // Role without name
-            const descriptor = {
-                type: 'role',
-                role: elementInfo.role,
-            };
-            if (await verifySelectorUniqueness(page, descriptor, targetElementHandle)) {
-                return descriptor;
-            }
-        }
-        // Priority 3: label
-        if (elementInfo.label) {
-            const descriptorExact = {
-                type: 'label',
-                value: elementInfo.label.trim(),
-                exact: true,
-            };
-            if (await verifySelectorUniqueness(page, descriptorExact, targetElementHandle)) {
-                return descriptorExact;
-            }
-            const descriptor = {
-                type: 'label',
-                value: elementInfo.label.trim(),
-                exact: false,
-            };
-            if (await verifySelectorUniqueness(page, descriptor, targetElementHandle)) {
-                return descriptor;
+                // If not unique but we have an index, use nth() for focused selector
+                if (verification.index !== undefined && verification.count && verification.count > 1) {
+                    return { ...descriptor, nth: verification.index };
+                }
             }
         }
-        // Priority 4: placeholder
-        if (elementInfo.placeholder) {
+        // Priority 3: placeholder (only if no label/ariaLabel - prefer direct attribute selectors)
+        // Placeholder is more specific than role+name for inputs without labels
+        if (elementInfo.placeholder && !elementInfo.label && !elementInfo.ariaLabel) {
             const descriptor = {
                 type: 'placeholder',
                 value: elementInfo.placeholder.trim(),
                 exact: false,
             };
-            if (await verifySelectorUniqueness(page, descriptor, targetElementHandle)) {
+            const verification = await verifySelectorUniqueness(page, descriptor, targetMimicId ?? null, timeout);
+            if (verification.unique) {
                 return descriptor;
             }
         }
-        // Priority 5: alt
-        if (elementInfo.alt) {
+        // Priority 4: alt (only if no label/ariaLabel - prefer direct attribute selectors)
+        // Alt is more specific than role+name for images without labels
+        if (elementInfo.alt && !elementInfo.label && !elementInfo.ariaLabel) {
             const descriptor = {
                 type: 'alt',
                 value: elementInfo.alt.trim(),
                 exact: false,
             };
-            if (await verifySelectorUniqueness(page, descriptor, targetElementHandle)) {
+            const verification = await verifySelectorUniqueness(page, descriptor, targetMimicId ?? null, timeout);
+            if (verification.unique) {
                 return descriptor;
             }
         }
-        // Priority 6: title
-        if (elementInfo.title) {
+        // Priority 5: title (only if no label/ariaLabel - prefer direct attribute selectors)
+        // Title is more specific than role+name for elements with title attributes but no labels
+        if (elementInfo.title && !elementInfo.label && !elementInfo.ariaLabel) {
             const descriptor = {
                 type: 'title',
                 value: elementInfo.title.trim(),
                 exact: false,
             };
-            if (await verifySelectorUniqueness(page, descriptor, targetElementHandle)) {
+            const verification = await verifySelectorUniqueness(page, descriptor, targetMimicId ?? null, timeout);
+            if (verification.unique) {
                 return descriptor;
             }
         }
+        // Priority 6: role + name (fallback when no label but we have placeholder/alt/title)
+        // Use placeholder/alt/title as name for role selector when no label available
+        if (elementInfo.role && !elementInfo.label && !elementInfo.ariaLabel) {
+            const isFormElement = ['textbox', 'combobox', 'checkbox', 'radio'].includes(elementInfo.role);
+            // For form elements without labels, use placeholder > text
+            // For other elements without labels, use alt > title > text
+            let name = null;
+            if (isFormElement) {
+                name = elementInfo.placeholder?.trim() || elementInfo.text?.trim() || null;
+            }
+            else {
+                // For images and other elements, use alt, title, or text
+                name = elementInfo.alt?.trim() || elementInfo.title?.trim() || elementInfo.text?.trim() || null;
+            }
+            if (name && name.trim()) {
+                // Try exact match first
+                const descriptorExact = {
+                    type: 'role',
+                    role: elementInfo.role,
+                    name: name.trim(),
+                    exact: true,
+                };
+                const verificationExact = await verifySelectorUniqueness(page, descriptorExact, targetMimicId ?? null);
+                if (verificationExact.unique) {
+                    return descriptorExact;
+                }
+                // If not unique but we have an index, use nth() for focused selector
+                if (verificationExact.index !== undefined && verificationExact.count && verificationExact.count > 1) {
+                    return { ...descriptorExact, nth: verificationExact.index };
+                }
+                // Try non-exact match
+                const descriptor = {
+                    type: 'role',
+                    role: elementInfo.role,
+                    name: name.trim(),
+                    exact: false,
+                };
+                const verification = await verifySelectorUniqueness(page, descriptor, targetMimicId ?? null, timeout);
+                if (verification.unique) {
+                    return descriptor;
+                }
+                // If not unique but we have an index, use nth() for focused selector
+                if (verification.index !== undefined && verification.count && verification.count > 1) {
+                    return { ...descriptor, nth: verification.index };
+                }
+            }
+            // Role without name (only if we don't have a label for form elements)
+            if (!isFormElement) {
+                const descriptor = {
+                    type: 'role',
+                    role: elementInfo.role,
+                };
+                const verification = await verifySelectorUniqueness(page, descriptor, targetMimicId ?? null, timeout);
+                if (verification.unique) {
+                    return descriptor;
+                }
+            }
+        }
+        // Priority 7: label (getByLabel - especially good for form elements)
+        // This should be unique for form inputs with proper label associations
+        if (elementInfo.label) {
+            const descriptorExact = {
+                type: 'label',
+                value: elementInfo.label.trim(),
+                exact: true,
+            };
+            const verificationExact = await verifySelectorUniqueness(page, descriptorExact, targetMimicId ?? null);
+            if (verificationExact.unique) {
+                return descriptorExact;
+            }
+            // If not unique but we have an index, use nth() for focused selector
+            if (verificationExact.index !== undefined && verificationExact.count && verificationExact.count > 1) {
+                return { ...descriptorExact, nth: verificationExact.index };
+            }
+            const descriptor = {
+                type: 'label',
+                value: elementInfo.label.trim(),
+                exact: false,
+            };
+            const verification = await verifySelectorUniqueness(page, descriptor, targetMimicId ?? null, timeout);
+            if (verification.unique) {
+                return descriptor;
+            }
+            // If not unique but we have an index, use nth() for focused selector
+            if (verification.index !== undefined && verification.count && verification.count > 1) {
+                return { ...descriptor, nth: verification.index };
+            }
+        }
         // Priority 7: text
         if (elementInfo.text && elementInfo.text.trim()) {
             const trimmedText = elementInfo.text.trim();
@@ -926,7 +1350,8 @@ export async function generateBestSelectorForElement(locator) {
                     value: trimmedText,
                     exact: true,
                 };
-                if (await verifySelectorUniqueness(page, descriptorExact, targetElementHandle)) {
+                const verificationExact = await verifySelectorUniqueness(page, descriptorExact, targetMimicId ?? null);
+                if (verificationExact.unique) {
                     return descriptorExact;
                 }
             }
@@ -935,165 +1360,152 @@ export async function generateBestSelectorForElement(locator) {
                 value: trimmedText,
                 exact: false,
             };
-            if (await verifySelectorUniqueness(page, descriptor, targetElementHandle)) {
+            const verification = await verifySelectorUniqueness(page, descriptor, targetMimicId ?? null, timeout);
+            if (verification.unique) {
                 return descriptor;
             }
         }
-        // Priority 8: CSS fallback
-        if (elementInfo.id) {
+        // Priority 8: name attribute (for form elements - better than CSS)
+        // Name attributes are more stable than CSS nth-of-type selectors
+        if (elementInfo.nameAttr && elementInfo.nameAttr.trim()) {
+            const nameValue = elementInfo.nameAttr.trim();
+            // Try exact name match
             const descriptor = {
                 type: 'css',
-                selector: `#${elementInfo.id}`,
+                selector: `[name="${nameValue}"]`,
             };
-            if (await verifySelectorUniqueness(page, descriptor, targetElementHandle)) {
+            const verification = await verifySelectorUniqueness(page, descriptor, targetMimicId ?? null, timeout);
+            if (verification.unique) {
                 return descriptor;
             }
         }
-        if (elementInfo.nameAttr) {
+        // Priority 9: id attribute (better than nth-of-type CSS)
+        // ID selectors are more stable than nth-of-type, even though they're still CSS
+        if (elementInfo.id && elementInfo.id.trim()) {
+            const idValue = elementInfo.id.trim();
             const descriptor = {
                 type: 'css',
-                selector: `[name="${elementInfo.nameAttr}"]`,
+                selector: `#${idValue}`,
             };
-            if (await verifySelectorUniqueness(page, descriptor, targetElementHandle)) {
+            const verification = await verifySelectorUniqueness(page, descriptor, targetMimicId ?? null, timeout);
+            if (verification.unique) {
                 return descriptor;
             }
         }
-        // Last resort: tag + nth-of-type
-        const descriptor = {
-            type: 'css',
-            selector: `${elementInfo.tag}:nth-of-type(${elementInfo.nthOfType})`,
-        };
-        if (await verifySelectorUniqueness(page, descriptor, targetElementHandle)) {
-            return descriptor;
-        }
+        // Don't use nth-of-type CSS here - only as absolute last resort after trying parent selectors
+        // CSS selectors with nth-of-type are less stable and harder to maintain
         return null;
     };
-    // Try element itself first
+    // Helper function to create nested selector
+    const createNestedSelector = (parent, child) => {
+        // Clone parent and add child
+        const nested = { ...parent };
+        nested.child = child;
+        return nested;
+    };
+    // Try element itself first - always check if child selector is unique before nesting
+    // This ensures we prefer direct selectors (like testid) over nested ones when possible
     const elementSelector = await tryElementSelector();
     if (elementSelector) {
-        return elementSelector;
-    }
-    // If nothing found on element, try parent
-    const parentInfo = await page.evaluate((element) => {
-        const parent = element.parentElement;
-        if (!parent || parent.tagName === 'BODY' || parent.tagName === 'HTML') {
-            return null;
+        // Verify child selector is unique
+        const childVerification = await verifySelectorUniqueness(page, elementSelector, targetMimicId ?? null);
+        if (childVerification.unique) {
+            // Child selector is unique - use it directly (don't nest)
+            // This is more stable than nested selectors and avoids unnecessary parent dependencies
+            return elementSelector;
         }
-        // @ts-ignore - window is available in browser context
-        const win = window;
-        // @ts-ignore - document is available in browser context
-        const doc = document;
-        function getVisibleText(el) {
-            const style = win.getComputedStyle(el);
-            if (style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0') {
-                return '';
-            }
-            return (el.textContent || '').trim().replace(/\s+/g, ' ');
+    }
+    // If we found a good parent selector AND child selector isn't unique, create nested selector
+    // This handles cases where the locator was created from a parent chain like:
+    // page.getByTestId('parent').getByRole('button', { name: 'Add to Cart' })
+    // or page.getByRole('section').getByRole('button', { name: 'Add to Cart' })
+    // Only use nested when child alone isn't unique
+    if (bestParentSelector && elementSelector) {
+        // Create nested selector since child alone isn't unique
+        const nestedDescriptor = createNestedSelector(bestParentSelector, elementSelector);
+        // Verify the nested selector is unique
+        const verification = await verifySelectorUniqueness(page, nestedDescriptor, targetMimicId ?? null);
+        if (verification.unique) {
+            return nestedDescriptor;
         }
-        function getLabel(el) {
-            const ariaLabel = el.getAttribute('aria-label');
-            if (ariaLabel)
-                return ariaLabel.trim();
-            const labelledBy = el.getAttribute('aria-labelledby');
-            if (labelledBy) {
-                const labelEl = doc.getElementById(labelledBy);
-                if (labelEl)
-                    return (labelEl.textContent || '').trim();
+    }
+    // If we found a good parent selector but child selector generation failed, try with basic selectors
+    if (bestParentSelector && !elementSelector) {
+        // Even if child selector generation failed, try with a basic role/text selector
+        // This handles cases where the element has a role but tryElementSelector didn't find it unique
+        if (elementInfo.role) {
+            const name = elementInfo.ariaLabel || elementInfo.label || elementInfo.text;
+            if (name && name.trim()) {
+                const childSelector = {
+                    type: 'role',
+                    role: elementInfo.role,
+                    name: name.trim(),
+                    exact: false,
+                };
+                const nestedDescriptor = createNestedSelector(bestParentSelector, childSelector);
+                const verification = await verifySelectorUniqueness(page, nestedDescriptor, targetMimicId ?? null);
+                if (verification.unique) {
+                    return nestedDescriptor;
+                }
             }
-            if (el.id) {
-                const label = doc.querySelector(`label[for="${el.id}"]`);
-                if (label)
-                    return (label.textContent || '').trim();
+            // Try role without name
+            const childSelector = {
+                type: 'role',
+                role: elementInfo.role,
+            };
+            const nestedDescriptor = createNestedSelector(bestParentSelector, childSelector);
+            const verification = await verifySelectorUniqueness(page, nestedDescriptor, targetMimicId ?? null);
+            if (verification.unique) {
+                return nestedDescriptor;
             }
-            const parentLabel = el.closest('label');
-            if (parentLabel)
-                return (parentLabel.textContent || '').trim();
-            return null;
         }
-        function inferRole(el) {
-            const explicitRole = el.getAttribute('role');
-            if (explicitRole)
-                return explicitRole;
-            const tag = el.tagName.toLowerCase();
-            const roleMap = {
-                'button': 'button',
-                'a': 'link',
-                'input': el.type === 'button' || el.type === 'submit' || el.type === 'reset' ? 'button' :
-                    el.type === 'checkbox' ? 'checkbox' :
-                        el.type === 'radio' ? 'radio' : 'textbox',
-                'select': 'combobox',
-                'textarea': 'textbox',
-                'img': 'img',
+        // Try with text selector if available
+        if (elementInfo.text && elementInfo.text.trim() && elementInfo.text.length < 50) {
+            const childSelector = {
+                type: 'text',
+                value: elementInfo.text.trim(),
+                exact: false,
             };
-            return roleMap[tag] || null;
-        }
-        function getDataset(el) {
-            const dataset = {};
-            for (const attr of el.attributes) {
-                if (attr.name.startsWith('data-')) {
-                    const key = attr.name.replace(/^data-/, '').replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
-                    dataset[key] = attr.value;
-                }
+            const nestedDescriptor = createNestedSelector(bestParentSelector, childSelector);
+            const verification = await verifySelectorUniqueness(page, nestedDescriptor, targetMimicId ?? null);
+            if (verification.unique) {
+                return nestedDescriptor;
             }
-            return dataset;
         }
-        return {
-            tag: parent.tagName.toLowerCase(),
-            text: getVisibleText(parent),
-            id: parent.id || null,
-            role: inferRole(parent),
-            label: getLabel(parent),
-            ariaLabel: parent.getAttribute('aria-label') || null,
-            dataset: getDataset(parent),
+    }
+    // If we get here, either:
+    // 1. No parent selector found and element selector isn't unique, OR
+    // 2. Parent selector found but nested selector isn't unique, OR
+    // 3. No element selector could be generated
+    // In these cases, we'll fall through to CSS fallback below
+    // Final fallback: CSS selector with nth-of-type (only if nothing else works)
+    // This is the absolute last resort - all better selector methods have been exhausted
+    // Try name attribute first (if available) before nth-of-type
+    if (elementInfo.nameAttr && elementInfo.nameAttr.trim()) {
+        const nameValue = elementInfo.nameAttr.trim();
+        const nameSelector = {
+            type: 'css',
+            selector: `[name="${nameValue}"]`,
         };
-    }, targetElementHandle);
-    if (parentInfo) {
-        // Try to find selector for parent
-        const tryParentSelector = async () => {
-            // Check parent for testid
-            if (parentInfo.dataset.testid) {
-                const parentDescriptor = {
-                    type: 'testid',
-                    value: parentInfo.dataset.testid,
-                };
-                // Try to find child selector
-                const childSelector = await tryElementSelector();
-                if (childSelector) {
-                    parentDescriptor.child = childSelector;
-                    if (await verifySelectorUniqueness(page, parentDescriptor, targetElementHandle)) {
-                        return parentDescriptor;
-                    }
-                }
-                // Parent testid alone might be unique enough
-                if (await verifySelectorUniqueness(page, parentDescriptor, targetElementHandle)) {
-                    return parentDescriptor;
-                }
-            }
-            // Check parent for role
-            if (parentInfo.role) {
-                const name = parentInfo.ariaLabel || parentInfo.label || parentInfo.text;
-                const parentDescriptor = {
-                    type: 'role',
-                    role: parentInfo.role,
-                    name: name?.trim(),
-                    exact: false,
-                };
-                const childSelector = await tryElementSelector();
-                if (childSelector) {
-                    parentDescriptor.child = childSelector;
-                    if (await verifySelectorUniqueness(page, parentDescriptor, targetElementHandle)) {
-                        return parentDescriptor;
-                    }
-                }
-            }
-            return null;
+        const verification = await verifySelectorUniqueness(page, nameSelector, targetMimicId ?? null, timeout);
+        if (verification.unique) {
+            return nameSelector;
+        }
+    }
+    // Try ID selector before nth-of-type
+    if (elementInfo.id && elementInfo.id.trim()) {
+        const idValue = elementInfo.id.trim();
+        const idSelector = {
+            type: 'css',
+            selector: `#${idValue}`,
         };
-        const parentSelector = await tryParentSelector();
-        if (parentSelector) {
-            return parentSelector;
+        const verification = await verifySelectorUniqueness(page, idSelector, targetMimicId ?? null, timeout);
+        if (verification.unique) {
+            return idSelector;
         }
     }
-    // Final fallback: CSS selector (should always work)
+    // Absolute last resort: nth-of-type CSS selector
+    // This is the least stable selector type, only used when all else fails
     const fallback = {
         type: 'css',
         selector: `${elementInfo.tag}:nth-of-type(${elementInfo.nthOfType})`,