Interactive User Manual

Complete manual on how to configure, launch, and use Selector Studio in your QA workflow.

🚀 Quick Start Checklist

Follow these steps to configure your local extension development copy or live production instances correctly.

⚙️ Add / Install the Chrome Extension

🎯 Prerequisite: Ensure you have a Chromium-based browser installed (Google Chrome, Microsoft Edge, Brave, Opera, etc.) and that the backend server is running locally (http://localhost:3000).

1 Start the Local Server

Open a terminal in the backend/ folder of the project, install dependencies, and launch the server:

cd backend
npm install
node server.js

2 Build the Extension Bundle

Open a new terminal in the main project root folder, install dependency packages, and run the build command to generate the compiled files:

npm install
npm run build

This compiles TypeScript scripts and aggregates assets into the dist/ folder.

3 Open Chrome Extensions Manager

Open Google Chrome and navigate to the Extensions page by visiting: chrome://extensions/. Alternatively, click the puzzle icon (🧩) in the toolbar and select "Manage Extensions".

4 Enable Developer Mode

Toggle the "Developer mode" switch located in the upper-right corner of the extensions page to the ON position.

5 Load Unpacked Extension Folder

Click the "Load unpacked" button in the top-left corner of the page. In the folder browser dialog, navigate to your project's directory and select the newly generated dist folder.

6 Pin the Extension for Easy Access

Once loaded, click the puzzle icon (🧩) in your Chrome toolbar, find Playwright Selector Tool, and click the pin icon (📌) to place it directly on your browser toolbar.

🔍 How to Use the Chrome Extension

Selector Studio provides three intuitive options for inspecting webpages and capturing resilient selectors directly from your browsing context:

🖱️ Alt + Click Selection (Overlay Panel)

Perfect for deep analysis and choosing alternative element selector formats:

  • Hold down the Alt key on your keyboard.
  • Click any element on a webpage to launch the Selector Studio floating side-panel.
  • Playwright Locator: Displays role-based recommended selectors (e.g. page.getByRole()).
  • CSS Selector: Resilient CSS identifier paths.
  • XPath Queries: High-precision absolute/relative XPaths, with a dropdown to expand multiple fallback paths.
  • Click Copy buttons to copy to clipboard instantly.
  • Press Esc or click the "x" to dismiss the panel.

⚡ Smart Locator Mode (PRO Highlighter)

Fast-track element locator capture with hover styling and tooltip support:

  • Click the extension toolbar icon to open the popup interface.
  • Click the Use Smart Locator (PRO) button (Requires PRO license).
  • The popup closes, entering interactive selection mode. Hovering elements outlines them in bright green.
  • A floating tooltip tracks your mouse cursor and displays the best locator (automatically prioritizing data-testid tags).
  • Left-click any highlighted element to copy its selector instantly and close selection mode.
  • Press Esc to cancel and exit.

📋 Right-Click Context Menu (Instant Copy)

Immediate, low-friction element capture without triggering overlay panels:

  • Simply right-click on any element on the page.
  • Click Copy Playwright Selector from the browser context menu.
  • The calculated Playwright code block is generated and copied to your clipboard instantly.

💳 Authentication & Pro Upgrades

✨ New Accounts: Every newly registered user receives a 60-day free trial to explore basic elements and test-run features!

1. Log In to Sync Local Settings

Open the extension popup and click Sign In / Login. Enter your email on the login page and click Login. The authentication credentials will automatically sync and save inside the extension.

2. Support Active Development (Optional)

To support active development, you can contribute any custom amount (default: ₹200) securely through Razorpay using the support section on the homepage or popup.

3. Complete Test Transaction

Click Pay Now on the checkout page. The Razorpay gateway modal will open. Select "Netbanking" or any "Test Payment" option, authorize the simulation, and wait. The page will verify the signature with the database and unlock PRO instantly.

4. Verify Local Plan Status

Open the extension popup and click Check Plan. The badge in the top-right corner of the popup will transition to a green PRO status tag.

❓ Troubleshooting & FAQ

Why does "Alt + Click" or "Smart Locator" not work on some pages?

Chrome security policies restrict third-party extensions from injecting content scripts into specific internal system pages (like chrome://extensions, chrome://settings) and the official Chrome Web Store. Try testing on standard public websites (e.g. Google, Wikipedia, or your own local web applications).

My subscription plan is not updating in the extension popup.

Ensure the backend Node.js server is actively running in your terminal at http://localhost:3000. Open the popup and click the Check Plan button to query the backend database and force a refresh of your local subscription state.

How can I copy selectors using data-testid?

Smart Locator Mode automatically prioritizes standard QA identifiers such as data-testid. Simply activate Smart Locator mode, hover over elements with test IDs, and click. It will copy the clean page.locator('[data-testid="value"]') path directly.