@testnexus/locatai 1.7.0

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@testnexus/locatai",
+  "version": "1.7.0",
+  "description": "AI-powered self-healing locators for Playwright. When locators fail, AI automatically finds the correct element.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "SELF_HEAL=1 npx playwright test",
+    "test:headed": "SELF_HEAL=1 npx playwright test --headed",
+    "test:unit": "vitest run",
+    "test:heal": "SELF_HEAL=1 npx playwright test examples/element-zoo-healing.test.ts",
+    "test:ci": "npm run test:unit && npm run test:heal",
+    "lint": "eslint src/",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "playwright",
+    "testing",
+    "automation",
+    "self-healing",
+    "ai",
+    "locators",
+    "e2e",
+    "end-to-end",
+    "web-testing",
+    "resilient-tests",
+    "gpt",
+    "openai",
+    "anthropic",
+    "claude",
+    "gemini",
+    "google",
+    "ollama",
+    "local-llm"
+  ],
+  "author": "Divyarajsinh Dodia",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Divyarajsinh-Dodia1617/LocatAi.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Divyarajsinh-Dodia1617/LocatAi/issues"
+  },
+  "homepage": "https://github.com/Divyarajsinh-Dodia1617/LocatAi#readme",
+  "peerDependencies": {
+    "@playwright/test": ">=1.40.0"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.74.0",
+    "@google/genai": "^1.41.0",
+    "ollama": "^0.6.3",
+    "openai": "^6.22.0",
+    "playwright-core": ">=1.40.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.58.2",
+    "@types/node": "^25.2.3",
+    "dotenv": "^17.3.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/readme.md

@@ -0,0 +1,361 @@
+<div align="center">
+  # LocatAI
+
+  AI-powered self-healing locators for Playwright. When your selectors break, LocatAI figures out what you meant and finds the element anyway.
+
+  [![npm version](https://badge.fury.io/js/@testnexus/locatai.svg)](https://www.npmjs.com/package/@testnexus/locatai)
+  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+</div>
+
+## Why?
+
+We've all been there. You write a solid test suite, everything passes, then the frontend team refactors something and half your locators break. You spend hours updating selectors instead of writing actual tests.
+
+LocatAI fixes this. It wraps your Playwright page with AI-powered healing that kicks in when locators fail. You can also skip selectors entirely and just describe what you're looking for in plain English.
+
+## Features
+
+- **Self-healing locators** - When a selector breaks, AI analyzes the page and finds the right element
+- **AI-only mode** - Just describe the element, no selector needed
+- **Multi-provider** - OpenAI, Anthropic, Google, or run locally with Ollama — your choice
+- **Local LLM support** - Run completely offline with Ollama. No API keys, no cloud, full privacy
+- **Caching** - Healed selectors are saved so you don't burn API calls on every run
+- **Drop-in** - Works with your existing Playwright setup
+
+## Installation
+
+```bash
+npm install @testnexus/locatai
+```
+
+## Quick Start
+
+Set your API key and enable healing:
+
+```bash
+# OpenAI (default) - also accepts AI_PROVIDER=gpt
+export AI_API_KEY="your-openai-key"
+export SELF_HEAL=1
+
+# Anthropic Claude - also accepts AI_PROVIDER=claude
+export AI_PROVIDER=anthropic
+export AI_API_KEY="your-anthropic-key"
+export SELF_HEAL=1
+
+# Google Gemini - also accepts AI_PROVIDER=gemini  
+export AI_PROVIDER=google
+export AI_API_KEY="your-google-key"
+export SELF_HEAL=1
+
+# Local LLM via Ollama — no API key, no cloud, fully offline!
+export AI_PROVIDER=local
+export SELF_HEAL=1
+# Optional: pick a different model (default: gemma3:4b)
+# export AI_MODEL="mistral"
+```
+
+Create a fixture:
+
+```typescript
+// fixtures.ts
+import { test as base } from '@playwright/test';
+import { createLocatAIFixture, LocatAIPage } from '@testnexus/locatai';
+
+export const test = base.extend<{ page: LocatAIPage }>(createLocatAIFixture());
+export { expect } from '@playwright/test';
+```
+
+Use it in your tests:
+
+```typescript
+import { test, expect } from './fixtures';
+
+test('login flow', async ({ page }) => {
+  await page.goto('https://example.com');
+  
+  // If this selector breaks, AI will find the right element
+  await page.locatai.click(
+    page.locator('[data-testid="submit-btn"]'),
+    'Submit button on form'
+  );
+  
+  // Or skip the selector entirely - just describe what you want
+  await page.locatai.fill('', 'Email input field', 'user@example.com');
+});
+```
+
+## API
+
+### `withLocatAI(page)`
+
+Wraps a Playwright page with healing methods:
+
+```typescript
+import { withLocatAI } from '@testnexus/locatai';
+
+const locataiPage = withLocatAI(page);
+await locataiPage.locatai.click(locator, 'Button description');
+```
+
+### `createLocatAIFixture()`
+
+Creates a test fixture that automatically wraps the page:
+
+```typescript
+import { test as base } from '@playwright/test';
+import { createLocatAIFixture, LocatAIPage } from '@testnexus/locatai';
+
+export const test = base.extend<{ page: LocatAIPage }>(createLocatAIFixture());
+```
+
+### Available Methods
+
+All methods take a locator (or empty string for AI-only) and a description:
+
+| Method | What it does |
+|--------|-------------|
+| `locatai.click(locator, desc, options?)` | Click an element |
+| `locatai.fill(locator, desc, value)` | Fill an input |
+| `locatai.selectOption(locator, desc, value)` | Select from dropdown |
+| `locatai.check(locator, desc)` | Check a checkbox |
+| `locatai.uncheck(locator, desc)` | Uncheck a checkbox |
+| `locatai.dblclick(locator, desc)` | Double-click |
+| `locatai.hover(locator, desc)` | Hover over element |
+| `locatai.focus(locator, desc)` | Focus element |
+| `locatai.locator(selector, desc)` | Create self-healing locator for chaining |
+
+### Self-Healing Locator
+
+Create a locator that combines a CSS selector with a semantic description. If the selector fails, AI takes over:
+
+```typescript
+// Combines selector with semantic fallback - best of both worlds
+await page.locatai.locator('.new-todo', 'Input field for new todos').fill('Buy milk');
+await page.locatai.locator('.submit-btn', 'Submit button').click();
+await page.locatai.locator('.toggle', 'Checkbox').check();
+```
+
+### AI-Only Mode
+
+Pass an empty string as the locator and let AI find the element:
+
+```typescript
+await page.locatai.click('', 'Login button');
+await page.locatai.fill('', 'Search input', 'my query');
+```
+
+This is useful when you don't have good selectors or want to make tests more readable.
+
+### Force Click (Hidden Elements)
+
+Some elements only appear on hover (like delete buttons). Use `{ force: true }` to click hidden elements:
+
+```typescript
+// First hover to reveal the element
+await page.locatai.hover('', 'Todo item in the list');
+
+// Then force-click the hidden delete button
+await page.locatai.click('', 'Delete button', { force: true });
+```
+
+### Mixing Healing with Regular Playwright
+
+Just because you've added LocatAI doesn't mean you have to use `page.locatai.*` for everything. The wrapped page still works exactly like a normal Playwright page, so you can mix and match as needed:
+
+```typescript
+// Use healing for elements that tend to break
+await page.locatai.fill('', 'Input field for new todo items', 'Buy groceries');
+
+// Use regular Playwright for stable selectors
+await page.fill('#username', 'testuser');
+await page.click('button[type="submit"]');
+```
+
+Pick the approach that makes sense for each action. Maybe you use healing for that flaky third-party widget but stick with regular locators for your own well-structured components. It's your call.
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SELF_HEAL` | Set to `1` to enable healing |
+| `AI_API_KEY` | Your AI provider API key |
+| `AI_PROVIDER` | `openai`/`gpt`, `anthropic`/`claude`, `google`/`gemini`, or `local`/`ollama` |
+| `AI_MODEL` | Override the default model (optional) |
+| `OLLAMA_HOST` | Ollama server URL (default: `http://127.0.0.1:11434`) |
+
+**Default models by provider:**
+- **OpenAI:** `gpt-5.2`
+- **Anthropic:** `claude-sonnet-4-5`
+- **Google:** `gemini-3-flash`
+- **Local (Ollama):** `gemma3:4b`
+
+### Fixture Options
+
+You can pass options when creating the healing fixture:
+
+```typescript
+const test = base.extend<{ page: LocatAIPage }>(createLocatAIFixture({
+  maxCandidates: 30,  // Max DOM elements sent to AI (default: 30)
+  maxAiTries: 4,      // Max AI strategies to validate (default: 4)
+  timeout: 5000,      // Locator timeout in ms (default: 5000)
+  provider: 'openai', // AI provider (default: 'openai')
+  model: 'gpt-5.2',   // Override default model
+}));
+```
+
+### Token Optimization
+
+LocatAI is designed to minimize AI token consumption and keep costs low:
+
+- **Compact candidates** — Only non-null attributes are sent. Null/empty fields are stripped, and short keys are used (`tid` instead of `data-testid`, `txt` instead of `text`, etc.)
+- **Invisible elements filtered** — Hidden elements (`display: none`, `visibility: hidden`, zero-size) are excluded before sending to the AI
+- **Smart pre-filtering** — Before sending candidates to the AI, `rankCandidates()` scores each element by keyword match, tag-type inference, ARIA role relevance, and test-ID presence. Only the top-ranked candidates are sent, typically reducing the set by 20–30% while preserving accuracy
+- **Capped output** — The AI is asked to return a maximum of 3 strategies per request
+- **Configurable limit** — Control how many DOM elements are collected with `maxCandidates`
+
+Lower `maxCandidates` = fewer tokens = lower cost and faster responses. The default of 30 works well for most pages. For complex pages with many interactive elements, you can increase it:
+
+```typescript
+// Simple pages — fewer candidates, faster & cheaper
+createLocatAIFixture({ maxCandidates: 15 })
+
+// Complex pages — more candidates, better accuracy
+createLocatAIFixture({ maxCandidates: 50 })
+```
+
+### Token Usage Visibility
+
+Each healing call logs the token consumption reported by the AI provider:
+
+```
+↑ 1350 input · 180 output · 1530 total tokens
+```
+
+Token usage is also recorded in `.self-heal/heal_events.jsonl` for cost tracking and analysis across test runs.
+
+### Cache
+
+Healed selectors get cached in `.self-heal/`. Add it to your `.gitignore`:
+
+```
+.self-heal/
+```
+
+## How It Works
+
+1. Try the original locator
+2. If it fails, check the cache for a previously healed selector
+3. If not cached, send page context to the AI and ask it to find the element
+4. Cache the result for next time
+
+## Example
+
+```typescript
+import { test as base, expect } from '@playwright/test';
+import { createLocatAIFixture, LocatAIPage } from '@testnexus/locatai';
+
+const test = base.extend<{ page: LocatAIPage }>(createLocatAIFixture());
+
+test('checkout flow', async ({ page }) => {
+  await page.goto('/shop');
+  
+  // These might break when the UI changes, but LocatAI will adapt
+  await page.locatai.click(
+    page.locator('[data-testid="add-to-cart"]'),
+    'Add to cart button'
+  );
+  
+  await page.locatai.click(
+    page.locator('.cart-icon'),
+    'Shopping cart icon'
+  );
+  
+  await page.locatai.fill(
+    page.locator('#email'),
+    'Email field in checkout',
+    'customer@example.com'
+  );
+  
+  // No selector at all - just describe it
+  await page.locatai.click('', 'Place order button');
+});
+```
+
+## Live Demo
+
+Want to see LocatAI in action without touching your own project? Check out the **[`test-published`](https://github.com/Divyarajsinh-Dodia1617/LocatAi/tree/test-published)** branch — a standalone mini-project that imports the published npm package and runs tests with intentionally broken selectors.
+
+```bash
+git clone -b test-published https://github.com/Divyarajsinh-Dodia1617/LocatAi.git locatai-demo
+cd locatai-demo
+npm install && npx playwright install chromium
+cp example.env .env   # add your API key
+npm test
+```
+
+It includes two smoke tests:
+- **Broken locator** — uses a wrong selector (`#wrong-todo-input`), AI heals it to the real input
+- **AI-only mode** — no selector at all, AI finds the element from a plain-English description
+
+## Privacy & Security
+
+When healing is triggered, LocatAI sends a **DOM snapshot** of candidate elements (tag names, roles, aria labels, text content, test IDs, etc.) to the configured AI provider's API. **No screenshots or full page HTML are sent** — only a structured list of relevant elements.
+
+Keep this in mind if your application contains sensitive data in the DOM (e.g., PII, financial data, internal URLs). You can:
+- **Use a local LLM** with `AI_PROVIDER=local` — data never leaves your machine
+- Use a self-hosted or on-premise LLM by configuring a custom `AI_MODEL` and API endpoint
+- Limit healing to non-production environments
+- Review the candidate data sent via the `.self-heal/heal_events.jsonl` log
+
+### Local LLM with Ollama
+
+For maximum privacy and zero cost, run healing entirely on your machine with [Ollama](https://ollama.com):
+
+```bash
+# 1. Install Ollama (https://ollama.com) and pull a model
+ollama pull gemma3:4b
+
+# 2. Configure LocatAI
+export AI_PROVIDER=local
+export SELF_HEAL=1
+```
+
+That's it — no API keys, no cloud calls, no usage fees. Ollama runs the model locally and LocatAI talks to it directly.
+
+**Recommended models for healing** (sorted by size):
+
+| Model | Size | Context | Tested | Good for |
+|-------|------|---------|--------|----------|
+| `llama3.2:3b` ⭐ | 2.0 GB | 128K | 5/5 pass | Best overall choice — fast, accurate, and lightweight |
+| `mistral` ⭐ | 4.1 GB | 128K | 5/5 pass | Most accurate response, but slowest (~1.4 min per run) |
+| `gemma3:4b` | 3.3 GB | 128K | 4/5 pass | Faster than mistral (~53s), but slightly less accurate |
+
+> **Best results were achieved with `mistral`, `gemma3:4b`, and `llama3.2:3b`** — these three models consistently produced the most accurate healing across our test suite. `llama3.2:3b` stands out as the best overall choice, combining top accuracy with a small footprint. We recommend starting with one of them.
+
+> **Tip:** Small models (1B–4B) may struggle with ambiguous elements (e.g. multiple checkboxes on the same page). If accuracy matters more than speed, use `mistral` or a larger model.
+
+You can use **any model** from the [Ollama library](https://ollama.com/library) — just set `AI_MODEL`:
+
+```bash
+export AI_MODEL=llama3.2:3b   #or mistral, etc.
+```
+
+Custom Ollama host (e.g., running on another machine):
+
+```bash
+export OLLAMA_HOST=http://192.168.1.100:11434
+```
+
+## Development
+
+```bash
+npm install
+npm run build
+SELF_HEAL=1 npm test
+```
+
+## License
+
+MIT