tamash-playwright 0.13.0-beta.1 → 0.13.0-beta.2

package/CHANGELOG.md

@@ -9,6 +9,10 @@ All notable changes to this project are documented here. Format loosely follows
 
 - **A context/page built off `browser` in `test.beforeAll` (shared across tests) was never healing-aware.** Only the `context`/`page` fixtures were wrapped with the healing proxy — a consumer using `test.beforeAll(async ({ browser }) => { context = await browser.newContext(); page = await context.newPage(); })` to log in once and reuse the session across every test in a file bypassed both, so nothing built that way ever healed. Found via a real support report. Fixed: the `browser` fixture is now wrapped too (`bindBrowser()`, `src/bindings/locator.binding.ts`) — `browser.newContext()`, `browser.newPage()`, and `browser.contexts()` all now hand back healing-aware objects, exactly like `context.newPage()` already did. Doesn't cover a browser obtained entirely outside the fixture system (e.g. `chromium.launch()` in `globalSetup`) — see "What else it heals" in README.md/usage.md for the manual `bindContext()`/`bindPageActions()` escape hatch for that case.
 
+### Docs
+
+- **README.md/usage.md/feature.md now lead with the actual rule, not just examples of it.** The `browser`-in-`beforeAll` fix above was documented as a bullet point alongside popups/iframes, which left the real boundary implicit: *any* browser/context/page from Playwright's own fixtures heals automatically, however many hops away and however it's reused, while anything built outside the fixture system (`chromium.launch()` directly, or `globalSetup`) still needs manual `bindContext()`/`bindPageActions()`. Now stated as the first thing in "What else it heals," not inferred from bullets.
+
 ## [0.12.0] - 2026-09-13
 
 ### Added

package/README.md

@@ -331,10 +331,12 @@ Everything below applies identically in both places — same package, same behav
 
 ## What else it heals — no extra setup needed
 
+**The rule that decides all of this**: if `browser`, `context`, or `page` came from Playwright's own fixtures — destructured from a test/`beforeAll`/`beforeEach` callback, e.g. `test('...', async ({ browser }) => {...})` — then everything built from it heals automatically, no matter how many hops away: `browser.newContext()` → `.newPage()`, stashed in a variable, reused across other tests, with `storageState`, whatever. If it *didn't* come from a fixture — a browser launched directly with `chromium.launch()`, or anything built inside `globalSetup` — it needs manual wrapping; see [If you build a context/page outside the fixture system entirely](#if-you-build-a-contextpage-outside-the-fixture-system-entirely) below.
+
 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.
-- **A context/page built from `browser` in `test.beforeAll`.** The common "log in once, reuse the session across every test in the file" pattern — `test.beforeAll(async ({ browser }) => { context = await browser.newContext(); page = await context.newPage(); })` — heals too, as long as `browser` itself came from the test fixtures (destructured from the callback, not imported separately). See [If you build a context/page outside the fixture system entirely](#if-you-build-a-contextpage-outside-the-fixture-system-entirely) for the one case this doesn't cover.
+- **A context/page built from `browser` in `test.beforeAll`.** The common "log in once, reuse the session across every test in the file" pattern — `test.beforeAll(async ({ browser }) => { context = await browser.newContext(); page = await context.newPage(); })` — heals too, per the rule above.
 - **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. Playwright 1.63's no-argument `page.frameLocator()` ("match in any frame") also heals when the page has a single frame; on a page with several frames it can't be told which one you meant, so healing steps aside cleanly (no wrong-frame guess) — pass an explicit `frameLocator('#id')` there.
 - **Most of the Playwright API surface**, not just clicks and fills — `check`, `selectOption`, `dragTo`, `dispatchEvent`, read methods like `textContent`/`getAttribute`/`isChecked`, `screenshot`, and more. A few are deliberately excluded, but still reported honestly on failure rather than silently retried: `dragTo`/`drop` can't be safely healed by guessing a replacement element for just one side of a two-sided drag, and `waitFor` is a state check rather than an action — a timeout on it can mean a genuinely broken selector, or that the element correctly never reached the expected state (verifying something does *not* appear, say), which can't be told apart from the error alone. (`expect(locator).toBeVisible()` and similar assertions are excluded for the same reason, but never even reach this mechanism — they're Playwright's own matcher, not a method this wraps.)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tamash-playwright",
-  "version": "0.13.0-beta.1",
+  "version": "0.13.0-beta.2",
   "description": "Plug and Play Self-healing for Playwright and automatically recovers broken selectors using an AI model (Ollama, OpenAI, Anthropic, Gemini, or a Claude/GitHub Copilot subscription).",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/usage.md

@@ -193,8 +193,10 @@ Everything below applies identically in both places — same package, same behav
 
 ## What else it heals — no extra setup
 
+**The rule that decides all of this**: if `browser`, `context`, or `page` came from Playwright's own fixtures — destructured from a test/`beforeAll`/`beforeEach` callback, e.g. `test('...', async ({ browser }) => {...})` — then everything built from it heals automatically, no matter how many hops away: `browser.newContext()` → `.newPage()`, stashed in a variable, reused across other tests, with `storageState`, whatever. If it *didn't* come from a fixture — a browser launched directly with `chromium.launch()`, or anything built inside `globalSetup` — it needs manual wrapping; see [If you build a context/page outside the fixture system entirely](#if-you-build-a-contextpage-outside-the-fixture-system-entirely) below.
+
 - **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`.
-- **A context/page built from `browser` in `test.beforeAll`.** The common "log in once, reuse the session across every test in the file" pattern — `test.beforeAll(async ({ browser }) => { context = await browser.newContext(); page = await context.newPage(); })` — heals too, as long as `browser` itself came from the test fixtures. See [If you build a context/page outside the fixture system entirely](#if-you-build-a-contextpage-outside-the-fixture-system-entirely) for the one case this doesn't cover.
+- **A context/page built from `browser` in `test.beforeAll`.** The common "log in once, reuse the session across every test in the file" pattern — `test.beforeAll(async ({ browser }) => { context = await browser.newContext(); page = await context.newPage(); })` — heals too, per the rule above.
 - **Elements inside `<iframe>`s.** `page.frameLocator('#my-iframe')` and anything chained off it heals the same way, correctly scoped to the iframe's own document. Playwright 1.63's no-argument `page.frameLocator()` ("match in any frame") also heals on a single-frame page; when several frames are present the healer can't tell which was meant and steps aside cleanly rather than guess — use an explicit `frameLocator('#id')` in that case.
 - **Most of the Playwright API surface**, not just clicks and fills — `check`, `selectOption`, `dragTo`, `dispatchEvent`, read methods like `textContent`/`getAttribute`/`isChecked`, `screenshot`, and more. `dragTo`, `drop`, and `waitFor` are reported honestly on failure rather than guessed at — the first two because a two-sided drag can't be safely fixed by guessing one side, `waitFor` because a timeout on it can be a correct test outcome (e.g. verifying an absence), not a broken selector. `expect(locator).toBeVisible()` and similar assertions are excluded the same way, but never reach this mechanism at all — they're Playwright's own matcher, not a method this wraps.