tamash-playwright 0.1.0__tar.gz

tamash_playwright-0.1.0/.env.example

@@ -0,0 +1,26 @@
+# Master on/off switch for self-healing. Unset or anything other than false/0 leaves it on.
+HEALER_ENABLED=true
+
+# Which AI provider backs self-healing: ollama | openai | anthropic | gemini
+# Unset, unknown, or a provider whose key/model below is missing disables self-healing —
+# a failed action just fails normally, since there's no AI model configured to recover it.
+HEALER_PROVIDER=ollama
+
+# --- Ollama Cloud (https://ollama.com) ---
+OLLAMA_MODEL=gpt-oss:120b
+OLLAMA_API_KEY=
+# OLLAMA_BASE_URL=https://ollama.com
+
+# --- OpenAI ---
+# OPENAI_MODEL=gpt-4.1-mini
+# OPENAI_API_KEY=
+# OPENAI_BASE_URL=https://api.openai.com/v1
+
+# --- Anthropic (requires: pip install tamash-playwright[anthropic]) ---
+# ANTHROPIC_MODEL=claude-haiku-4-5
+# ANTHROPIC_API_KEY=
+
+# --- Google Gemini ---
+# GEMINI_MODEL=  # check https://ai.google.dev/gemini-api/docs/models for the current model id
+# GEMINI_API_KEY=
+# GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai

tamash_playwright-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.env
+test-results/
+playwright-report/

tamash_playwright-0.1.0/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) 2026 QtpSudhakar / VibeTestQ
+
+All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to use
+the Software for any purpose, including commercial use, subject to the
+following conditions:
+
+1. The Software may not be copied, modified, merged, published, distributed,
+   sublicensed, or sold, in whole or in part, without prior written
+   permission from the copyright holder.
+
+2. The above copyright notice and this permission notice shall be included
+   in all copies of the Software that are permitted under these terms.
+
+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.
+
+For questions or concerns, contact us at support@vibetestq.com.

tamash_playwright-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.5
+Name: tamash-playwright
+Version: 0.1.0
+Summary: Self-healing bindings for Playwright + pytest: automatically recovers broken selectors using an AI model (Ollama, OpenAI, Anthropic, or Gemini).
+Project-URL: Homepage, https://github.com/qtpsudhakarproducts/tamash-playwright-python
+Project-URL: Repository, https://github.com/qtpsudhakarproducts/tamash-playwright-python
+Project-URL: License, https://github.com/qtpsudhakarproducts/tamash-playwright-python/blob/main/LICENSE
+Author: QtpSudhakar / VibeTestQ
+License: SEE LICENSE IN LICENSE
+License-File: LICENSE
+Keywords: anthropic,gemini,llm,ollama,openai,playwright,pytest,self-healing,test-automation
+Requires-Python: >=3.9
+Requires-Dist: pytest-playwright>=0.4.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.115.0; extra == 'anthropic'
+Description-Content-Type: text/markdown
+
+# tamash-playwright
+
+`tamash-playwright` is a plug and play self-healing solution for Playwright + pytest. Install it, add your AI API key details, and wire in one fixture override.
+
+That's it. No changes needed to your actual test functions if you're following standard Playwright/pytest best practices.
+
+> Also available for TypeScript/`@playwright/test` as [`tamash-playwright` on npm](https://www.npmjs.com/package/tamash-playwright) — same name, same idea, separate package per ecosystem.
+
+### Why you need this
+
+Websites change often. A button gets renamed or moved, and your test can't find it anymore — even though the app still works fine for real users. Normally, that just means a broken test.
+
+`tamash-playwright` fixes this automatically. When a test action 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.
+
+Here are the detailed steps to use this package.
+
+## Step 1: Install it
+
+```sh
+pip install tamash-playwright
+```
+
+This pulls in `pytest-playwright` as a dependency, so if you're starting fresh you'll also need the Playwright browsers:
+
+```sh
+playwright install
+```
+
+Using Anthropic (Claude) as your provider needs one extra install:
+
+```sh
+pip install "tamash-playwright[anthropic]"
+```
+
+## Step 2: Connect an AI model
+
+`tamash-playwright` needs an AI model to decide where a broken element actually went. Pick one of Ollama, OpenAI, Anthropic (Claude), or Google Gemini, and give it an API key.
+
+Create a file named `.env` in your project folder:
+
+```sh
+# Master on/off switch. Leave this as true, or remove the line entirely.
+HEALER_ENABLED=true
+
+# Pick one: ollama | openai | anthropic | gemini
+HEALER_PROVIDER=ollama
+
+# --- Ollama Cloud (https://ollama.com) ---
+OLLAMA_MODEL=gpt-oss:120b
+OLLAMA_API_KEY=
+
+# --- OpenAI ---
+# OPENAI_MODEL=gpt-4.1-mini
+# OPENAI_API_KEY=
+
+# --- Anthropic (Claude) ---
+# ANTHROPIC_MODEL=claude-haiku-4-5
+# ANTHROPIC_API_KEY=
+
+# --- Google Gemini ---
+# GEMINI_MODEL=
+# GEMINI_API_KEY=
+```
+
+Just fill in the API key and model for whichever one you want to use, and leave the rest as-is (or delete them).
+
+### Getting a free Ollama key (fastest way to get started)
+
+Ollama Cloud is a quick, free way to get an API key without signing up for OpenAI/Anthropic/Gemini billing.
+
+1. Go to [ollama.com](https://ollama.com/) and create an account.
+2. Once signed in, go to [ollama.com/settings/keys](https://ollama.com/settings/keys).
+3. Create a new API key and copy it.
+4. Paste it into your `.env` file:
+
+```sh
+HEALER_ENABLED=true
+HEALER_PROVIDER=ollama
+OLLAMA_MODEL=gpt-oss:120b
+OLLAMA_API_KEY=paste_your_key_here
+```
+
+That's all you need — no other variables required.
+
+## Step 3: Wire it in
+
+Unlike the JS/TS version of this package (where you swap one `import` line per test file), pytest's plugin model means the reliable way to activate self-healing is **one line in your project's `conftest.py`**, added once — not per test file:
+
+```python
+# conftest.py
+from tamash_playwright.plugin import page  # noqa: F401
+```
+
+Why this line, and not nothing at all: `tamash-playwright` registers itself as a pytest plugin automatically on install, and its `page` fixture *may* already override `pytest-playwright`'s own `page` fixture depending on plugin load order — but that order isn't something pytest guarantees across environments. A `conftest.py` fixture, on the other hand, is *always* preferred by pytest over a same-named fixture from an installed plugin, so re-exporting it there is the one setup step that's guaranteed to work everywhere, every time.
+
+With that line in place, every test using the `page` fixture — no matter how many test files you have — automatically gets self-healing. Nothing else changes:
+
+```python
+def test_login(page):
+    page.goto("/")
+    page.get_by_placeholder("Username").fill("Admin")  # healed automatically if this breaks
+    page.get_by_role("button", name="Login").click()
+    from playwright.sync_api import expect
+    expect(page.get_by_role("heading", name="Dashboard")).to_be_visible()
+```
+
+## Step 4: Check your setup
+
+Run the built-in doctor command to confirm everything's wired up correctly:
+
+```sh
+tamash-playwright doctor
+```
+
+It checks three things:
+
+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. **Missing `.describe()` labels** — scans your test files (`tests/` by default, or pass `--dir <path>`) for locators that don't have a `.describe('...')` label, flagging the ones most worth fixing (raw CSS/XPath selectors first).
+3. **Locators written directly in test files** — flags any locator defined inline in a test rather than inside a Page Object class, a Playwright best practice regardless of self-healing.
+
+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. 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.
+
+### A quick tip for better results
+
+If you're using plain CSS selectors (like `page.locator('input[name="username"]')`) rather than Playwright's more descriptive locators (`get_by_role`, `get_by_placeholder`, etc.), it helps to add a short, human-readable label so the healer knows what it's actually looking for. Chain `.describe('...')` right onto the locator:
+
+```python
+def test_login_using_css_selectors(page):
+    page.goto("https://example.com/auth/login")
+
+    txt_username = page.locator('input[name="username"]').describe("User Name Textbox")
+    txt_username.fill("testadmin")
+
+    txt_password = page.locator('input[placeholder="Password"]').describe("Password Textbox")
+    txt_password.fill("secret")
+
+    btn_login = page.locator('button[type="submit"]').describe("Login Button")
+    btn_login.click()
+```
+
+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 gets healed (and what doesn't)
+
+Only real Playwright actions that can be safely retried are healed: `click`, `fill`, `check`, `hover`, `press`, `select_option`, `set_input_files`, `focus`, `blur`, `dblclick`, `tap`, `clear`, `uncheck`. `drag_to` and anything unlisted is intentionally left alone rather than guessed at.
+
+`expect(...)` assertions (`to_have_text`, `to_be_visible`, etc.) are **not** healed — they use Playwright's own built-in auto-retrying assertions, which are a separate mechanism this package doesn't touch. If a locator only ever appears inside an `expect(...)` call and never in an action, `.describe()` on it is a readability nicety, not something that affects healing.
+
+## 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.
+
+## Support
+
+For questions or concerns, contact us at support@vibetestq.com.

tamash_playwright-0.1.0/README.md

@@ -0,0 +1,155 @@
+# tamash-playwright
+
+`tamash-playwright` is a plug and play self-healing solution for Playwright + pytest. Install it, add your AI API key details, and wire in one fixture override.
+
+That's it. No changes needed to your actual test functions if you're following standard Playwright/pytest best practices.
+
+> Also available for TypeScript/`@playwright/test` as [`tamash-playwright` on npm](https://www.npmjs.com/package/tamash-playwright) — same name, same idea, separate package per ecosystem.
+
+### Why you need this
+
+Websites change often. A button gets renamed or moved, and your test can't find it anymore — even though the app still works fine for real users. Normally, that just means a broken test.
+
+`tamash-playwright` fixes this automatically. When a test action 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.
+
+Here are the detailed steps to use this package.
+
+## Step 1: Install it
+
+```sh
+pip install tamash-playwright
+```
+
+This pulls in `pytest-playwright` as a dependency, so if you're starting fresh you'll also need the Playwright browsers:
+
+```sh
+playwright install
+```
+
+Using Anthropic (Claude) as your provider needs one extra install:
+
+```sh
+pip install "tamash-playwright[anthropic]"
+```
+
+## Step 2: Connect an AI model
+
+`tamash-playwright` needs an AI model to decide where a broken element actually went. Pick one of Ollama, OpenAI, Anthropic (Claude), or Google Gemini, and give it an API key.
+
+Create a file named `.env` in your project folder:
+
+```sh
+# Master on/off switch. Leave this as true, or remove the line entirely.
+HEALER_ENABLED=true
+
+# Pick one: ollama | openai | anthropic | gemini
+HEALER_PROVIDER=ollama
+
+# --- Ollama Cloud (https://ollama.com) ---
+OLLAMA_MODEL=gpt-oss:120b
+OLLAMA_API_KEY=
+
+# --- OpenAI ---
+# OPENAI_MODEL=gpt-4.1-mini
+# OPENAI_API_KEY=
+
+# --- Anthropic (Claude) ---
+# ANTHROPIC_MODEL=claude-haiku-4-5
+# ANTHROPIC_API_KEY=
+
+# --- Google Gemini ---
+# GEMINI_MODEL=
+# GEMINI_API_KEY=
+```
+
+Just fill in the API key and model for whichever one you want to use, and leave the rest as-is (or delete them).
+
+### Getting a free Ollama key (fastest way to get started)
+
+Ollama Cloud is a quick, free way to get an API key without signing up for OpenAI/Anthropic/Gemini billing.
+
+1. Go to [ollama.com](https://ollama.com/) and create an account.
+2. Once signed in, go to [ollama.com/settings/keys](https://ollama.com/settings/keys).
+3. Create a new API key and copy it.
+4. Paste it into your `.env` file:
+
+```sh
+HEALER_ENABLED=true
+HEALER_PROVIDER=ollama
+OLLAMA_MODEL=gpt-oss:120b
+OLLAMA_API_KEY=paste_your_key_here
+```
+
+That's all you need — no other variables required.
+
+## Step 3: Wire it in
+
+Unlike the JS/TS version of this package (where you swap one `import` line per test file), pytest's plugin model means the reliable way to activate self-healing is **one line in your project's `conftest.py`**, added once — not per test file:
+
+```python
+# conftest.py
+from tamash_playwright.plugin import page  # noqa: F401
+```
+
+Why this line, and not nothing at all: `tamash-playwright` registers itself as a pytest plugin automatically on install, and its `page` fixture *may* already override `pytest-playwright`'s own `page` fixture depending on plugin load order — but that order isn't something pytest guarantees across environments. A `conftest.py` fixture, on the other hand, is *always* preferred by pytest over a same-named fixture from an installed plugin, so re-exporting it there is the one setup step that's guaranteed to work everywhere, every time.
+
+With that line in place, every test using the `page` fixture — no matter how many test files you have — automatically gets self-healing. Nothing else changes:
+
+```python
+def test_login(page):
+    page.goto("/")
+    page.get_by_placeholder("Username").fill("Admin")  # healed automatically if this breaks
+    page.get_by_role("button", name="Login").click()
+    from playwright.sync_api import expect
+    expect(page.get_by_role("heading", name="Dashboard")).to_be_visible()
+```
+
+## Step 4: Check your setup
+
+Run the built-in doctor command to confirm everything's wired up correctly:
+
+```sh
+tamash-playwright doctor
+```
+
+It checks three things:
+
+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. **Missing `.describe()` labels** — scans your test files (`tests/` by default, or pass `--dir <path>`) for locators that don't have a `.describe('...')` label, flagging the ones most worth fixing (raw CSS/XPath selectors first).
+3. **Locators written directly in test files** — flags any locator defined inline in a test rather than inside a Page Object class, a Playwright best practice regardless of self-healing.
+
+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. 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.
+
+### A quick tip for better results
+
+If you're using plain CSS selectors (like `page.locator('input[name="username"]')`) rather than Playwright's more descriptive locators (`get_by_role`, `get_by_placeholder`, etc.), it helps to add a short, human-readable label so the healer knows what it's actually looking for. Chain `.describe('...')` right onto the locator:
+
+```python
+def test_login_using_css_selectors(page):
+    page.goto("https://example.com/auth/login")
+
+    txt_username = page.locator('input[name="username"]').describe("User Name Textbox")
+    txt_username.fill("testadmin")
+
+    txt_password = page.locator('input[placeholder="Password"]').describe("Password Textbox")
+    txt_password.fill("secret")
+
+    btn_login = page.locator('button[type="submit"]').describe("Login Button")
+    btn_login.click()
+```
+
+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 gets healed (and what doesn't)
+
+Only real Playwright actions that can be safely retried are healed: `click`, `fill`, `check`, `hover`, `press`, `select_option`, `set_input_files`, `focus`, `blur`, `dblclick`, `tap`, `clear`, `uncheck`. `drag_to` and anything unlisted is intentionally left alone rather than guessed at.
+
+`expect(...)` assertions (`to_have_text`, `to_be_visible`, etc.) are **not** healed — they use Playwright's own built-in auto-retrying assertions, which are a separate mechanism this package doesn't touch. If a locator only ever appears inside an `expect(...)` call and never in an action, `.describe()` on it is a readability nicety, not something that affects healing.
+
+## 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.
+
+## Support
+
+For questions or concerns, contact us at support@vibetestq.com.

tamash_playwright-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tamash-playwright"
+version = "0.1.0"
+description = "Self-healing bindings for Playwright + pytest: automatically recovers broken selectors using an AI model (Ollama, OpenAI, Anthropic, or Gemini)."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "SEE LICENSE IN LICENSE" }
+authors = [{ name = "QtpSudhakar / VibeTestQ" }]
+keywords = ["playwright", "pytest", "self-healing", "test-automation", "llm", "ollama", "openai", "anthropic", "gemini"]
+dependencies = [
+    "pytest-playwright>=0.4.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.optional-dependencies]
+anthropic = ["anthropic>=0.115.0"]
+
+[project.urls]
+Homepage = "https://github.com/qtpsudhakarproducts/tamash-playwright-python"
+Repository = "https://github.com/qtpsudhakarproducts/tamash-playwright-python"
+License = "https://github.com/qtpsudhakarproducts/tamash-playwright-python/blob/main/LICENSE"
+
+[project.entry-points.pytest11]
+tamash_playwright = "tamash_playwright.plugin"
+
+[project.scripts]
+tamash-playwright = "tamash_playwright.cli.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tamash_playwright"]

tamash_playwright-0.1.0/src/tamash_playwright/__init__.py

@@ -0,0 +1,11 @@
+from .bindings import bind_frame, bind_locator, bind_page
+from .healer.core import SelfHealingReport, get_healing_reports, heal_action_failure
+
+__all__ = [
+    "bind_page",
+    "bind_frame",
+    "bind_locator",
+    "heal_action_failure",
+    "get_healing_reports",
+    "SelfHealingReport",
+]

tamash_playwright-0.1.0/src/tamash_playwright/bindings.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from playwright.sync_api import Locator
+
+from .healer.core import heal_action_failure
+
+# `drag_to` is included so a failure is at least reported (see healer/core.py's
+# _REPLAYABLE_ACTIONS for why it can never actually be healed).
+_ACTIONS = {
+    "click",
+    "dblclick",
+    "tap",
+    "hover",
+    "fill",
+    "clear",
+    "press",
+    "check",
+    "uncheck",
+    "select_option",
+    "set_input_files",
+    "drag_to",
+    "focus",
+    "blur",
+}
+
+_LOCATOR_FACTORY_METHODS = {
+    "locator",
+    "get_by_role",
+    "get_by_label",
+    "get_by_placeholder",
+    "get_by_text",
+    "get_by_alt_text",
+    "get_by_title",
+    "get_by_test_id",
+}
+
+# Playwright's Locator.and_()/or_() use a trailing underscore since `and`/`or` are reserved
+# keywords in Python.
+_CHAIN_METHODS = {"describe", "first", "last", "nth", "filter", "and_", "or_"}
+
+_DESCRIPTION_ATTR = "_tamash_description"
+
+
+def _describe_factory_call(method: str, args: tuple, kwargs: dict) -> Optional[str]:
+    first = args[0] if args else None
+
+    if method == "get_by_role":
+        name = kwargs.get("name") or (args[1] if len(args) > 1 else None)
+        return f'role:{first} "{name}"' if name else f"role:{first}"
+    if method == "get_by_label":
+        return f'label "{first}"'
+    if method == "get_by_placeholder":
+        return f'placeholder "{first}"'
+    if method == "get_by_text":
+        return f'text "{first}"'
+    if method == "get_by_alt_text":
+        return f'alt text "{first}"'
+    if method == "get_by_title":
+        return f'title "{first}"'
+    if method == "get_by_test_id":
+        return f'testid "{first}"'
+    if method == "locator":
+        return f'selector "{first}"'
+    return None
+
+
+# Python has no equivalent of JS's Proxy, and — unlike a __getattr__-based wrapper class — that
+# actually matters here: Playwright's own `expect()` does `isinstance(actual, Locator)` /
+# `isinstance(actual, Page)` internally and reaches into `actual._impl_obj` directly. A wrapper
+# class fails those checks outright (`expect()` raises "Unsupported type"), since it was never
+# really a Locator/Page to begin with. So instead of wrapping, this monkey-patches the specific
+# action/factory/chain methods directly onto the *real* Page/Frame/Locator instance in place —
+# it's still a genuine Locator afterwards, isinstance and expect() both keep working, and only
+# the patched method names' behavior changes.
+
+
+def _patch_actions(obj: Any, kind: str) -> None:
+    for name in _ACTIONS:
+        original = getattr(obj, name, None)
+        if not callable(original):
+            continue
+
+        def make_wrapper(action_name: str, real_method: Any) -> Any:
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                try:
+                    return real_method(*args, **kwargs)
+                except Exception as error:  # noqa: BLE001 - re-raised below if not recovered
+                    description = getattr(obj, _DESCRIPTION_ATTR, None)
+                    _report, recovered, result = heal_action_failure(
+                        action=action_name,
+                        kind=kind,
+                        description=description or f"{kind} action {action_name}",
+                        error=error,
+                        target=obj,
+                        args=args,
+                        kwargs=kwargs,
+                    )
+                    if recovered:
+                        return result
+                    raise
+
+            return wrapper
+
+        setattr(obj, name, make_wrapper(name, original))
+
+
+def _patch_locator_factories(obj: Any, kind: str) -> None:
+    for name in _LOCATOR_FACTORY_METHODS:
+        original = getattr(obj, name, None)
+        if not callable(original):
+            continue
+
+        def make_wrapper(method_name: str, real_factory: Any) -> Any:
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                child = real_factory(*args, **kwargs)
+                if isinstance(child, Locator):
+                    _patch_locator(child, _describe_factory_call(method_name, args, kwargs))
+                return child
+
+            return wrapper
+
+        setattr(obj, name, make_wrapper(name, original))
+
+
+def _patch_chain_methods(locator: Any, description: Optional[str]) -> None:
+    for name in _CHAIN_METHODS:
+        original = getattr(locator, name, None)
+        if not callable(original):
+            continue
+
+        def make_wrapper(method_name: str, real_method: Any) -> Any:
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                result = real_method(*args, **kwargs)
+                next_description = str(args[0]) if method_name == "describe" and args else description
+                if isinstance(result, Locator):
+                    _patch_locator(result, next_description)
+                return result
+
+            return wrapper
+
+        setattr(locator, name, make_wrapper(name, original))
+
+
+def _patch_locator(locator: Any, description: Optional[str]) -> None:
+    if description is not None:
+        setattr(locator, _DESCRIPTION_ATTR, description)
+    _patch_actions(locator, "locator")
+    _patch_locator_factories(locator, "locator")
+    _patch_chain_methods(locator, description)
+
+
+def bind_page(page: Any) -> Any:
+    _patch_actions(page, "page")
+    _patch_locator_factories(page, "page")
+    return page
+
+
+def bind_frame(frame: Any) -> Any:
+    _patch_actions(frame, "frame")
+    _patch_locator_factories(frame, "frame")
+    return frame
+
+
+def bind_locator(locator: Any) -> Any:
+    _patch_locator(locator, None)
+    return locator

tamash_playwright-0.1.0/src/tamash_playwright/cli/__main__.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .doctor import run_doctor
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="tamash-playwright")
+    subparsers = parser.add_subparsers(dest="command")
+
+    doctor_parser = subparsers.add_parser("doctor", help="Check AI connectivity and locator best practices.")
+    doctor_parser.add_argument("--dir", default="tests", help="Test directory to scan (default: tests)")
+
+    args = parser.parse_args()
+
+    if args.command == "doctor":
+        run_doctor(args.dir)
+    else:
+        parser.print_help()
+        sys.exit(1 if args.command else 0)
+
+
+if __name__ == "__main__":
+    main()