argus-testing 0.1.0__tar.gz

argus_testing-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+argus-reports/
+*.png
+.env
+test-reports/

argus_testing-0.1.0/CLAUDE.md

@@ -0,0 +1,72 @@
+# Argus — AI-Powered Exploratory QA Agent
+
+## What is this
+
+Argus is an open-source tool that tests web applications like a real user. Give it a URL, it explores your app — clicking buttons, filling forms, trying edge cases — and generates an HTML report of every bug it finds.
+
+**The key insight:** Existing testing tools (Playwright, Cypress) only test what you script. Argus discovers bugs you didn't think to test for.
+
+## Two usage modes
+
+1. **CLI mode** (`argus <url>`) — Standalone with built-in LLM planner via LiteLLM. Needs an API key (OpenAI, Anthropic, DeepSeek, Gemini, Ollama, etc.).
+2. **MCP mode** (`argus-mcp`) — Claude Code becomes the AI brain. Argus provides browser tools. No API key needed. Configured via `claude mcp add argus -- argus-mcp`.
+
+## Project goals
+
+- **Primary:** Get GitHub stars. This means: solve a real pain point, one-command setup, great README with GIFs/screenshots, polished UX.
+- **Secondary:** Portfolio piece for Big Tech AI/ML Engineer interviews. Demonstrate AI system engineering (not prompt wrappers) — async workers, state management, cost control, scaling.
+- **Tertiary:** Eventually commercializable as a SaaS.
+
+## Architecture
+
+```
+argus/
+├── cli.py           # CLI entry point (click)
+├── config.py        # YAML config + focus areas
+├── browser.py       # Playwright driver + DOM extraction + page content extraction + error capture
+├── planner.py       # LLM exploration strategy (LiteLLM) — CLI mode brain
+├── detector.py      # Bug detection: console/network errors + smart detection (text anomalies,
+│                    #   count consistency, CSS state, toast cross-check, state verification)
+├── explorer.py      # Main loop: observe → plan → act → detect → verify → screenshot
+├── reporter.py      # Self-contained HTML report with embedded base64 screenshots
+├── mcp_server.py    # MCP server exposing browser tools for Claude Code (12 tools incl. verify_action)
+└── models.py        # Data models (Bug, Action, PageState, Screenshot, etc.)
+```
+
+## Tech stack
+
+Python 3.10+ | Playwright | LiteLLM | MCP SDK | Click | Rich | PyYAML
+
+## Development
+
+```bash
+cd /Users/yichen/projects/argus
+source .venv/bin/activate
+pip install -e .
+playwright install chromium
+```
+
+## Test site
+
+`test-site/app.py` is BuggyTasks — a realistic task management app (Starlette) with **22 intentional bugs** across 4 difficulty tiers:
+
+- **Tier 1 (surface):** console errors, dead links, API 500s
+- **Tier 2 (form):** auth bypass, password mismatch, XSS, form data loss
+- **Tier 3 (logic):** fake delete/save, off-by-one count, pagination dupes, race conditions
+- **Tier 4 (UX):** case-sensitive search, broken dates, eternal "Loading...", misleading success toasts
+
+The full bug catalog is documented at the top of `test-site/app.py`. Run with:
+
+```bash
+cd test-site && python app.py  # runs on http://127.0.0.1:5555
+```
+
+## GitHub
+
+Repo: https://github.com/chriswu727/argus (owner: chriswu727)
+
+## Key files for context
+
+- `docs/STATUS.md` — Current completion status and what's done
+- `docs/ROADMAP.md` — Future features and priorities
+- `docs/TODO.md` — Immediate next tasks

argus_testing-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yichen Wu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.

argus_testing-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: argus-testing
+Version: 0.1.0
+Summary: AI-powered exploratory testing agent that discovers bugs like a real user
+Project-URL: Homepage, https://github.com/chriswu727/argus
+Project-URL: Repository, https://github.com/chriswu727/argus
+Author-email: Yichen Wu <yichenwujob@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agent,ai,claude-code,exploratory-testing,mcp,playwright,qa,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0.0
+Requires-Dist: jinja2>=3.0.0
+Requires-Dist: litellm>=1.40.0
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: playwright>=1.40.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Description-Content-Type: text/markdown
+
+# Argus
+
+**AI-powered exploratory QA agent.** Give it a URL, it explores your app like a real user — clicking buttons, filling forms, trying edge cases — and finds bugs that scripted tests miss.
+
+Unlike Playwright or Cypress, you don't write test scripts. Argus **discovers bugs you didn't think to test for.**
+
+## What It Catches
+
+Traditional test tools only catch what you explicitly script. Argus catches:
+
+- **Console errors & crashes** — JS exceptions, unhandled promises
+- **Broken API calls** — HTTP 4xx/5xx responses
+- **Fake success operations** — "Saved!" toast shown but server returned 500
+- **Silent data loss** — delete says "Deleted!" but item still exists on refresh
+- **Broken date formatting** — "1.52 days ago" instead of "2 days ago"
+- **Count mismatches** — dashboard says "7 tasks" but there are actually 8
+- **Dead links** — navigation links pointing to 404 pages
+- **XSS vulnerabilities** — unsanitized user input reflected in HTML
+
+## Quick Start (MCP Server for Claude Code)
+
+The recommended way to use Argus. Claude Code becomes the AI brain — no API key needed.
+
+```bash
+pip install argus-testing
+playwright install chromium
+claude mcp add argus -- argus-mcp
+```
+
+Then in Claude Code:
+
+> "Test my app at http://localhost:3000, focus on the checkout flow"
+
+Claude Code will explore your app using Argus tools, try edge cases, verify that actions actually persist, and generate an HTML bug report.
+
+### MCP Tools
+
+| Tool | What it does |
+|------|-------------|
+| `start_session(url)` | Launch browser, navigate to URL |
+| `get_page_state()` | See all interactive elements + page content + counts + toasts |
+| `click(index)` | Click an element |
+| `type_text(index, text)` | Type into an input field |
+| `navigate(url)` | Go to a URL |
+| `screenshot(name)` | Capture the current page |
+| `get_errors()` | Get console/network errors + smart detection (broken dates, count mismatches, misleading toasts) |
+| `verify_action(type, text, url)` | Verify a delete/edit actually persisted by navigating and checking |
+| `end_session()` | Close browser, generate HTML report |
+
+## Alternative: Standalone CLI
+
+Bring your own LLM API key. Argus has a built-in AI planner that decides what to explore.
+
+```bash
+pip install argus-testing
+playwright install chromium
+
+export DEEPSEEK_API_KEY=sk-...   # or OPENAI_API_KEY, ANTHROPIC_API_KEY
+
+argus http://localhost:3000 --model deepseek/deepseek-chat -n 50
+argus http://localhost:3000 -f "test login with edge cases" --headed
+```
+
+Supports 100+ models via [LiteLLM](https://github.com/BerriAI/litellm): OpenAI, Anthropic, DeepSeek, Gemini, Ollama (free/local), etc.
+
+## Smart Detection
+
+Argus goes beyond console errors. It extracts page content and analyzes it:
+
+| Detection | How it works | Example bug found |
+|-----------|-------------|-------------------|
+| **State verification** | After delete/edit, navigates back and checks if the change persisted | "Deleted!" shown but item reappears on refresh |
+| **Toast + error cross-check** | Correlates success toasts with HTTP 500 responses | Settings shows "Saved!" but server crashed |
+| **Text anomaly scanning** | Regex patterns on visible page text | "NaN", "1.52 days ago", eternal "Loading..." |
+| **Count consistency** | Compares displayed counts against actual rendered items | Header says "7 tasks" but 8 items visible |
+| **CSS state analysis** | Checks semantic CSS classes for contradictory states | "0 remaining" shown in red (should be success) |
+
+## Bug Report
+
+Each session generates a self-contained HTML report with:
+
+- Bug cards with severity, type, description, and reproduction steps
+- Embedded screenshots (base64 — no external files needed)
+- Testing timeline showing every page visited
+- Console and network error logs
+
+## How It Works
+
+```
+You give a URL
+  → Argus opens a real browser (Playwright)
+  → AI explores: clicks, types, navigates, tries edge cases
+  → Smart detection analyzes page content after every action
+  → Generates HTML report with all bugs found
+```
+
+## Architecture
+
+```
+argus/
+├── browser.py       # Playwright driver + DOM extraction + page content analysis
+├── detector.py      # Smart bug detection (5 detection methods)
+├── mcp_server.py    # MCP server (12 tools) for Claude Code
+├── explorer.py      # CLI exploration loop
+├── planner.py       # LLM planner for CLI mode (LiteLLM)
+├── reporter.py      # Self-contained HTML report generator
+├── models.py        # Data models
+├── config.py        # YAML config + focus areas
+└── cli.py           # CLI entry point
+```
+
+## Requirements
+
+- Python 3.10+
+- Chromium (auto-installed via `playwright install chromium`)
+
+## License
+
+MIT

argus_testing-0.1.0/README.md

@@ -0,0 +1,119 @@
+# Argus
+
+**AI-powered exploratory QA agent.** Give it a URL, it explores your app like a real user — clicking buttons, filling forms, trying edge cases — and finds bugs that scripted tests miss.
+
+Unlike Playwright or Cypress, you don't write test scripts. Argus **discovers bugs you didn't think to test for.**
+
+## What It Catches
+
+Traditional test tools only catch what you explicitly script. Argus catches:
+
+- **Console errors & crashes** — JS exceptions, unhandled promises
+- **Broken API calls** — HTTP 4xx/5xx responses
+- **Fake success operations** — "Saved!" toast shown but server returned 500
+- **Silent data loss** — delete says "Deleted!" but item still exists on refresh
+- **Broken date formatting** — "1.52 days ago" instead of "2 days ago"
+- **Count mismatches** — dashboard says "7 tasks" but there are actually 8
+- **Dead links** — navigation links pointing to 404 pages
+- **XSS vulnerabilities** — unsanitized user input reflected in HTML
+
+## Quick Start (MCP Server for Claude Code)
+
+The recommended way to use Argus. Claude Code becomes the AI brain — no API key needed.
+
+```bash
+pip install argus-testing
+playwright install chromium
+claude mcp add argus -- argus-mcp
+```
+
+Then in Claude Code:
+
+> "Test my app at http://localhost:3000, focus on the checkout flow"
+
+Claude Code will explore your app using Argus tools, try edge cases, verify that actions actually persist, and generate an HTML bug report.
+
+### MCP Tools
+
+| Tool | What it does |
+|------|-------------|
+| `start_session(url)` | Launch browser, navigate to URL |
+| `get_page_state()` | See all interactive elements + page content + counts + toasts |
+| `click(index)` | Click an element |
+| `type_text(index, text)` | Type into an input field |
+| `navigate(url)` | Go to a URL |
+| `screenshot(name)` | Capture the current page |
+| `get_errors()` | Get console/network errors + smart detection (broken dates, count mismatches, misleading toasts) |
+| `verify_action(type, text, url)` | Verify a delete/edit actually persisted by navigating and checking |
+| `end_session()` | Close browser, generate HTML report |
+
+## Alternative: Standalone CLI
+
+Bring your own LLM API key. Argus has a built-in AI planner that decides what to explore.
+
+```bash
+pip install argus-testing
+playwright install chromium
+
+export DEEPSEEK_API_KEY=sk-...   # or OPENAI_API_KEY, ANTHROPIC_API_KEY
+
+argus http://localhost:3000 --model deepseek/deepseek-chat -n 50
+argus http://localhost:3000 -f "test login with edge cases" --headed
+```
+
+Supports 100+ models via [LiteLLM](https://github.com/BerriAI/litellm): OpenAI, Anthropic, DeepSeek, Gemini, Ollama (free/local), etc.
+
+## Smart Detection
+
+Argus goes beyond console errors. It extracts page content and analyzes it:
+
+| Detection | How it works | Example bug found |
+|-----------|-------------|-------------------|
+| **State verification** | After delete/edit, navigates back and checks if the change persisted | "Deleted!" shown but item reappears on refresh |
+| **Toast + error cross-check** | Correlates success toasts with HTTP 500 responses | Settings shows "Saved!" but server crashed |
+| **Text anomaly scanning** | Regex patterns on visible page text | "NaN", "1.52 days ago", eternal "Loading..." |
+| **Count consistency** | Compares displayed counts against actual rendered items | Header says "7 tasks" but 8 items visible |
+| **CSS state analysis** | Checks semantic CSS classes for contradictory states | "0 remaining" shown in red (should be success) |
+
+## Bug Report
+
+Each session generates a self-contained HTML report with:
+
+- Bug cards with severity, type, description, and reproduction steps
+- Embedded screenshots (base64 — no external files needed)
+- Testing timeline showing every page visited
+- Console and network error logs
+
+## How It Works
+
+```
+You give a URL
+  → Argus opens a real browser (Playwright)
+  → AI explores: clicks, types, navigates, tries edge cases
+  → Smart detection analyzes page content after every action
+  → Generates HTML report with all bugs found
+```
+
+## Architecture
+
+```
+argus/
+├── browser.py       # Playwright driver + DOM extraction + page content analysis
+├── detector.py      # Smart bug detection (5 detection methods)
+├── mcp_server.py    # MCP server (12 tools) for Claude Code
+├── explorer.py      # CLI exploration loop
+├── planner.py       # LLM planner for CLI mode (LiteLLM)
+├── reporter.py      # Self-contained HTML report generator
+├── models.py        # Data models
+├── config.py        # YAML config + focus areas
+└── cli.py           # CLI entry point
+```
+
+## Requirements
+
+- Python 3.10+
+- Chromium (auto-installed via `playwright install chromium`)
+
+## License
+
+MIT

argus_testing-0.1.0/argus/__init__.py

@@ -0,0 +1,3 @@
+"""Argus — AI-powered exploratory QA agent."""
+
+__version__ = "0.1.0"

argus_testing-0.1.0/argus/browser.py

@@ -0,0 +1,286 @@
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime
+from pathlib import Path
+
+from playwright.async_api import Browser, BrowserContext, Page, async_playwright
+
+from typing import Dict, List, Optional, Tuple
+
+from .models import InteractiveElement, PageState
+
+# JS snippet to extract visible interactive elements from the page.
+_EXTRACT_ELEMENTS_JS = """
+() => {
+    const sel = 'a, button, input, select, textarea, [role="button"], [role="link"], [role="tab"], [role="menuitem"], [onclick], [tabindex]:not([tabindex="-1"])';
+    const els = document.querySelectorAll(sel);
+    return Array.from(els).map((el, i) => {
+        const rect = el.getBoundingClientRect();
+        const style = window.getComputedStyle(el);
+        if (rect.width === 0 || rect.height === 0 || style.display === 'none' || style.visibility === 'hidden') return null;
+        return {
+            index: i,
+            tag: el.tagName.toLowerCase(),
+            type: el.type || null,
+            text: (el.textContent || '').trim().slice(0, 100) || null,
+            placeholder: el.placeholder || null,
+            href: el.href || null,
+            value: el.value || null,
+            disabled: el.disabled || false,
+            role: el.getAttribute('role') || null,
+            aria_label: el.getAttribute('aria-label') || null,
+            name: el.name || null,
+            id: el.id || null,
+        };
+    }).filter(Boolean);
+}
+"""
+
+# JS snippet to extract full page content for smart detection.
+_EXTRACT_PAGE_CONTENT_JS = """
+() => {
+    const result = { pageText: '', toasts: [], counts: {}, cssIndicators: [], itemLists: {} };
+
+    // 1. Full visible text — simple and robust
+    try {
+        result.pageText = (document.body.innerText || '').slice(0, 5000);
+    } catch(e) {}
+
+    // 2. Toast/notification messages
+    try {
+        const sels = '.toast, [role="alert"], .alert-success, .alert-error, .alert-warning, [class*="toast"]';
+        document.querySelectorAll(sels).forEach(el => {
+            const text = el.textContent.trim();
+            if (text) {
+                const s = window.getComputedStyle(el);
+                result.toasts.push({
+                    text: text.slice(0, 200),
+                    visible: s.display !== 'none' && s.visibility !== 'hidden',
+                    classes: el.className || ''
+                });
+            }
+        });
+    } catch(e) {}
+
+    // 3. Number + label counts
+    try {
+        document.querySelectorAll('.stat, .stat-val, .count, .badge, h1, h2, h3, p, span').forEach(el => {
+            const text = el.textContent.trim();
+            const m = text.match(/^(\\d+)\\s+(.+)$/);
+            if (m) result.counts[m[2].trim()] = parseInt(m[1], 10);
+        });
+    } catch(e) {}
+
+    // 4. Semantic CSS indicators
+    try {
+        ['remaining-zero','task-done','error','loading','spinner','alert-error','alert-success'].forEach(cls => {
+            document.querySelectorAll('.' + cls).forEach(el => {
+                result.cssIndicators.push({
+                    cls: cls,
+                    text: el.textContent.trim().slice(0, 100),
+                    tag: el.tagName.toLowerCase()
+                });
+            });
+        });
+    } catch(e) {}
+
+    // 5. Item lists
+    try {
+        document.querySelectorAll('.card, .list, ul, ol').forEach(container => {
+            const items = container.querySelectorAll('.task-item, .list-item, li, tr');
+            if (items.length >= 2) {
+                const key = (container.className || container.tagName).slice(0, 50);
+                result.itemLists[key] = Array.from(items).map(it => it.textContent.trim().slice(0, 200));
+            }
+        });
+    } catch(e) {}
+
+    return result;
+}
+"""
+
+
+class BrowserDriver:
+    """Wraps Playwright to drive a browser and capture errors."""
+
+    def __init__(
+        self,
+        headless: bool = True,
+        viewport_width: int = 1280,
+        viewport_height: int = 720,
+    ):
+        self.headless = headless
+        self.viewport = {"width": viewport_width, "height": viewport_height}
+        self._playwright = None
+        self._browser: Optional[Browser] = None
+        self._context: Optional[BrowserContext] = None
+        self._page: Optional[Page] = None
+        self.console_errors: List[Dict] = []
+        self.network_errors: List[Dict] = []
+
+    # -- lifecycle --
+
+    async def start(self):
+        self._playwright = await async_playwright().start()
+        self._browser = await self._playwright.chromium.launch(headless=self.headless)
+        self._context = await self._browser.new_context(viewport=self.viewport)
+        self._page = await self._context.new_page()
+        self._setup_listeners()
+
+    async def stop(self):
+        if self._browser:
+            await self._browser.close()
+        if self._playwright:
+            await self._playwright.stop()
+
+    # -- listeners --
+
+    def _setup_listeners(self):
+        self._page.on("console", self._on_console)
+        self._page.on("pageerror", self._on_page_error)
+        self._page.on("response", self._on_response)
+
+    def _on_console(self, msg):
+        if msg.type in ("error", "warning"):
+            self.console_errors.append({
+                "type": msg.type,
+                "text": msg.text,
+                "url": self._page.url,
+                "timestamp": datetime.now().isoformat(),
+            })
+
+    def _on_page_error(self, error):
+        self.console_errors.append({
+            "type": "exception",
+            "text": str(error),
+            "url": self._page.url,
+            "timestamp": datetime.now().isoformat(),
+        })
+
+    async def _on_response(self, response):
+        if response.status >= 400:
+            self.network_errors.append({
+                "url": response.url,
+                "status": response.status,
+                "method": response.request.method,
+                "page_url": self._page.url,
+                "timestamp": datetime.now().isoformat(),
+            })
+
+    # -- navigation --
+
+    async def goto(self, url: str):
+        await self._page.goto(url, wait_until="networkidle", timeout=30_000)
+
+    # -- state extraction --
+
+    async def get_state(self) -> PageState:
+        elements = await self._extract_elements()
+        content = await self._extract_page_content()
+        return PageState(
+            url=self._page.url,
+            title=await self._page.title(),
+            elements=elements,
+            page_text=content.get("pageText", ""),
+            toast_messages=[t["text"] for t in content.get("toasts", []) if t.get("visible")],
+            counts=content.get("counts", {}),
+            css_indicators=[
+                f"{ind['cls']}:{ind['text']}"
+                for ind in content.get("cssIndicators", [])
+            ],
+            item_lists=content.get("itemLists", {}),
+        )
+
+    async def refresh_and_get_state(self) -> PageState:
+        """Reload the current page and return fresh state for verification."""
+        await self._page.reload(wait_until="networkidle", timeout=15_000)
+        return await self.get_state()
+
+    async def _extract_elements(self) -> List[InteractiveElement]:
+        raw = await self._page.evaluate(_EXTRACT_ELEMENTS_JS)
+        return [InteractiveElement(**el) for el in raw]
+
+    async def _extract_page_content(self) -> Dict:
+        try:
+            return await self._page.evaluate(_EXTRACT_PAGE_CONTENT_JS)
+        except Exception:
+            return {}
+
+    # -- actions --
+
+    async def click(self, element_index: int, elements: List[InteractiveElement]) -> bool:
+        el = elements[element_index]
+        selector = self._build_selector(el)
+        try:
+            await self._page.click(selector, timeout=5_000)
+            await self._page.wait_for_load_state("networkidle", timeout=10_000)
+            return True
+        except Exception:
+            return False
+
+    async def type_text(
+        self, element_index: int, text: str, elements: List[InteractiveElement]
+    ) -> bool:
+        el = elements[element_index]
+        selector = self._build_selector(el)
+        try:
+            await self._page.fill(selector, text, timeout=5_000)
+            return True
+        except Exception:
+            return False
+
+    async def select_option(
+        self, element_index: int, value: str, elements: List[InteractiveElement]
+    ) -> bool:
+        el = elements[element_index]
+        selector = self._build_selector(el)
+        try:
+            await self._page.select_option(selector, value, timeout=5_000)
+            return True
+        except Exception:
+            return False
+
+    async def go_back(self) -> bool:
+        try:
+            await self._page.go_back(wait_until="networkidle", timeout=10_000)
+            return True
+        except Exception:
+            return False
+
+    async def scroll_down(self):
+        await self._page.evaluate("window.scrollBy(0, 500)")
+        await asyncio.sleep(0.5)
+
+    async def screenshot(self, path: str) -> str:
+        Path(path).parent.mkdir(parents=True, exist_ok=True)
+        await self._page.screenshot(path=path, full_page=False)
+        return path
+
+    # -- error draining --
+
+    def drain_errors(self) -> Tuple[List[Dict], List[Dict]]:
+        console = self.console_errors.copy()
+        network = self.network_errors.copy()
+        self.console_errors.clear()
+        self.network_errors.clear()
+        return console, network
+
+    # -- selector building --
+
+    @staticmethod
+    def _build_selector(el: InteractiveElement) -> str:
+        if el.id:
+            return f"#{el.id}"
+        parts = [el.tag]
+        if el.name:
+            parts.append(f'[name="{el.name}"]')
+        if el.type and el.tag == "input":
+            parts.append(f'[type="{el.type}"]')
+        if el.role:
+            parts.append(f'[role="{el.role}"]')
+        selector = "".join(parts)
+        if el.text and not el.name and not el.id:
+            text_escaped = el.text[:50].replace('"', '\\"')
+            return f'{el.tag}:has-text("{text_escaped}")'
+        return selector