playwright-genie 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vijay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,435 @@
+# playwright-nlp-locator
+
+> 🎯 Find Playwright locators using natural language descriptions powered by LLM
+
+[![npm version](https://img.shields.io/npm/v/playwright-nlp-locator.svg)](https://www.npmjs.com/package/playwright-nlp-locator)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**playwright-nlp-locator** enables you to write browser automation scripts using plain English instead of manually inspecting elements and writing complex selectors. Simply describe the element you want to interact with, and the library will find the best Playwright locator for it.
+
+## ✨ Features
+
+- 🗣️ **Natural Language Descriptions** - Describe elements in plain English
+- 🎯 **Smart Locator Generation** - Returns optimal locators (role-based > text-based > CSS)
+- 📊 **Confidence Scores** - Know how confident the match is
+- 🔄 **Alternative Suggestions** - Get multiple locator options
+- 🛠️ **TypeScript Support** - Full type definitions included
+- 🤖 **LLM-Powered** - Uses Abacus.AI APIs for intelligent matching
+- 📦 **Production Ready** - Error handling, edge cases, and best practices
+
+## 📦 Installation
+
+```bash
+npm install playwright-nlp-locator playwright
+```
+
+### Prerequisites
+
+1. **Playwright** - The library works with Playwright
+2. **Python 3** - Required for LLM API calls
+3. **Abacus.AI Python SDK** - Install with `pip install abacusai`
+4. **Abacus.AI API Key** - Set the `ABACUS_API_KEY` environment variable
+
+```bash
+pip install abacusai
+export ABACUS_API_KEY="your-api-key-here"
+```
+
+## 🚀 Quick Start
+
+```javascript
+const { chromium } = require('playwright');
+const { findLocator, createNLPHelper } = require('playwright-nlp-locator');
+
+async function main() {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  await page.goto('https://example.com');
+
+  // Option 1: Get the locator string
+  const result = await findLocator(page, 'Login Button');
+  console.log(result.locator);  // e.g., "page.getByRole('button', { name: 'Login' })"
+  console.log(result.confidence);  // e.g., 0.95
+
+  // Option 2: Use the NLP Helper for direct interaction
+  const nlp = createNLPHelper(page);
+  await nlp.click('Submit button');
+  await nlp.type('Email input field', 'user@example.com');
+  await nlp.type('Password field', 'secret123');
+
+  await browser.close();
+}
+
+main();
+```
+
+## 📖 API Reference
+
+### `findLocator(page, description, options?)`
+
+Find a Playwright locator using natural language description.
+
+**Parameters:**
+- `page` - Playwright Page object
+- `description` - Natural language description of the element
+- `options` - Optional configuration object
+
+**Returns:** `Promise<FindLocatorResult>`
+
+```javascript
+const result = await findLocator(page, 'email input field');
+
+// Result object:
+{
+  found: true,
+  locator: "page.getByPlaceholder('Enter your email')",
+  locatorType: 'placeholder',
+  confidence: 0.92,
+  explanation: 'Input field with placeholder text indicating email entry',
+  alternatives: [
+    { locator: "page.locator('#email')", confidence: 0.85 }
+  ],
+  elementIndex: 3
+}
+```
+
+### `getLocator(page, description, options?)`
+
+Get an actual Playwright Locator object ready for interaction.
+
+```javascript
+const { locator, result } = await getLocator(page, 'Submit button');
+
+// Use the locator directly
+await locator.click();
+await locator.fill('text');
+const text = await locator.textContent();
+```
+
+### `findAllLocators(page, description, options?)`
+
+Find multiple matching elements for a description.
+
+```javascript
+const matches = await findAllLocators(page, 'navigation links');
+
+// Returns array of matches:
+[
+  { locator: "page.getByRole('link', { name: 'Home' })", confidence: 0.90, type: 'role' },
+  { locator: "page.getByRole('link', { name: 'About' })", confidence: 0.88, type: 'role' }
+]
+```
+
+### `createNLPHelper(page, options?)`
+
+Create a helper object with natural language methods.
+
+```javascript
+const nlp = createNLPHelper(page);
+
+// Available methods:
+await nlp.click('Login button');
+await nlp.type('Username field', 'john_doe');
+await nlp.select('Country dropdown', 'USA');
+await nlp.hover('Profile menu');
+await nlp.waitFor('Loading spinner to disappear');
+const text = await nlp.getText('Welcome message');
+const exists = await nlp.exists('Error message');
+```
+
+## ⚙️ Configuration Options
+
+```javascript
+const options = {
+  // Maximum elements to analyze (default: 100)
+  maxElements: 100,
+  
+  // Include hidden elements (default: false)
+  includeHiddenElements: false,
+  
+  // Minimum confidence to accept (default: 0.5)
+  confidenceThreshold: 0.5,
+  
+  // LLM model to use (default: 'claude-3-5-sonnet')
+  model: 'claude-3-5-sonnet',
+  
+  // Locator preference order
+  preferredLocatorOrder: ['role', 'text', 'testId', 'css', 'xpath']
+};
+
+const result = await findLocator(page, 'Submit button', options);
+```
+
+## 🎯 Best Practices for Descriptions
+
+### ✅ Good Descriptions
+
+```javascript
+// Be specific about the element type
+await nlp.click('Login button');
+await nlp.type('Email input field', 'user@example.com');
+await nlp.click('Submit form button');
+
+// Include context when needed
+await nlp.click('Add to cart button for the first product');
+await nlp.type('Search box in the header', 'shoes');
+
+// Use visual or functional descriptions
+await nlp.click('Red cancel button');
+await nlp.click('Hamburger menu icon');
+await nlp.click('Close modal X button');
+```
+
+### ❌ Avoid Vague Descriptions
+
+```javascript
+// Too vague - could match multiple elements
+await nlp.click('button');
+await nlp.type('input', 'text');
+
+// Better alternatives:
+await nlp.click('primary submit button');
+await nlp.type('username input', 'text');
+```
+
+## 📚 Complete Examples
+
+### Example 1: Login Form Automation
+
+```javascript
+const { chromium } = require('playwright');
+const { createNLPHelper } = require('playwright-nlp-locator');
+
+async function loginAutomation() {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  
+  await page.goto('https://myapp.com/login');
+  
+  const nlp = createNLPHelper(page);
+  
+  // Fill login form using natural language
+  await nlp.type('Username or email input', 'john@example.com');
+  await nlp.type('Password field', 'secretPassword123');
+  
+  // Check "Remember me" if it exists
+  if (await nlp.exists('Remember me checkbox')) {
+    await nlp.click('Remember me checkbox');
+  }
+  
+  // Submit the form
+  await nlp.click('Sign in button');
+  
+  // Wait for dashboard to load
+  await nlp.waitFor('Dashboard header');
+  
+  console.log('Login successful!');
+  
+  await browser.close();
+}
+```
+
+### Example 2: E-commerce Shopping Flow
+
+```javascript
+async function shoppingFlow() {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  const nlp = createNLPHelper(page);
+  
+  await page.goto('https://shop.example.com');
+  
+  // Search for a product
+  await nlp.type('Search bar', 'wireless headphones');
+  await nlp.click('Search button');
+  
+  // Filter results
+  await nlp.click('Price filter dropdown');
+  await nlp.click('Under $100 option');
+  
+  // Select a product
+  await nlp.click('First product in the list');
+  
+  // Add to cart
+  await nlp.select('Size selector', 'Medium');
+  await nlp.click('Add to cart button');
+  
+  // Proceed to checkout
+  await nlp.click('Shopping cart icon');
+  await nlp.click('Proceed to checkout button');
+  
+  // Fill shipping info
+  await nlp.type('First name field', 'John');
+  await nlp.type('Last name field', 'Doe');
+  await nlp.type('Address line 1', '123 Main St');
+  await nlp.type('City input', 'New York');
+  await nlp.select('State dropdown', 'NY');
+  await nlp.type('Zip code', '10001');
+  
+  await nlp.click('Continue to payment button');
+  
+  await browser.close();
+}
+```
+
+### Example 3: Form Validation Testing
+
+```javascript
+const { findLocator, getLocator } = require('playwright-nlp-locator');
+
+async function testFormValidation() {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  
+  await page.goto('https://myapp.com/signup');
+  
+  // Submit empty form to trigger validation
+  const { locator: submitBtn } = await getLocator(page, 'Submit button');
+  await submitBtn.click();
+  
+  // Check for validation errors
+  const emailError = await findLocator(page, 'Email validation error message');
+  if (emailError.found && emailError.confidence > 0.7) {
+    console.log('Email validation working:', emailError.locator);
+  }
+  
+  const passwordError = await findLocator(page, 'Password error message');
+  if (passwordError.found) {
+    const { locator } = await getLocator(page, 'Password error');
+    const errorText = await locator.textContent();
+    console.log('Password error:', errorText);
+  }
+  
+  await browser.close();
+}
+```
+
+### Example 4: Dynamic Content Handling
+
+```javascript
+async function handleDynamicContent() {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  const nlp = createNLPHelper(page);
+  
+  await page.goto('https://app.example.com');
+  
+  // Wait for dynamic content to load
+  await nlp.waitFor('Content loaded indicator');
+  
+  // Handle modals
+  if (await nlp.exists('Cookie consent popup')) {
+    await nlp.click('Accept cookies button');
+  }
+  
+  if (await nlp.exists('Newsletter subscription modal')) {
+    await nlp.click('Close modal button');
+  }
+  
+  // Interact with lazy-loaded content
+  await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight));
+  await nlp.waitFor('Load more button');
+  await nlp.click('Load more button');
+  
+  await browser.close();
+}
+```
+
+## 🔧 Locator Types
+
+The library returns different types of locators based on element attributes:
+
+| Type | Example | Priority |
+|------|---------|----------|
+| Role | `page.getByRole('button', { name: 'Submit' })` | 1 (Highest) |
+| Text | `page.getByText('Click here')` | 2 |
+| Label | `page.getByLabel('Email address')` | 3 |
+| Placeholder | `page.getByPlaceholder('Enter email')` | 4 |
+| TestId | `page.getByTestId('submit-btn')` | 5 |
+| CSS | `page.locator('button.primary')` | 6 |
+| XPath | `page.locator('//button[@id="submit"]')` | 7 (Lowest) |
+
+## 🐛 Error Handling
+
+```javascript
+const { findLocator, getLocator } = require('playwright-nlp-locator');
+
+// Method 1: Check result
+const result = await findLocator(page, 'Missing element');
+if (!result.found) {
+  console.log('Element not found:', result.error);
+}
+
+if (result.confidence < 0.5) {
+  console.log('Low confidence match - may be incorrect');
+}
+
+// Method 2: Try-catch with getLocator
+try {
+  const { locator } = await getLocator(page, 'Element description');
+  await locator.click();
+} catch (error) {
+  console.error('Failed to find element:', error.message);
+}
+
+// Method 3: Fallback locators
+const result = await findLocator(page, 'Submit button');
+if (result.confidence < 0.7 && result.alternatives?.length > 0) {
+  console.log('Using alternative locator:', result.alternatives[0].locator);
+}
+```
+
+## 🔒 Security Notes
+
+- The library sends page DOM structure to the LLM API for analysis
+- Sensitive data in element values may be visible to the API
+- Consider using this in development/testing environments
+- For production, ensure compliance with your data policies
+
+## 📄 TypeScript Usage
+
+```typescript
+import { chromium, Page } from 'playwright';
+import { 
+  findLocator, 
+  getLocator, 
+  createNLPHelper, 
+  FindLocatorResult,
+  NLPHelper,
+  NLPLocatorConfig 
+} from 'playwright-nlp-locator';
+
+async function typedExample(): Promise<void> {
+  const browser = await chromium.launch();
+  const page: Page = await browser.newPage();
+  
+  const config: NLPLocatorConfig = {
+    confidenceThreshold: 0.7,
+    maxElements: 50
+  };
+  
+  const result: FindLocatorResult = await findLocator(page, 'Login button', config);
+  
+  if (result.found && result.confidence >= 0.7) {
+    console.log(`Found: ${result.locator}`);
+  }
+  
+  const nlp: NLPHelper = createNLPHelper(page, config);
+  await nlp.click('Submit button');
+  
+  await browser.close();
+}
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 📝 License
+
+MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- [Playwright](https://playwright.dev/) - The underlying browser automation framework
+- [Abacus.AI](https://abacus.ai/) - LLM API powering the natural language understanding