tamash-playwright 0.4.0 → 0.6.0

package/.env.example

@@ -6,6 +6,11 @@ HEALER_ENABLED=true
 # a failed action just fails normally, since there's no AI model configured to recover it.
 HEALER_PROVIDER=ollama
 
+# Optional, off by default. If a locator gets healed but the action on it still fails (e.g. the
+# element is covered or needs scrolling into view), the AI can pick a recovery tactic (scroll,
+# force, wait, or dispatch the DOM event directly) instead of giving up immediately.
+# HEALER_ACTION_RECOVERY_ENABLED=true
+
 # --- Ollama Cloud (https://ollama.com) ---
 OLLAMA_MODEL=gpt-oss:120b
 OLLAMA_API_KEY=

package/README.md

@@ -10,6 +10,8 @@ Websites change often. A button gets renamed or moved, and your test can't find
 
 `tamash-playwright` fixes this automatically. When a test can't find an element, it asks an AI model to find it on the current page and tries again. If it succeeds, your test keeps going. If not, it fails normally, just like before.
 
+**Want to see it working before you set it up yourself?** Clone the sample repo — [github.com/qtpsudhakarproducts/tamash-playwright-typescript-playwright](https://github.com/qtpsudhakarproducts/tamash-playwright-typescript-playwright) — a full worked example with both a plain-locator test and a Page Object Model test, an intentionally broken selector, and step-by-step setup instructions.
+
 Here are the detailed steps to use this package.
 
 ## Step 1: Install it
@@ -37,6 +39,9 @@ HEALER_ENABLED=true
 # Pick one: ollama | openai | anthropic | gemini
 HEALER_PROVIDER=ollama
 
+# Optional, off by default — see "Action recovery" below.
+# HEALER_ACTION_RECOVERY_ENABLED=true
+
 # --- Ollama Cloud (https://ollama.com) ---
 OLLAMA_MODEL=gpt-oss:120b
 OLLAMA_API_KEY=
@@ -74,7 +79,41 @@ OLLAMA_API_KEY=paste_your_key_here
 
 That's all you need — no other variables required.
 
-## Step 3: Use it in your tests
+### Important: set `actionTimeout` in your `playwright.config.ts`
+
+By default, Playwright lets a broken locator retry silently for your *entire* test timeout before it ever throws an error — which means self-healing never gets a turn at all, since it only kicks in once an action actually fails. Set `actionTimeout` to something well below your test timeout so a broken locator fails fast, leaving real time for healing to run:
+
+```ts
+export default defineConfig({
+  timeout: 60000, // your overall test timeout
+  use: {
+    actionTimeout: 8000, // must be comfortably less than the test timeout above
+  },
+});
+```
+
+Without this, healing attempts will show `stage=no_snapshot` in the console and never recover anything — not because healing failed, but because it never had time to run before the whole test was torn down.
+
+## Step 3: Check your setup
+
+Run the built-in doctor command to confirm everything's wired up correctly before you rely on it:
+
+```sh
+npx tamash-playwright doctor
+```
+
+It checks:
+
+1. **AI connectivity** — confirms `HEALER_ENABLED`/`HEALER_PROVIDER` are set correctly and actually calls your configured provider to make sure the API key and model work.
+2. **`actionTimeout` configuration** — checks your `playwright.config.ts` for an `actionTimeout` set well below your test `timeout` (see above); flags it if missing or too close to the test timeout, since that silently starves self-healing of any time to run.
+3. **Action recovery status** — whether `HEALER_ACTION_RECOVERY_ENABLED` is on (see below).
+4. **Vision capability** — whether your configured model is expected to support the screenshot-based fallback (see below), based on its name.
+5. **Missing `.describe()` labels** — scans your test files (`tests/` by default, or pass `--dir <path>`) for locators that don't have a `.describe('...')` label, and flags the ones most worth fixing (raw CSS/XPath selectors first).
+6. **Locators written directly in test files** — flags any locator defined inline in a test rather than inside a Page Object class, which is a Playwright best practice regardless of self-healing: it keeps tests readable and means a UI change only needs a fix in one place.
+
+If it finds issues, the fastest fix is to open the project in an AI coding assistant (Claude Code, Cursor, GitHub Copilot, etc.) and ask it to address what it flagged — add `.describe()` calls, or extract locators into Page Object classes. You can also add a standing rule to that assistant's instructions/skill file (e.g. `CLAUDE.md`, `.cursor/rules`, `.github/copilot-instructions.md`) so it follows both practices automatically on any new test code going forward.
+
+## Step 4: Use it in your tests
 
 Change one line at the top of your test file — everything else about how you write tests stays exactly the same:
 
@@ -129,6 +168,36 @@ test('login test using CSS Selectors', async ({ page }) => {
 
 This step is optional, but recommended — without it, the healer has to guess purely from a broken CSS selector, which gives it a lot less to work with.
 
+## What else it heals — no extra setup needed
+
+Beyond a single broken `click`/`fill`/`getByRole` on the main page, all of this works automatically once you've done Steps 1–2:
+
+- **Popups and extra tabs.** A page opened via `context.newPage()`, `window.open`, or a `target="_blank"` link is just as healing-aware as your main `page` — no manual wrapping needed.
+- **Elements inside `<iframe>`s.** `page.frameLocator('#my-iframe')` and anything chained off it heals the same way, scoped correctly to the iframe's own document.
+- **Most of the Playwright API surface**, not just clicks and fills — `check`, `selectOption`, `dragTo`, `dispatchEvent`, read methods like `textContent`/`getAttribute`/`isChecked`, `screenshot`, and more. Methods that can't be safely healed by guessing a replacement element (`dragTo`, `drop`) are still reported honestly on failure, they're just never silently retried with a different element.
+
+## When text alone isn't enough: vision fallback
+
+Sometimes an element has nothing useful to match on by text — an icon-only button with no label, or several visually distinct elements that all look identical in the accessibility tree. If your configured model supports image input (e.g. `gpt-4o`, `claude-haiku-4-5`, `gemini-2.0-flash`), `tamash-playwright` automatically falls back to a screenshot-based search after the normal text-based attempt fails — no separate setup, it just uses the same provider and API key from Step 2. Run `npx tamash-playwright doctor` to check whether your configured model is expected to support this.
+
+## Action recovery (optional)
+
+Occasionally a locator heals correctly — the AI found the right element — but the *action* on it still fails, e.g. it's covered by an overlay or needs scrolling into view first. Set `HEALER_ACTION_RECOVERY_ENABLED=true` to let the AI pick a recovery tactic from a fixed, safe set (scroll into view, retry bypassing actionability checks, wait briefly and retry, or dispatch the DOM event directly) before giving up. It's off by default since it's a second, more speculative layer of intervention beyond selector healing — the AI only ever picks from that fixed menu, it never decides how to interact with the page on its own.
+
+## Checking what actually happened
+
+Every healing attempt — whether it succeeded or not — shows up in Playwright's own HTML report (`npx playwright show-report`), no separate report to check:
+
+- An annotation on the test summarizing what happened, e.g. `Recovered using ollama:gpt-oss:120b (role:button:Submit)`.
+- A JSON attachment with the full detail: which provider was used, whether the vision or action-recovery fallback was involved, the AI's suggested selector, token cost, and — if it didn't heal — which stage it stopped at (e.g. `ai_declined`, `replay_failed`).
+- Exactly where in your own code the locator was created — a test file or a Page Object class, whichever it really is — so you know which line to go fix even if you never look at the healing report again.
+
+The same detail is also printed to the console as it happens, one line per attempt:
+
+```
+[self-healer] src/pages/loginpage.ts:11 — locator.fill "Username Textbox" -> HEALED [provider=ollama:gpt-oss:120b, vision=no, actionRecovery=no, suggested="role:textbox:Username", 620 tokens (489 input + 131 output)] — locator.fill: Timeout 8000ms exceeded.
+```
+
 ## License
 
 Free to use, including commercially. The source code may not be copied, modified, redistributed, or resold without prior written permission. See the LICENSE file included in this package for the full terms.

package/dist/bindings/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bindings/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,IAAI,EAAE,KAAK,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAGvE,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,EAAE,IAAI,CAAC;IAChB,UAAU,EAAE,KAAK,CAAC;CACnB,CAAC;AAEF,eAAO,MAAM,IAAI,0PAWf,CAAC;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bindings/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,IAAI,EAAE,KAAK,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAGvE,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,EAAE,IAAI,CAAC;IAChB,UAAU,EAAE,KAAK,CAAC;CACnB,CAAC;AAEF,eAAO,MAAM,IAAI,0PAcf,CAAC;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/bindings/index.js

@@ -4,6 +4,9 @@ exports.expect = exports.test = void 0;
 const test_1 = require("@playwright/test");
 const locator_binding_1 = require("./locator.binding");
 exports.test = test_1.test.extend({
+    context: async ({ context }, use) => {
+        await use((0, locator_binding_1.bindContext)(context));
+    },
     page: async ({ page }, use) => {
         await use((0, locator_binding_1.bindPageActions)(page));
     },

package/dist/bindings/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/bindings/index.ts"],"names":[],"mappings":";;;AAAA,2CAAuE;AACvE,uDAAsE;AAOzD,QAAA,IAAI,GAAG,WAAI,CAAC,MAAM,CAAkB;IAC/C,IAAI,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,EAAE;QAC5B,MAAM,GAAG,CAAC,IAAA,iCAAe,EAAC,IAAI,CAAC,CAAC,CAAC;IACnC,CAAC;IACD,SAAS,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,EAAE;QACjC,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC;IACD,UAAU,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,EAAE;QAClC,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;QAC/B,MAAM,GAAG,CAAC,IAAA,kCAAgB,EAAC,KAAK,CAAC,CAAC,CAAC;IACrC,CAAC;CACF,CAAC,CAAC;AAEH,yCAA0C;AAAjC,8FAAA,MAAM,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/bindings/index.ts"],"names":[],"mappings":";;;AAAA,2CAAuE;AACvE,uDAAmF;AAOtE,QAAA,IAAI,GAAG,WAAI,CAAC,MAAM,CAAkB;IAC/C,OAAO,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,EAAE;QAClC,MAAM,GAAG,CAAC,IAAA,6BAAW,EAAC,OAAO,CAAC,CAAC,CAAC;IAClC,CAAC;IACD,IAAI,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,EAAE;QAC5B,MAAM,GAAG,CAAC,IAAA,iCAAe,EAAC,IAAI,CAAC,CAAC,CAAC;IACnC,CAAC;IACD,SAAS,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,EAAE;QACjC,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC;IACD,UAAU,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,EAAE;QAClC,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;QAC/B,MAAM,GAAG,CAAC,IAAA,kCAAgB,EAAC,KAAK,CAAC,CAAC,CAAC;IACrC,CAAC;CACF,CAAC,CAAC;AAEH,yCAA0C;AAAjC,8FAAA,MAAM,OAAA"}

package/dist/bindings/locator.binding.d.ts

@@ -1,8 +1,9 @@
-import type { Frame, Locator, Page } from '@playwright/test';
-type BindingKind = 'locator' | 'page' | 'frame';
-export declare function bindTargetActions<T extends Locator | Page | Frame>(target: T, kind?: BindingKind, description?: string): T;
+import type { BrowserContext, Frame, FrameLocator, Locator, Page } from '@playwright/test';
+type BindingKind = 'locator' | 'page' | 'frame' | 'frameLocator';
+export declare function bindTargetActions<T extends Locator | Page | Frame | FrameLocator>(target: T, kind?: BindingKind, description?: string, frameScope?: FrameLocator, selector?: string, callSite?: Error): T;
 export declare function bindLocatorActions(locator: Locator): Locator;
 export declare function bindPageActions(page: Page): Page;
 export declare function bindFrameActions(frame: Frame): Frame;
+export declare function bindContext(context: BrowserContext): BrowserContext;
 export {};
 //# sourceMappingURL=locator.binding.d.ts.map

package/dist/bindings/locator.binding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"locator.binding.d.ts","sourceRoot":"","sources":["../../src/bindings/locator.binding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAsC7D,KAAK,WAAW,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;AA6BhD,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,OAAO,GAAG,IAAI,GAAG,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,GAAE,WAAuB,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,CAAC,CAwErI;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAE5D;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAEhD;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAEpD"}
+{"version":3,"file":"locator.binding.d.ts","sourceRoot":"","sources":["../../src/bindings/locator.binding.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AA2E3F,KAAK,WAAW,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,GAAG,cAAc,CAAC;AA8EjE,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,OAAO,GAAG,IAAI,GAAG,KAAK,GAAG,YAAY,EAC/E,MAAM,EAAE,CAAC,EACT,IAAI,GAAE,WAAuB,EAC7B,WAAW,CAAC,EAAE,MAAM,EAKpB,UAAU,CAAC,EAAE,YAAY,EAMzB,QAAQ,CAAC,EAAE,MAAM,EAKjB,QAAQ,CAAC,EAAE,KAAK,GACf,CAAC,CA2HH;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAE5D;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAEhD;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAEpD;AAYD,wBAAgB,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,cAAc,CAmCnE"}

package/dist/bindings/locator.binding.js

@@ -1,9 +1,14 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.bindTargetActions = bindTargetActions;
 exports.bindLocatorActions = bindLocatorActions;
 exports.bindPageActions = bindPageActions;
 exports.bindFrameActions = bindFrameActions;
+exports.bindContext = bindContext;
+const path_1 = __importDefault(require("path"));
 const healer_1 = require("../healer");
 const ACTIONS = [
     'click',
@@ -18,8 +23,40 @@ const ACTIONS = [
     'selectOption',
     'setInputFiles',
     'dragTo',
+    // `drop` validates its `{files, data}` payload *before* ever touching the locator (confirmed:
+    // an empty payload throws "At least one of files or data must be provided" instantly, with no
+    // "Timeout ... exceeded" resolving-the-locator phase at all), so like `dragTo` it's caught and
+    // reported here but excluded from replayAction — a two-sided drag/drop pairing can't be safely
+    // healed by guessing a substitute locator for just one side of it.
+    'drop',
     'focus',
     'blur',
+    'type',
+    'pressSequentially',
+    'setChecked',
+    'scrollIntoViewIfNeeded',
+    'dispatchEvent',
+    'waitFor',
+    // Read methods below don't act on the page — they raise when the locator can't be resolved
+    // (confirmed empirically: they throw the same "Timeout ... exceeded" shape as click/fill do
+    // against a zero-match locator), so a broken selector here is just as healable as a broken
+    // selector on a click. `isVisible`/`isHidden`/`count`/`all`/`allInnerTexts`/`allTextContents`
+    // are deliberately excluded — confirmed they degrade gracefully (false/0/[]) instead of
+    // throwing, so there's no exception here for the healer to ever catch.
+    'textContent',
+    'innerText',
+    'innerHTML',
+    'getAttribute',
+    'inputValue',
+    'isChecked',
+    'isEnabled',
+    'isDisabled',
+    'isEditable',
+    'selectText',
+    'screenshot',
+    'boundingBox',
+    'elementHandle',
+    'ariaSnapshot',
 ];
 const LOCATOR_FACTORY_METHODS = [
     'locator',
@@ -31,6 +68,10 @@ const LOCATOR_FACTORY_METHODS = [
     'getByTitle',
     'getByTestId',
 ];
+// Handled separately from LOCATOR_FACTORY_METHODS: frameLocator() returns a FrameLocator, not a
+// Locator, so it needs its own BindingKind and its own frameScope propagation (see below) rather
+// than being folded into the generic factory-method branch.
+const FRAME_LOCATOR_METHOD = 'frameLocator';
 // Methods that return a *new* Locator derived from the current one. Playwright's own
 // implementations are immutable (they don't mutate `target`), so if we don't intercept these
 // and re-wrap the result, the returned Locator silently loses its healing Proxy. This mattered
@@ -58,23 +99,111 @@ function describeFactoryCall(prop, args) {
             return `testid "${String(first)}"`;
         case 'locator':
             return `selector "${String(first)}"`;
+        case 'frameLocator':
+            return `iframe "${String(first)}"`;
         default:
             return undefined;
     }
 }
-function bindTargetActions(target, kind = 'locator', description) {
-    return new Proxy(target, {
+// Resolves the real, human-meaningful call site of a locator — the line in the consumer's own
+// test file or Page Object that actually wrote `.locator(...)`/`.getByRole(...)`/etc. — from an
+// Error captured at that exact call. Only ever invoked on a genuine failure (see the ACTIONS
+// branch below), never on every locator creation: constructing an Error is cheap, but reading
+// `.stack` is not (V8 computes it lazily on first access), so this cost is deliberately deferred
+// until it's actually needed.
+//
+// Filters by checking whether a frame's file path contains "locator.binding" rather than an exact
+// path/`__filename` comparison — verified empirically that this matters: Node resolves stack
+// frames through this package's own source maps, so a frame belonging to this file shows up as
+// `.../src/bindings/locator.binding.ts` in the formatted stack string even when the code actually
+// executing is the compiled `dist/bindings/locator.binding.js` — an exact `__filename` compare
+// would silently never match and filter nothing out.
+function resolveCallerLocation(callSite) {
+    const stack = callSite.stack;
+    if (!stack) {
+        return undefined;
+    }
+    for (const line of stack.split('\n')) {
+        if (line.includes('locator.binding')) {
+            continue;
+        }
+        const match = line.match(/^\s*at\s+(?:.*\s+\()?(.+):(\d+):(\d+)\)?\s*$/);
+        if (!match) {
+            continue;
+        }
+        const [, filePath, lineNumber] = match;
+        return `${path_1.default.relative(process.cwd(), filePath)}:${lineNumber}`;
+    }
+    return undefined;
+}
+// Marks every proxy this module creates so a target that's already wrapped is never wrapped
+// again. This matters concretely for the primary test `page`: Playwright's own built-in `page`
+// fixture is implemented as `context.newPage()`, and since bindContext() (below) already wraps
+// whatever newPage() returns, the fixture override in bindings/index.ts receives an
+// already-wrapped page as its `page` dependency. Without this check, wrapping it a second time
+// would nest two independent healing layers around the same actions — every failed action would
+// then be caught and reported twice (the inner layer reports, rethrows; the outer layer catches
+// that rethrow and reports again), even though only one real action ever ran. Keying by the
+// object actually passed in (rather than tracking raw targets) is what makes this work: the
+// second call receives the *proxy* from the first call, not the original raw object, so a
+// raw-object cache would miss it.
+const knownProxies = new WeakSet();
+function bindTargetActions(target, kind = 'locator', description, 
+// The owning FrameLocator, when `target` (or anything derived from it via chaining/factory
+// calls) lives inside an <iframe> — threaded through to healActionFailure so the healer
+// snapshots and rebuilds a replacement locator *inside that iframe*, not the outer page where
+// the element doesn't exist. ariaSnapshot() never descends into iframes on its own.
+frameScope, 
+// The selector text captured once at the factory call (e.g. `selector "#foo"`), tracked
+// independently of `description` so a later `.describe("Submit button")` overrides only the
+// human-readable label without erasing what the original selector actually was — both are worth
+// showing the AI/report, since "Submit button (selector \"#foo\")" is more useful for debugging
+// a bad selector than either alone.
+selector, 
+// An Error captured at the factory call that created this Locator — its birthplace, not
+// wherever it's later chained/acted on. Threaded through exactly like `selector`: freshly
+// captured on every factory call, propagated unchanged through CHAIN_METHODS. Only ever turned
+// into an actual file:line (via resolveCallerLocation) on a genuine failure, not eagerly here.
+callSite) {
+    if (knownProxies.has(target)) {
+        return target;
+    }
+    const proxy = new Proxy(target, {
         get(target, prop, receiver) {
             if (typeof prop === 'string') {
                 const targetObject = target;
-                if (kind !== 'locator' && LOCATOR_FACTORY_METHODS.includes(prop)) {
+                if (prop === FRAME_LOCATOR_METHOD) {
+                    return (...args) => {
+                        const factory = targetObject[prop];
+                        if (typeof factory !== 'function') {
+                            throw new Error(`frameLocator() is not available on this ${kind}.`);
+                        }
+                        const childFrameLocator = factory.apply(target, args);
+                        const frameSelector = describeFactoryCall(prop, args);
+                        // The FrameLocator itself becomes the frameScope for everything resolved through it.
+                        return bindTargetActions(childFrameLocator, 'frameLocator', frameSelector, childFrameLocator, frameSelector);
+                    };
+                }
+                // Previously gated on `kind !== 'locator'`, which meant chaining a factory method off an
+                // already-obtained Locator (e.g. `container.getByRole('button')`, a common pattern for
+                // scoping a search) silently returned a raw, unwrapped Locator with no healing at all.
+                // Locator/Page/Frame/FrameLocator all expose these methods, so there's no kind this
+                // should be excluded for.
+                if (LOCATOR_FACTORY_METHODS.includes(prop)) {
                     return (...args) => {
                         const factory = targetObject[prop];
                         if (typeof factory !== 'function') {
                             throw new Error(`The locator factory "${String(prop)}" is not available on this ${kind}.`);
                         }
                         const locator = factory.apply(target, args);
-                        return bindTargetActions(locator, 'locator', describeFactoryCall(prop, args));
+                        const newSelector = describeFactoryCall(prop, args);
+                        // Captured fresh at every factory call, same as newSelector — this call is this
+                        // Locator's birthplace, regardless of where `target` itself came from.
+                        const newCallSite = new Error();
+                        // description starts out equal to the selector text (nothing else to show yet); a
+                        // later `.describe()` call overrides description independently, without touching
+                        // `newSelector` — see the CHAIN_METHODS branch below.
+                        return bindTargetActions(locator, 'locator', newSelector, frameScope, newSelector, newCallSite);
                     };
                 }
                 if (kind === 'locator' && CHAIN_METHODS.includes(prop)) {
@@ -85,7 +214,11 @@ function bindTargetActions(target, kind = 'locator', description) {
                         }
                         const result = chainMethod.apply(target, args);
                         const nextDescription = prop === 'describe' ? String(args[0] ?? '') : description;
-                        return bindTargetActions(result, 'locator', nextDescription);
+                        // `selector` and `callSite` are deliberately NOT touched here, for any chain method
+                        // including `describe()` — they always stay the original factory-call selector/site,
+                        // so a human description added later doesn't erase where this Locator actually came
+                        // from.
+                        return bindTargetActions(result, 'locator', nextDescription, frameScope, selector, callSite);
                     };
                 }
                 if (ACTIONS.includes(prop)) {
@@ -104,13 +237,27 @@ function bindTargetActions(target, kind = 'locator', description) {
                             return await target[prop](...callArgs);
                         }
                         catch (error) {
+                            // description defaults to the selector text at the factory call, so the two are
+                            // identical until `.describe()` overrides description — only combine them once
+                            // they've actually diverged, so a plain (never-described) locator still reports a
+                            // single clean "selector \"#foo\"" instead of a redundant "selector \"#foo\"
+                            // (selector \"#foo\")".
+                            const effectiveDescription = description && selector && description !== selector
+                                ? `${description} (${selector})`
+                                : (description ?? selector ?? `${kind} action ${String(prop)}`);
                             const healing = await (0, healer_1.healActionFailure)({
                                 action: String(prop),
                                 kind,
-                                description: description ?? `${kind} action ${String(prop)}`,
+                                description: effectiveDescription,
                                 error,
-                                target,
+                                // FrameLocator never reaches this branch (it has no ACTIONS methods, only the
+                                // locator-factory ones handled above), so this narrowing is safe.
+                                target: target,
                                 callArgs,
+                                frameScope,
+                                // Only resolved now, on a genuine failure — not at every locator creation. See
+                                // resolveCallerLocation's own comment for why.
+                                sourceLocation: callSite ? resolveCallerLocation(callSite) : undefined,
                             });
                             // NOTE: most Playwright actions (click/fill/check/hover/...) resolve to `undefined`
                             // on success, so `healing.recovered` alone is the correct success signal here —
@@ -128,6 +275,8 @@ function bindTargetActions(target, kind = 'locator', description) {
             return typeof value === 'function' ? value.bind(target) : value;
         },
     });
+    knownProxies.add(proxy);
+    return proxy;
 }
 function bindLocatorActions(locator) {
     return bindTargetActions(locator, 'locator');
@@ -138,4 +287,45 @@ function bindPageActions(page) {
 function bindFrameActions(frame) {
     return bindTargetActions(frame, 'frame');
 }
+// A second/third page (a popup, a manually-opened tab, target="_blank" navigation) is just as
+// much "what the test did" as the primary page — but unlike Python's monkey-patching approach
+// (where mutating the real instance means every reference to it sees the patch, however it was
+// obtained), a Proxy only affects code that actually holds a reference to *that* Proxy. Passively
+// listening via `context.on('page', ...)` and discarding the result would never reach the test:
+// `const popup = await context.newPage()` returns Playwright's own raw object directly, bypassing
+// any side-effecting listener entirely. So this wraps the *methods that hand pages back to the
+// caller* instead — newPage(), pages(), and on('page'/'popup', handler) (rewriting the handler so
+// whatever it's called with is the wrapped page, not the raw one) — which is what actually gets
+// the healing-aware Proxy into the test's hands regardless of how it obtained the new page.
+function bindContext(context) {
+    if (knownProxies.has(context)) {
+        return context;
+    }
+    const proxy = new Proxy(context, {
+        get(target, prop, receiver) {
+            if (prop === 'newPage') {
+                return async (...args) => {
+                    const page = await target.newPage(...args);
+                    return bindPageActions(page);
+                };
+            }
+            if (prop === 'pages') {
+                return () => target.pages().map((page) => bindPageActions(page));
+            }
+            if (prop === 'on' || prop === 'once') {
+                return (event, handler) => {
+                    if (event === 'page' || event === 'popup') {
+                        const wrappedHandler = (page) => handler(bindPageActions(page));
+                        return target[prop](event, wrappedHandler);
+                    }
+                    return target[prop](event, handler);
+                };
+            }
+            const value = Reflect.get(target, prop, receiver);
+            return typeof value === 'function' ? value.bind(target) : value;
+        },
+    });
+    knownProxies.add(proxy);
+    return proxy;
+}
 //# sourceMappingURL=locator.binding.js.map

package/dist/bindings/locator.binding.js.map

@@ -1 +1 @@
-{"version":3,"file":"locator.binding.js","sourceRoot":"","sources":["../../src/bindings/locator.binding.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"locator.binding.js","sourceRoot":"","sources":["../../src/bindings/locator.binding.ts"],"names":[],"mappings":"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"}

package/dist/cli/doctor.d.ts

@@ -0,0 +1,2 @@
+export declare function runDoctor(args?: string[]): Promise<void>;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/cli/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/cli/doctor.ts"],"names":[],"mappings":"AAqJA,wBAAsB,SAAS,CAAC,IAAI,GAAE,MAAM,EAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBlE"}

package/dist/cli/doctor.js

@@ -0,0 +1,154 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDoctor = runDoctor;
+const path_1 = __importDefault(require("path"));
+const dotenv_1 = __importDefault(require("dotenv"));
+const providers_1 = require("../healer/providers");
+const healer_1 = require("../healer");
+const scanDescribe_1 = require("./scanDescribe");
+const scanActionTimeout_1 = require("./scanActionTimeout");
+dotenv_1.default.config({ path: path_1.default.resolve(process.cwd(), '.env') });
+const CONNECTIVITY_TIMEOUT_MS = 15000;
+const CONNECTIVITY_SNAPSHOT = '- generic "tamash-playwright doctor check":\n  - button "OK"';
+async function checkProviderConnectivity() {
+    console.log(`HEALER_ENABLED: ${process.env.HEALER_ENABLED ?? '(unset — defaults to true)'}`);
+    if (!(0, healer_1.isHealingEnabled)()) {
+        console.log('  Healing is currently OFF. Set HEALER_ENABLED=true (or remove the line) to turn it back on.');
+        return;
+    }
+    console.log(`HEALER_ACTION_RECOVERY_ENABLED: ${process.env.HEALER_ACTION_RECOVERY_ENABLED ?? '(unset — defaults to false)'}`);
+    if ((0, healer_1.isActionRecoveryEnabled)()) {
+        console.log('  Action recovery is ON — if a locator heals but the action on it still fails, the AI may retry');
+        console.log('  it (scroll into view, force, wait, or dispatch the DOM event directly) before giving up.');
+    }
+    else {
+        console.log('  Action recovery is OFF (opt-in, off by default). Set HEALER_ACTION_RECOVERY_ENABLED=true to turn it on.');
+    }
+    console.log('');
+    const providerName = process.env.HEALER_PROVIDER;
+    if (!providerName) {
+        console.log('[WARN] HEALER_PROVIDER is not set. No AI provider is configured, so self-healing will never');
+        console.log('       recover a failed action — it will just fail normally.');
+        console.log('       Set HEALER_PROVIDER (ollama | openai | anthropic | gemini) plus its API key/model in .env.');
+        return;
+    }
+    const provider = (0, providers_1.getHealProvider)();
+    if (!provider) {
+        console.log(`[FAIL] HEALER_PROVIDER=${providerName}, but its required model/API key env vars are missing.`);
+        console.log('       Check the matching section for it in your .env file.');
+        return;
+    }
+    // Based on a model-name heuristic (see providers/vision-models.ts), not a live check — kept
+    // that way deliberately so `doctor` doesn't spend an extra API call confirming something the
+    // name pattern already answers; if the heuristic is ever wrong for a given model, that surfaces
+    // the first time healing actually needs the vision fallback, not here.
+    if (provider.supportsVision) {
+        console.log(`Vision-capable model: yes — ${provider.name} may be used for the screenshot-based fallback when text-based healing fails.`);
+    }
+    else {
+        console.log(`Vision-capable model: no — ${provider.name} does not look vision-capable by name, so the screenshot-based fallback will never be attempted.`);
+    }
+    console.log(`Testing connectivity to ${provider.name}...`);
+    const result = await provider.suggestSelector({
+        action: 'click',
+        description: 'tamash-playwright doctor connectivity check',
+        ariaSnapshot: CONNECTIVITY_SNAPSHOT,
+        timeoutMs: CONNECTIVITY_TIMEOUT_MS,
+    });
+    if (result) {
+        console.log(`[OK] Connected to ${provider.name} successfully.`);
+    }
+    else {
+        console.log(`[FAIL] Could not get a valid response from ${provider.name}.`);
+        console.log('       Check the warning above (if any), your API key, model name, and network connection.');
+    }
+}
+function checkDescribeUsage(occurrences) {
+    const missingDescribe = occurrences.filter((o) => !o.hasDescribe);
+    if (missingDescribe.length === 0) {
+        console.log('[OK] No locators found without a .describe() label.');
+        return;
+    }
+    console.log(`[WARN] Found ${missingDescribe.length} locator(s) without .describe():\n`);
+    for (const finding of missingDescribe) {
+        const tag = finding.priority === 'high' ? '[HIGH]' : '[LOW] ';
+        const relativeFile = path_1.default.relative(process.cwd(), finding.file);
+        console.log(`  ${tag} ${relativeFile}:${finding.line}  ${finding.snippet}`);
+    }
+    console.log('');
+    console.log('Recommendation: add .describe(\'...\') to these locators — especially the [HIGH] ones (raw CSS/XPath');
+    console.log('selectors), since those give the self-healer the least to go on if they break. Example:');
+    console.log('');
+    console.log('  page.locator(\'input[name="username"]\').describe(\'Username Textbox\')');
+    console.log('');
+    console.log('Fastest way to fix these: open this project in an AI coding assistant (Claude Code, Cursor, GitHub');
+    console.log('Copilot, etc.) and ask it to add .describe() to the locators flagged above.');
+    console.log('');
+    console.log('To make this automatic going forward, add a standing rule to your AI IDE\'s instructions/skill file');
+    console.log('(e.g. CLAUDE.md, .cursor/rules, .github/copilot-instructions.md) along the lines of:');
+    console.log('  "Whenever creating or editing a Playwright locator, chain .describe(\'...\') onto it with a short,');
+    console.log('   human-readable label of what the element is."');
+}
+// Any locator this scan finds lives in a *.spec.ts/*.test.ts file by construction (that's the
+// glob it scans), which means it's written directly into the test rather than inside a Page
+// Object — hence this fires whenever there's at least one occurrence, regardless of .describe().
+function checkPageObjectUsage(occurrences) {
+    if (occurrences.length === 0) {
+        return;
+    }
+    const fileCount = new Set(occurrences.map((o) => o.file)).size;
+    console.log('');
+    console.log(`[INFO] Found ${occurrences.length} locator(s) defined directly inside ${fileCount} test file(s).`);
+    console.log('       Best practice: don\'t write locators straight into your tests — move them into Page Object');
+    console.log('       classes instead (e.g. a pages/LoginPage.ts with a login() method that internally holds the');
+    console.log('       page.locator(...) calls). Tests then call page-object methods, not raw locators. This keeps');
+    console.log('       tests readable and means a UI change only needs a fix in one place.');
+}
+function checkActionTimeoutSetup() {
+    const result = (0, scanActionTimeout_1.checkActionTimeout)();
+    switch (result.status) {
+        case 'no_config':
+            console.log('[INFO] Could not find a playwright.config.(ts|js|mjs|cjs) in the current directory to check.');
+            console.log('       Make sure `actionTimeout` (inside `use: {...}`) is set well below your test `timeout` —');
+            console.log('       without it, a broken locator can retry silently for the entire test timeout, leaving no');
+            console.log('       time for self-healing to run at all.');
+            return;
+        case 'not_set':
+            console.log(`[WARN] No \`actionTimeout\` found in ${result.configFile}.`);
+            console.log('       Without it, Playwright lets a broken locator retry for your whole test timeout before');
+            console.log('       ever throwing — self-healing never gets a turn. Add this to your `use: {...}` block:');
+            console.log('         actionTimeout: 8000, // comfortably less than your test timeout');
+            return;
+        case 'too_close':
+            console.log(`[WARN] ${result.configFile} sets actionTimeout: ${result.actionTimeout} >= timeout: ${result.testTimeout}.`);
+            console.log('       actionTimeout must be well below the overall test timeout, or self-healing still won\'t');
+            console.log('       have any time left to run once an action fails.');
+            return;
+        case 'ok':
+            console.log(`[OK] ${result.configFile} sets actionTimeout: ${result.actionTimeout}ms — self-healing has room to run.`);
+            return;
+    }
+}
+function parseTestDir(args) {
+    const flagIndex = args.indexOf('--dir');
+    const value = flagIndex !== -1 ? args[flagIndex + 1] : undefined;
+    return path_1.default.resolve(process.cwd(), value ?? 'tests');
+}
+async function runDoctor(args = []) {
+    console.log('tamash-playwright doctor\n');
+    await checkProviderConnectivity();
+    console.log('');
+    checkActionTimeoutSetup();
+    console.log('');
+    const testDir = parseTestDir(args);
+    const relativeDir = path_1.default.relative(process.cwd(), testDir) || testDir;
+    console.log(`Scanning ${relativeDir} for locators...`);
+    console.log('(static text scan, not a real parser — review these before acting on them)\n');
+    const occurrences = (0, scanDescribe_1.scanTestDirectory)(testDir);
+    checkDescribeUsage(occurrences);
+    checkPageObjectUsage(occurrences);
+}
+//# sourceMappingURL=doctor.js.map