tamash-playwright 0.9.0-beta.4 → 0.9.0

package/CHANGELOG.md

@@ -0,0 +1,132 @@
+# Changelog
+
+All notable changes to this project are documented here. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com/); dates are when each version was published.
+
+## [0.9.0] - 2026-08-26
+
+### Fixed
+
+- **Heal-log visibility**: a heal with no reusable selector (a one-shot `ref` resolution, or a
+  vision-tagged point) was silently dropped from `heals.jsonl` entirely, even though it genuinely
+  fixed that run. Now logged for audit — with a clear `reviewNote` — whenever it has a suggestion
+  *or* a review note, without letting an audit-only entry shadow an older, real cached fix for the
+  same location.
+- **Vision support for `claude-subscription`/`copilot-subscription`**: both providers had
+  `supportsVision` hardcoded to `false` regardless of model. Both SDKs genuinely support image
+  input (Claude Agent SDK via an image content block; Copilot SDK via a `blob` attachment) —
+  implemented for real and verified live with actual screenshots, not just doctor's yes/no label.
+- **Argument forwarding in healed replays**: `replayAction()` only ever forwarded the first call
+  argument. A trailing options object (`click({ modifiers: [...] })`, `fill(value, { timeout })`,
+  `dispatchEvent`'s 3rd argument) was silently dropped on a healed replay — changing the action's
+  real behavior while still reporting a clean `HEALED`.
+- **`ref`-strategy replays now act through the derived durable locator, not the raw ref**:
+  `aria-ref=` locators never resolve for `dispatchEvent` at all (a Playwright-level limitation,
+  confirmed directly via `DEBUG=pw:api`), even though the identical element resolves instantly via
+  a `normalize()`-derived locator for that same action. Fixed by deriving the durable locator
+  *before* replaying and acting through it, falling back to the raw ref only when nothing durable
+  could be found. A related accuracy bug is fixed alongside it: the report/heal-log could
+  previously claim a derived selector "worked" even when its own replay had actually failed and a
+  fallback silently took over — now only the locator that genuinely performed the action is
+  reported or cached.
+- **`copilot-subscription` could hang a non-Playwright test runner indefinitely** — its shared
+  client keeps a connection open across calls for performance, which Playwright's own test runner
+  tolerates by force-exiting regardless, but a runner like Cucumber does not, so the process never
+  returned even after every test had already passed. Found live running a real Cucumber suite in
+  CI. `closeCopilotSubscriptionClient()` is now exported from the package's own entry point so any
+  non-Playwright consumer can call it from their own teardown hook (e.g. Cucumber's `AfterAll`).
+
+### Added
+
+- **`locator.getDurable(action?)`** — resolves any locator (most usefully one built from
+  `aria-ref=...`) to a durable, reusable equivalent (`getByRole`/`getByLabel`/a css selector/…),
+  using the same derivation logic self-healing already uses internally. Throws if nothing durable
+  could be derived, rather than silently handing back something untrusted.
+- **`apply-heals` now previews before writing**: every run — dry or real — shows a styled table of
+  exactly what it found (location, before, after, review status) instead of a plain scrolling log.
+  A real run also asks for confirmation before writing anything, but *only* at a genuine
+  interactive terminal — CI and any non-interactive/piped invocation proceed automatically exactly
+  as before, so no existing unattended CI workflow is affected. `--yes`/`-y` skips the prompt at a
+  real terminal too.
+- **`doctor`'s output is styled** with colors and tables (including a new end-of-run Summary
+  section) instead of a plain scrolling log.
+- **Exact locator code in console lines and reports**: a healed suggestion is now shown as the
+  real, copy-pasteable Playwright call (`getByRole("textbox", { name: "Username" })`) instead of
+  an abbreviated shorthand (`role:textbox:Username`) — the same code `apply-heals` would write to
+  source, so what you see is never a lossier stand-in for what was actually used.
+- A canonical Page Object Model usage example (`tests/pages/` +
+  `tests/example-orangehrm-add-employee.spec.ts`), verified live against a real OrangeHRM demo,
+  including a genuine self-heal via the `near`/widening strategy on a real unlabeled field.
+
+### Changed
+
+- README/usage.md's vision-fallback documentation now correctly lists `claude-subscription`/
+  `copilot-subscription` as vision-capable (with a suitable model), not just the API-key providers.
+
+## [0.8.0] - 2026-08-25
+
+### Added
+
+- `claude-subscription` and `copilot-subscription` heal providers — self-healing backed by a
+  personal Claude or GitHub Copilot subscription instead of a pay-per-token API key, working both
+  locally and unattended in CI (`CLAUDE_CODE_OAUTH_TOKEN` for Claude; the ambient `GITHUB_TOKEN` or
+  a personal-account PAT for Copilot on GitHub Actions).
+
+### Fixed
+
+- Missing CLI install step in setup docs for `claude-subscription`/`copilot-subscription` — the
+  standalone `claude`/`copilot` CLIs are genuinely required for the login step even though the SDKs
+  don't need them installed to function at runtime.
+
+### Documentation
+
+- The org-vs-personal-account Copilot licensing gotcha in CI (a repo owned by an organization
+  without its own Copilot enablement can't use a personal subscription via the ambient token).
+- Action Recovery (`HEALER_ACTION_RECOVERY_ENABLED`) hidden from docs and `doctor` output —
+  disabled by default already; this only reduced its visibility, no behavior change.
+
+## [0.7.0] - 2026-08-21
+
+### Added
+
+- `apply-heals` — turns a runtime heal into a permanent source-code fix, plus an opportunistic
+  cache (`heals.jsonl`) so a previously-confirmed selector is tried before a fresh AI call, and
+  history archival so a run's report/log isn't silently overwritten by the next one.
+- Position/relationship-based locator strategies (`near`, `scoped`, `containing`) for elements with
+  no accessible identity of their own.
+- Self-healing rebuilt around `ariaSnapshot({ mode: 'ai' })` + `aria-ref=` resolution and
+  `Locator.normalize()`, replacing pixel-distance guessing for both the text path and the vision
+  fallback's durability upgrade.
+- A real unit test suite (32 tests at the time, zero new dependencies).
+
+### Fixed
+
+- `doctor`'s `actionTimeout` check being fooled by a commented-out config value.
+- `apply-heals --logs-dir` silently losing raw heal-log archival.
+- `apply-heals` only replacing the first call when re-healing an already-`near`-fixed line.
+- `apply-heals` `ENOENT` on a fresh CI checkout with no `.tamash-playwright/` directory yet — the
+  sharded "apply-heals" CI job checks out fresh and has never run tests itself, so the directory
+  genuinely doesn't exist there the way it always does in every local recipe.
+- File path corruption (and a `require()` crash in the generated verification script) for ESM
+  (`"type": "module"`) consumer projects — `Error.stack` renders as a `file://` URL there, which
+  broke path resolution and a plain `.js` verification script alike.
+- The AI being misled by the broken selector still present in its own prompt context; a failed
+  label guess now auto-upgrades to a structural `near` match instead of giving up.
+
+### Verified
+
+- All four API-key providers (Ollama, OpenAI, Anthropic, Gemini) confirmed working with real API
+  calls, not just documented.
+
+## [0.6.0] - 2026-08-17
+
+### Added
+
+- iframe and popup healing, vision fallback (screenshot-based recovery when text alone isn't
+  enough), AI-driven action recovery (scroll/force/wait/dispatch), and source-location reporting.
+- `doctor`'s `actionTimeout` configuration check.
+
+### Initial release
+
+- Self-healing Playwright bindings: broken locators are recovered at runtime via an AI provider,
+  with `.describe()` for human-readable context.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tamash-playwright",
-  "version": "0.9.0-beta.4",
+  "version": "0.9.0",
   "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",
@@ -11,6 +11,7 @@
     "dist",
     "README.md",
     "usage.md",
+    "CHANGELOG.md",
     ".env.example"
   ],
   "scripts": {