⚡ Locator Labs Desktop

✨ Features

🎯 Smart Locator Generation

• Semantic Locators - Accessibility-first locators (getByRole, getByLabel, getByText)
• Quality Ratings - Each locator rated as BEST, GOOD, OK, or FRAGILE
• Multiple Strategies - ID, Name, CSS Selector, XPath, Link Text, and more

🔧 Multi-Framework Support

| Framework | Languages | |-----------|-----------| | Playwright | JavaScript/TypeScript, Python | | Selenium | Java, Python | | Cypress | JavaScript/TypeScript |

🚀 Powerful Capabilities

| Feature | Description | |---------|-------------| | Live Element Inspector | Point and click to select elements | | Built-in Browser | No need to switch between apps | | Multi-Tab Support | Work with multiple pages simultaneously | | Shadow DOM Support | Works with web components | | iFrame Support | Handles nested frames automatically with frameLocator() | | SVG Element Support | Special handling for SVG elements with local-name() XPath | | Test Locator | Validate locators before using them | | Action Autocomplete | .click(), .fill(), .type(), .should() and more | | Dark/Light Theme | Easy on the eyes |

🎯 PO Mode (Page Object Mode)

One-click element capture for rapid Page Object creation!

| Feature | Description | |---------|-------------| | Quick Toggle | Click the PO button to enable/disable | | Click to Add | Simply click elements to add them to your cart | | Status Bar | Shows "PO Mode Active" above URL bar | | Duplicate Prevention | Won't add the same element twice | | Visual Feedback | Toast notifications confirm additions | | ESC to Exit | Press ESC key to quickly disable PO Mode |

📦 Page Object Model Generator

Generate production-ready Page Object classes for:

• Playwright (TypeScript, JavaScript, Python)
• Selenium (Java, Python)
• Cypress
• WebdriverIO
• Robot Framework

📥 Download

Latest Release: v1.1.0

| Platform | Download | |----------|----------| | 🍎 macOS (Universal - Intel & Apple Silicon) | LocatorLabs-1.1.0-universal.dmg | | 🪟 Windows | LocatorLabs Setup 1.1.0.exe | | 🐧 Linux | LocatorLabs-1.1.0.AppImage |

👉 View all releases

💡 Note: macOS users may need to right-click and select "Open" for the first launch due to Gatekeeper.

Alternative: Install via npm

For developers who prefer npm or work in environments where .exe files are restricted:

# Install globally
npm install -g locatorlabs
locatorlabs

# Or run directly without installing (one-time use)
npx locatorlabs

# With dev tools enabled
npx locatorlabs --dev

Requirements for npm installation:

• Node.js 16 or later
• npm 7 or later

🚀 Getting Started

Installation

1. Download the installer for your platform from Releases
2. macOS: Open the .dmg and drag Locator Labs to Applications
3. Windows: Run the .exe installer
4. Linux: Make the .AppImage executable: chmod +x LocatorLabs-1.1.0.AppImage and run it

Quick Start Guide

1. Launch Locator Labs Desktop
2. Enter a URL in the address bar and press Go
3. Click "Start Inspecting" to enable element selection
4. Click any element on the page to generate locators
5. Choose your framework (Playwright/Selenium/Cypress) using the tabs
6. Copy the locator using the 📋 button

📖 How to Use

Generating Locators

1. Navigate to your target website
2. Click "Start Inspecting" button (turns green when active)
3. Hover over elements - they get highlighted
4. Click an element to capture it
5. View all generated locators with quality ratings
6. Click 📋 to copy or ➕ to add to Page Object cart

Testing Locators

1. Enter any locator in the "Test Locator" field
2. Click ▶ to execute
3. See how many elements match
4. Use ◀ ▶ arrows to navigate through matches
5. Supports Playwright, Selenium, and Cypress syntax

Building Page Objects

1. While inspecting, click ➕ on locators you want to save
2. Click the 📦 cart icon in the header
3. Enter a page name (e.g., "LoginPage")
4. Select your framework and language
5. Click "Download File" or "Copy to Clipboard"

Using PO Mode (Faster Method!)

1. Click the "PO" button next to the URL bar (turns green when active)
2. Status bar appears: "PO Mode Active - Click on elements to add"
3. Click any element on the page - it's automatically added to cart
4. Repeat for all elements you need
5. Press ESC or click "PO" again to exit
6. Click 📦 cart icon to generate your Page Object class

Tips:

• Duplicate elements are automatically prevented
• Green toast = element added successfully
• Red toast = element already in cart
• Works with iframes and Shadow DOM elements

🎯 Locator Quality Guide

| Rating | Meaning | Stability | |--------|---------|-----------| | 🟢 BEST | Semantic, accessible locators | Very Stable | | 🔵 GOOD | Reliable with good specificity | Stable | | 🟡 OK | Works but may need updates | Moderate | | 🔴 FRAGILE | Likely to break with UI changes | Unstable |

Examples by Framework

Playwright (BEST)

page.getByRole('button', { name: 'Submit' })
page.getByLabel('Email')
page.getByTestId('login-form')
page.frameLocator('iframe#main').getByRole('button')

Selenium (BEST → GOOD)

driver.findElement(By.id("submit-btn"))
driver.findElement(By.name("email"))
driver.findElement(By.cssSelector("[data-testid='login']"))

Cypress (BEST → GOOD)

cy.get('[data-testid="submit"]')
cy.contains('button', 'Submit')
cy.get('#email').shadow().find('input')
cy.xpath('//button[@id="login"]')

⚙️ System Requirements

| Platform | Minimum Version | |----------|-----------------| | macOS | 10.13 High Sierra or later | | Windows | Windows 10 or later | | Linux | Ubuntu 18.04+ or equivalent |

🆕 What's New

v1.1.8

• ✅ PO Mode (Page Object Mode) - Click the PO button, then click elements to instantly add them to your Page Object cart
• ✅ PO Mode Status Bar - Visual indicator above URL bar showing when PO Mode is active
• ✅ Duplicate Prevention - Same element cannot be added twice to the cart
• ✅ SVG XPath Fix - Proper local-name() syntax for SVG elements
• ✅ Improved Variable Naming - Better camelCase/snake_case naming based on element IDs
• ✅ iFrame Detection Fix - Correctly detects elements inside iframes for Selenium/Cypress
• ✅ Tour Guide Update - Added PO Mode to the interactive tour

v1.1.0

• ✅ Cypress Framework Support - Full locator generation with cy.get(), cy.contains(), cy.xpath()
• ✅ Cypress Actions - Autocomplete for .click(), .type(), .should(), .invoke(), .trigger()
• ✅ Interactive Tour Guide - Onboarding experience for new users
• ✅ Playwright frameLocator() - Automatic iframe handling with nested frame support
• ✅ Shadow DOM for Cypress - cy.get().shadow() chain support
• ✅ Improved Test Locator - Better frame navigation and error messages
• ✅ Bug Fixes - XPath quote handling, accessible name matching, and more

v1.0.0

• ✅ Initial Release
• ✅ Playwright & Selenium support
• ✅ Page Object Model generator (8 frameworks)
• ✅ Shadow DOM & iFrame handling
• ✅ Multi-tab browsing
• ✅ Dark/Light theme
• ✅ URL history with suggestions
• ✅ Test locator with element navigation

❓ FAQ

• Generates semantic locators automatically (getByRole, getByLabel)
• Provides quality ratings to help you choose the best locator
• Works in enterprise environments where extensions are blocked
• Built-in Page Object Model generator
• Supports Playwright, Selenium, and Cypress in one tool
• Test and validate locators before using them in your tests

Right-click the app and select "Open", then click "Open" in the dialog. You only need to do this once.

Yes! The built-in browser maintains your session, so you can log in and inspect authenticated pages. Your session persists across page navigations.

Yes! As of v1.1.0, full Cypress support is included with cy.get(), cy.contains(), cy.xpath(), Shadow DOM chains, and action autocomplete.

LocatorLabs automatically detects elements inside iframes and generates the appropriate locators:

• Playwright: Adds frameLocator() prefix automatically (e.g., page.frameLocator('iframe#main').getByRole('button'))
• Selenium: Shows "Switch to Frame First" instructions with the frame switching code
• Cypress: Generates iframe-aware locators

Nested iframes are also supported!

Yes! LocatorLabs fully supports Shadow DOM elements:

• Playwright: Uses pierce selectors or JS path to reach shadow elements
• Selenium: Generates JavaScript executor code for shadow DOM traversal
• Cypress: Creates .shadow() chain locators (e.g., cy.get('#host').shadow().find('button'))

The Test Locator lets you validate any locator before using it in your tests:

• Enter any Playwright, Selenium, or Cypress locator
• Click ▶ to execute and see how many elements match
• Elements are highlighted on the page
• Navigate through multiple matches using ◀ ▶ arrows
• Autocomplete suggests actions like .click(), .fill(), .type()

Method 1: Traditional (using ➕ button)

1. While inspecting elements, click ➕ on locators you want to include
2. Click the 📦 cart icon in the header
3. Enter a page name (e.g., "LoginPage")
4. Select your framework (Playwright, Selenium, Cypress, WebdriverIO, Robot Framework)
5. Choose your language
6. Click "Download File" or "Copy to Clipboard"

Method 2: PO Mode (Faster!)

1. Click the PO button next to the URL bar
2. Simply click on elements - they're automatically added
3. Press ESC when done
4. Click 📦 cart to generate your class

PO Mode (Page Object Mode) is a faster way to build Page Objects:

1. Click the PO button next to the URL bar (it turns green)
2. A status bar appears: "PO Mode Active - Click on elements to add"
3. Click any element on the page - it's instantly added to your cart
4. A green toast confirms: "Added to Page Object"
5. If you try to add a duplicate, a red toast warns: "Element already in cart!"
6. Press ESC or click PO again to exit
7. Click the 📦 cart icon to generate your Page Object class

Benefits:

• Much faster than clicking ➕ for each locator
• Automatic duplicate prevention
• Works with iframes and Shadow DOM
• Visual feedback for every action

| Rating | Example | Why | |--------|---------|-----| | 🟢 BEST | getByRole('button', { name: 'Submit' }) | Semantic, accessibility-based, resilient to UI changes | | 🔵 GOOD | By.id("submit-btn") | Stable identifiers, unlikely to change | | 🟡 OK | By.cssSelector(".btn-primary") | Class-based, may change with styling updates | | 🔴 FRAGILE | By.xpath("//div[3]/button[1]") | Position-based, breaks easily with DOM changes |

Yes! XPath is supported for all frameworks:

• Playwright: page.locator('xpath=//button[@id="submit"]')
• Selenium: driver.findElement(By.xpath("//button[@id='submit']"))
• Cypress: cy.xpath('//button[@id="submit"]') (requires cypress-xpath plugin)

LocatorLabs handles quote escaping automatically for complex XPath expressions.

Yes! After typing a complete locator and adding a ., you'll see action suggestions:

• Playwright: .click(), .fill(), .textContent(), .isVisible(), .hover(), and more
• Selenium: .click(), .sendKeys(), .getText(), .isDisplayed(), and more
• Cypress: .click(), .type(), .should(), .invoke(), .trigger(), and more

The Test Locator shows you the count of matching elements. Use the ◀ ▶ navigation arrows to cycle through each match - each element gets highlighted in turn. This helps you verify your locator is specific enough or identify if you need to add more specificity.

The application itself works offline, but you need an internet connection to browse websites. All locator generation, testing, and Page Object creation happen locally on your machine.

Yes! Common shortcuts include:

• Ctrl/Cmd + R: Refresh page
• Ctrl/Cmd + L: Focus URL bar
• Escape: Stop inspecting
• Arrow keys: Navigate through autocomplete suggestions

LocatorLabs prioritizes stable locators:

1. Use semantic locators like getByRole, getByLabel, getByText (rated BEST)
2. Look for data-testid attributes if available
3. Use partial matches with contains() for text that remains stable
4. Avoid position-based XPath (rated FRAGILE)

The quality ratings help you identify which locators are most resilient.

Yes! Version 1.1.0 includes an interactive Tour Guide that walks you through all the features step-by-step. It starts automatically for first-time users, or you can restart it anytime from the Help menu.

Common reasons and solutions:

• Element is in an iframe: LocatorLabs should detect this automatically, but ensure the iframe is same-origin
• Element is in Shadow DOM: Supported - check if the shadow root is open
• Page is still loading: Wait for the page to fully load before inspecting
• Element is dynamically rendered: Interact with the page to make the element appear first

Yes! LocatorLabs Desktop is designed for enterprise use:

• No browser extension required (works where extensions are blocked)
• Runs locally on your machine (no data sent to external servers)
• Works with internal/intranet applications
• Supports authentication and maintains sessions
• npm installation available for environments where .exe files are blocked but npm is allowed

Yes! If you have Node.js installed, you can use npm:

# One-time run (no install)
npx locatorlabs

# Or install globally
npm install -g locatorlabs
locatorlabs

This is useful for:

• Developers who prefer command-line installation
• Environments where .exe downloads are blocked but npm is allowed
• Keeping the app updated easily via npm

🤝 Support & Feedback

• Issues: GitHub Issues
• Website: locator-labs.com
• YouTube: Naveen AutomationLabs

📄 License

Proprietary Software - All Rights Reserved © 2025 Naveen Automation Labs