wavexis 2.3.3__tar.gz → 2.3.5__tar.gz

{wavexis-2.3.3 → wavexis-2.3.5}/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to wavexis are documented in this file.
 
+## v2.3.5 — 2026-07-07
+
+### Added
+
+- Natural language selector: `find_by_text`, `nl_click`, `nl_fill` in both CDP and BiDi backends
+- `wavexis nl click/fill/find` CLI command with natural language queries
+- Fuzzy text matching scoring: exact match (100), contains query (80), query contains text (60), word overlap (up to 50)
+- Searches textContent, aria-label, placeholder, title, alt, and value attributes
+- Returns best CSS selector for the matched element
+- `--all` flag on `nl find` returns all matches ranked by score
+- `--no-wait` flag to skip auto-waiting
+
+## v2.3.4 — 2026-07-07
+
+### Added
+
+- Generate locator: `suggest_locator` method in both CDP and BiDi backends
+- `wavexis dom <url> --action suggest_locator -s <selector>` CLI command
+- `--all` flag to return all suggestions ranked by specificity
+- Priority order: `#id` > `[data-testid]` > `[aria-label]` > `[role]` > `:has-text()` > `tag.classes` > `parent > tag` > `:nth-of-type()` > `tag`
+- Uses `CSS.escape()` for safe selector generation
+
 ## v2.3.3 — 2026-07-07
 
 ### Added

{wavexis-2.3.3 → wavexis-2.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wavexis
-Version: 2.3.3
+Version: 2.3.5
 Summary: Browser automation CLI — wraps cdpwave and bidiwave, no Node.js, no Chromium download
 Project-URL: Homepage, https://github.com/MathiasPaulenko/wavexis
 Project-URL: Repository, https://github.com/MathiasPaulenko/wavexis

{wavexis-2.3.3 → wavexis-2.3.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "wavexis"
-version = "2.3.3"
+version = "2.3.5"
 description = "Browser automation CLI — wraps cdpwave and bidiwave, no Node.js, no Chromium download"
 readme = "README.md"
 license = { text = "MIT" }

{wavexis-2.3.3 → wavexis-2.3.5}/tests/unit/test_backend_manager.py

@@ -132,6 +132,28 @@ class DummyBackend(AbstractBackend):
         """Dom scroll."""
         pass
 
+    async def suggest_locator(
+        self, selector: str, all: bool = False
+    ) -> list[str] | str:
+        """Suggest locator."""
+        return selector
+
+    async def find_by_text(
+        self, query: str, all: bool = False
+    ) -> list[str] | str:
+        """Find by text."""
+        return query
+
+    async def nl_click(self, query: str, auto_wait: bool = True) -> None:
+        """NL click."""
+        pass
+
+    async def nl_fill(
+        self, query: str, value: str, auto_wait: bool = True
+    ) -> None:
+        """NL fill."""
+        pass
+
     async def capture_har(self, params: object) -> dict:
         """Capture har."""
         return {}

{wavexis-2.3.3 → wavexis-2.3.5}/tests/unit/test_manager.py

@@ -66,6 +66,16 @@ class FakeBackend(AbstractBackend):
         """Dom focus."""
     async def dom_scroll(self, selector=None, x=0, y=0):
         """Dom scroll."""
+    async def suggest_locator(self, selector, all=False):
+        """Suggest locator."""
+        return selector
+    async def find_by_text(self, query, all=False):
+        """Find by text."""
+        return query
+    async def nl_click(self, query, auto_wait=True):
+        """NL click."""
+    async def nl_fill(self, query, value, auto_wait=True):
+        """NL fill."""
     async def capture_har(self, params):
         """Capture har."""
     async def get_cookies(self):

wavexis-2.3.5/tests/unit/test_nl.py

@@ -0,0 +1,180 @@
+"""Unit tests for natural language selector — find_by_text, nl_click, nl_fill."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from wavexis.exceptions import ElementNotFoundError
+
+
+def _make_cdp_backend() -> Any:
+    """Create a CDPBackend with mocked session."""
+    from wavexis.backend.cdp import CDPBackend
+
+    backend = CDPBackend()
+    backend._session = MagicMock()
+    backend._session.runtime = MagicMock()
+    backend._session.runtime.evaluate = AsyncMock(
+        return_value={"result": {"value": None}}
+    )
+    return backend
+
+
+def _make_bidi_backend() -> Any:
+    """Create a BiDiBackend with mocked client."""
+    from wavexis.backend.bidi import BiDiBackend
+
+    backend = BiDiBackend()
+    backend._client = MagicMock()
+    backend._context = MagicMock()
+    backend._client.script = MagicMock()
+    result = MagicMock()
+    result.value = None
+    backend._client.script.evaluate = AsyncMock(return_value=result)
+    return backend
+
+
+@pytest.mark.unit
+class TestFindByTextCDP:
+    """Tests for find_by_text in CDP backend."""
+
+    def test_returns_best_selector(self) -> None:
+        """Test that find_by_text returns the best match."""
+        backend = _make_cdp_backend()
+        selectors = ["#login-btn", "button.primary"]
+        backend._session.runtime.evaluate = AsyncMock(
+            return_value={"result": {"value": json.dumps(selectors)}}
+        )
+        result = asyncio.run(backend.find_by_text("login button"))
+        assert result == "#login-btn"
+
+    def test_returns_all_selectors(self) -> None:
+        """Test that find_by_text with all=True returns all matches."""
+        backend = _make_cdp_backend()
+        selectors = ["#login-btn", "button.primary", "button"]
+        backend._session.runtime.evaluate = AsyncMock(
+            return_value={"result": {"value": json.dumps(selectors)}}
+        )
+        result = asyncio.run(backend.find_by_text("login", all=True))
+        assert isinstance(result, list)
+        assert len(result) == 3
+
+    def test_raises_on_no_match(self) -> None:
+        """Test that find_by_text raises ElementNotFoundError when no match."""
+        backend = _make_cdp_backend()
+        backend._session.runtime.evaluate = AsyncMock(
+            return_value={"result": {"value": json.dumps([])}}
+        )
+        with pytest.raises(ElementNotFoundError):
+            asyncio.run(backend.find_by_text("nonexistent"))
+
+    def test_raises_on_null_result(self) -> None:
+        """Test that find_by_text raises when JS returns null."""
+        backend = _make_cdp_backend()
+        backend._session.runtime.evaluate = AsyncMock(
+            return_value={"result": {"value": None}}
+        )
+        with pytest.raises(ElementNotFoundError):
+            asyncio.run(backend.find_by_text("anything"))
+
+
+@pytest.mark.unit
+class TestFindByTextBiDi:
+    """Tests for find_by_text in BiDi backend."""
+
+    def test_returns_best_selector(self) -> None:
+        """Test that find_by_text returns the best match."""
+        backend = _make_bidi_backend()
+        selectors = ["#email-input", "input.email"]
+        result_mock = MagicMock()
+        result_mock.value = json.dumps(selectors)
+        backend._client.script.evaluate = AsyncMock(return_value=result_mock)
+        result = asyncio.run(backend.find_by_text("email field"))
+        assert result == "#email-input"
+
+    def test_returns_all_selectors(self) -> None:
+        """Test that find_by_text with all=True returns all matches."""
+        backend = _make_bidi_backend()
+        selectors = ["#email", "input[placeholder='email']", "input"]
+        result_mock = MagicMock()
+        result_mock.value = json.dumps(selectors)
+        backend._client.script.evaluate = AsyncMock(return_value=result_mock)
+        result = asyncio.run(backend.find_by_text("email", all=True))
+        assert isinstance(result, list)
+        assert len(result) == 3
+
+    def test_raises_on_no_match(self) -> None:
+        """Test that find_by_text raises ElementNotFoundError when no match."""
+        backend = _make_bidi_backend()
+        result_mock = MagicMock()
+        result_mock.value = json.dumps([])
+        backend._client.script.evaluate = AsyncMock(return_value=result_mock)
+        with pytest.raises(ElementNotFoundError):
+            asyncio.run(backend.find_by_text("nonexistent"))
+
+
+@pytest.mark.unit
+class TestNlClick:
+    """Tests for nl_click in both backends."""
+
+    def test_cdp_nl_click_calls_click(self) -> None:
+        """Test that nl_click finds element and calls click."""
+        backend = _make_cdp_backend()
+        selectors = ["#submit-btn"]
+        backend._session.runtime.evaluate = AsyncMock(
+            return_value={"result": {"value": json.dumps(selectors)}}
+        )
+        backend.click = AsyncMock()
+        asyncio.run(backend.nl_click("submit button", auto_wait=False))
+        backend.click.assert_called_once_with(
+            "#submit-btn", auto_wait=False
+        )
+
+    def test_bidi_nl_click_calls_click(self) -> None:
+        """Test that nl_click finds element and calls click."""
+        backend = _make_bidi_backend()
+        selectors = ["#submit-btn"]
+        result_mock = MagicMock()
+        result_mock.value = json.dumps(selectors)
+        backend._client.script.evaluate = AsyncMock(return_value=result_mock)
+        backend.click = AsyncMock()
+        asyncio.run(backend.nl_click("submit button", auto_wait=False))
+        backend.click.assert_called_once_with(
+            "#submit-btn", auto_wait=False
+        )
+
+
+@pytest.mark.unit
+class TestNlFill:
+    """Tests for nl_fill in both backends."""
+
+    def test_cdp_nl_fill_calls_fill(self) -> None:
+        """Test that nl_fill finds element and calls fill."""
+        backend = _make_cdp_backend()
+        selectors = ["#email-field"]
+        backend._session.runtime.evaluate = AsyncMock(
+            return_value={"result": {"value": json.dumps(selectors)}}
+        )
+        backend.fill = AsyncMock()
+        asyncio.run(backend.nl_fill("email field", "test@test.com", auto_wait=False))
+        backend.fill.assert_called_once_with(
+            "#email-field", "test@test.com", auto_wait=False
+        )
+
+    def test_bidi_nl_fill_calls_fill(self) -> None:
+        """Test that nl_fill finds element and calls fill."""
+        backend = _make_bidi_backend()
+        selectors = ["#email-field"]
+        result_mock = MagicMock()
+        result_mock.value = json.dumps(selectors)
+        backend._client.script.evaluate = AsyncMock(return_value=result_mock)
+        backend.fill = AsyncMock()
+        asyncio.run(backend.nl_fill("email field", "test@test.com", auto_wait=False))
+        backend.fill.assert_called_once_with(
+            "#email-field", "test@test.com", auto_wait=False
+        )

wavexis-2.3.5/tests/unit/test_suggest_locator.py

@@ -0,0 +1,110 @@
+"""Unit tests for suggest_locator in both backends."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from wavexis.exceptions import ElementNotFoundError
+
+
+def _make_cdp_backend() -> Any:
+    """Create a CDPBackend with mocked session."""
+    from wavexis.backend.cdp import CDPBackend
+
+    backend = CDPBackend()
+    backend._session = MagicMock()
+    backend._session.runtime = MagicMock()
+    backend._session.runtime.evaluate = AsyncMock(
+        return_value={"result": {"value": None}}
+    )
+    return backend
+
+
+def _make_bidi_backend() -> Any:
+    """Create a BiDiBackend with mocked client."""
+    from wavexis.backend.bidi import BiDiBackend
+
+    backend = BiDiBackend()
+    backend._client = MagicMock()
+    backend._context = MagicMock()
+    backend._client.script = MagicMock()
+    result = MagicMock()
+    result.value = None
+    backend._client.script.evaluate = AsyncMock(return_value=result)
+    return backend
+
+
+@pytest.mark.unit
+class TestSuggestLocatorCDP:
+    """Tests for suggest_locator in CDP backend."""
+
+    def test_returns_best_selector(self) -> None:
+        """Test that suggest_locator returns the first (best) suggestion."""
+        backend = _make_cdp_backend()
+        suggestions = ["#login-btn", "button.primary", "button"]
+        backend._session.runtime.evaluate = AsyncMock(
+            return_value={"result": {"value": json.dumps(suggestions)}}
+        )
+        result = asyncio.run(backend.suggest_locator("#login-btn"))
+        assert result == "#login-btn"
+
+    def test_returns_all_suggestions(self) -> None:
+        """Test that suggest_locator with all=True returns all suggestions."""
+        backend = _make_cdp_backend()
+        suggestions = ["#my-id", "[data-testid='btn']", "button.clickable", "button"]
+        backend._session.runtime.evaluate = AsyncMock(
+            return_value={"result": {"value": json.dumps(suggestions)}}
+        )
+        result = asyncio.run(backend.suggest_locator("button", all=True))
+        assert isinstance(result, list)
+        assert len(result) == 4
+        assert result[0] == "#my-id"
+
+    def test_raises_on_element_not_found(self) -> None:
+        """Test that suggest_locator raises ElementNotFoundError when element missing."""
+        backend = _make_cdp_backend()
+        backend._session.runtime.evaluate = AsyncMock(
+            return_value={"result": {"value": None}}
+        )
+        with pytest.raises(ElementNotFoundError):
+            asyncio.run(backend.suggest_locator("#missing"))
+
+
+@pytest.mark.unit
+class TestSuggestLocatorBiDi:
+    """Tests for suggest_locator in BiDi backend."""
+
+    def test_returns_best_selector(self) -> None:
+        """Test that suggest_locator returns the first (best) suggestion."""
+        backend = _make_bidi_backend()
+        suggestions = ["#submit", "button[type='submit']", "button"]
+        result_mock = MagicMock()
+        result_mock.value = json.dumps(suggestions)
+        backend._client.script.evaluate = AsyncMock(return_value=result_mock)
+        result = asyncio.run(backend.suggest_locator("#submit"))
+        assert result == "#submit"
+
+    def test_returns_all_suggestions(self) -> None:
+        """Test that suggest_locator with all=True returns all suggestions."""
+        backend = _make_bidi_backend()
+        suggestions = ["#email", "[data-testid='email']", "input.email", "input"]
+        result_mock = MagicMock()
+        result_mock.value = json.dumps(suggestions)
+        backend._client.script.evaluate = AsyncMock(return_value=result_mock)
+        result = asyncio.run(backend.suggest_locator("input", all=True))
+        assert isinstance(result, list)
+        assert len(result) == 4
+
+    def test_raises_on_element_not_found(self) -> None:
+        """Test that suggest_locator raises ElementNotFoundError when element missing."""
+        backend = _make_bidi_backend()
+        result_mock = MagicMock()
+        result_mock.value = None
+        backend._client.script.evaluate = AsyncMock(return_value=result_mock)
+        with pytest.raises(ElementNotFoundError):
+            asyncio.run(backend.suggest_locator("#missing"))

{wavexis-2.3.3 → wavexis-2.3.5}/wavexis/__init__.py

@@ -1,3 +1,3 @@
 """wavexis — CLI de automatización de navegador."""
 
-__version__ = "2.3.3"
+__version__ = "2.3.5"

{wavexis-2.3.3 → wavexis-2.3.5}/wavexis/backend/base.py

@@ -149,6 +149,66 @@ class AbstractBackend(ABC):
     ) -> None:
         """Scroll to an element or by offset."""
 
+    @abstractmethod
+    async def suggest_locator(
+        self, selector: str, all: bool = False
+    ) -> list[str] | str:
+        """Suggest the best CSS selector for an element.
+
+        Analyzes the element and generates optimal selectors in priority order:
+        id > data-testid > aria-label > text > tag.classes > nth-of-type chain.
+
+        Args:
+            selector: CSS selector for the target element.
+            all: If True, return multiple suggestions; otherwise just the best one.
+
+        Returns:
+            List of selector strings when all=True, single best selector when all=False.
+        """
+
+    @abstractmethod
+    async def find_by_text(
+        self, query: str, all: bool = False
+    ) -> list[str] | str:
+        """Find elements by natural language text query.
+
+        Searches all visible elements by text content, aria-label,
+        placeholder, title, and alt text using fuzzy matching.
+
+        Args:
+            query: Natural language query (e.g. "the login button").
+            all: If True, return all matches; otherwise just the best one.
+
+        Returns:
+            List of CSS selector strings when all=True, single best when all=False.
+
+        Raises:
+            ElementNotFoundError: If no element matches the query.
+        """
+
+    @abstractmethod
+    async def nl_click(
+        self, query: str, auto_wait: bool = True
+    ) -> None:
+        """Click an element found by natural language text query.
+
+        Args:
+            query: Natural language query (e.g. "login button").
+            auto_wait: If True, wait for element to be visible before clicking.
+        """
+
+    @abstractmethod
+    async def nl_fill(
+        self, query: str, value: str, auto_wait: bool = True
+    ) -> None:
+        """Fill an input element found by natural language text query.
+
+        Args:
+            query: Natural language query (e.g. "email field").
+            value: Value to set in the input field.
+            auto_wait: If True, wait for element to be visible before filling.
+        """
+
     # ── Network ────────────────────────────────────────────
 
     @abstractmethod

{wavexis-2.3.3 → wavexis-2.3.5}/wavexis/backend/bidi.py

@@ -537,6 +537,172 @@ class BiDiBackend(AbstractBackend):
             js = f"window.scrollTo({x},{y})"
         await self._client.script.evaluate(self._context, js)
 
+    async def suggest_locator(
+        self, selector: str, all: bool = False
+    ) -> list[str] | str:
+        """Suggest the best CSS selector for an element.
+
+        Args:
+            selector: CSS selector for the target element.
+            all: If True, return multiple suggestions; otherwise just the best one.
+
+        Returns:
+            List of selector strings when all=True, single best selector when all=False.
+        """
+        client = self._require_client()
+        escaped = selector.replace("'", "\\'")
+        js = self._suggest_locator_js(escaped)
+        result = await client.script.evaluate(self._context, js)
+        raw = getattr(result, "value", None)
+        if not raw:
+            raise ElementNotFoundError(selector)
+        suggestions: list[str] = json.loads(raw)
+        if all:
+            return suggestions
+        return suggestions[0] if suggestions else selector
+
+    @staticmethod
+    def _suggest_locator_js(escaped: str) -> str:
+        """Build JS that generates CSS selector suggestions for an element."""
+        return (
+            f"(function(){{"
+            f"var el=document.querySelector('{escaped}');"
+            f"if(!el)return null;"
+            f"var s=[];var t=el.tagName.toLowerCase();"
+            f"var id=el.id;"
+            f"var tid=el.getAttribute('data-testid')"
+            f"||el.getAttribute('data-test-id')"
+            f"||el.getAttribute('data-cy');"
+            f"var aria=el.getAttribute('aria-label');"
+            f"var role=el.getAttribute('role');"
+            f"var txt=(el.textContent||'').trim().substring(0,50);"
+            f"var cls=Array.from(el.classList);"
+            f"if(id)s.push('#'+CSS.escape(id));"
+            f"if(tid)s.push('[data-testid=\"'+tid+'\"]');"
+            f"if(aria)s.push(t+'[aria-label=\"'+aria+'\"]');"
+            f"if(role)s.push(t+'[role=\"'+role+'\"]');"
+            f"if(txt&&txt.length<30)s.push(t+':has-text(\"'+txt+'\"]');"
+            f"if(cls.length>0)s.push(t+'.'+cls.join('.'));"
+            f"var p=el.parentElement;"
+            f"if(p&&p.id)s.push('#'+CSS.escape(p.id)+' > '+t);"
+            f"var sib=p?Array.from(p.children)"
+            f".filter(function(c){{return c.tagName===el.tagName}}):[];"
+            f"if(sib.length>1){{"
+            f"var i=sib.indexOf(el)+1;"
+            f"s.push(t+':nth-of-type('+i+')');}}"
+            f"s.push(t);"
+            f"return JSON.stringify(s);"
+            f"}})()"
+        )
+
+    @staticmethod
+    def _find_by_text_js(query: str) -> str:
+        """Build JS that finds elements by natural language text query."""
+        escaped = query.replace("\\", "\\\\").replace("'", "\\'")
+        return (
+            f"(function(){{"
+            f"var q='{escaped}'.toLowerCase().trim();"
+            f"var words=q.split(/\\s+/);"
+            f"var els=Array.from(document.querySelectorAll('*'));"
+            f"var results=[];"
+            f"for(var i=0;i<els.length;i++){{"
+            f"var el=els[i];"
+            f"var rect=el.getBoundingClientRect();"
+            f"if(rect.width===0||rect.height===0)continue;"
+            f"var texts=["
+            f"(el.textContent||'').trim(),"
+            f"el.getAttribute('aria-label')||'',"
+            f"el.getAttribute('placeholder')||'',"
+            f"el.getAttribute('title')||'',"
+            f"el.getAttribute('alt')||'',"
+            f"el.getAttribute('value')||''"
+            f"].map(function(t){{return t.toLowerCase()}});"
+            f"var bestScore=0;"
+            f"for(var j=0;j<texts.length;j++){{"
+            f"var t=texts[j];if(!t)continue;"
+            f"if(t===q){{bestScore=100;break;}}"
+            f"if(t.indexOf(q)>=0){{bestScore=Math.max(bestScore,80);}}"
+            f"if(q.indexOf(t)>=0&&t.length>3){{bestScore=Math.max(bestScore,60);}}"
+            f"var matched=0;"
+            f"for(var k=0;k<words.length;k++){{"
+            f"if(t.indexOf(words[k])>=0)matched++;"
+            f"}}"
+            f"if(matched>0)bestScore=Math.max(bestScore,"
+            f"Math.round(matched/words.length*50));"
+            f"}}"
+            f"if(bestScore>0){{"
+            f"var tag=el.tagName.toLowerCase();"
+            f"var sel=tag;"
+            f"if(el.id)sel='#'+CSS.escape(el.id);"
+            f"else if(el.getAttribute('data-testid'))"
+            f"sel='[data-testid=\"'+el.getAttribute('data-testid')+'\"]';"
+            f"else if(el.getAttribute('aria-label'))"
+            f"sel=tag+'[aria-label=\"'+el.getAttribute('aria-label')+'\"]';"
+            f"else if(el.classList.length>0)"
+            f"sel=tag+'.'+Array.from(el.classList).join('.');"
+            f"results.push({{score:bestScore,sel:sel}});"
+            f"}}"
+            f"}}"
+            f"results.sort(function(a,b){{return b.score-a.score}});"
+            f"return JSON.stringify(results.map(function(r){{return r.sel}}));"
+            f"}})()"
+        )
+
+    async def find_by_text(
+        self, query: str, all: bool = False
+    ) -> list[str] | str:
+        """Find elements by natural language text query.
+
+        Args:
+            query: Natural language query (e.g. "the login button").
+            all: If True, return all matches; otherwise just the best one.
+
+        Returns:
+            List of CSS selector strings when all=True, single best when all=False.
+
+        Raises:
+            ElementNotFoundError: If no element matches the query.
+        """
+        client = self._require_client()
+        js = self._find_by_text_js(query)
+        result = await client.script.evaluate(self._context, js)
+        raw = getattr(result, "value", None)
+        if not raw:
+            raise ElementNotFoundError(query)
+        selectors: list[str] = json.loads(raw)
+        if not selectors:
+            raise ElementNotFoundError(query)
+        if all:
+            return selectors
+        return selectors[0]
+
+    async def nl_click(
+        self, query: str, auto_wait: bool = True
+    ) -> None:
+        """Click an element found by natural language text query.
+
+        Args:
+            query: Natural language query (e.g. "login button").
+            auto_wait: If True, wait for element to be visible before clicking.
+        """
+        selector = await self.find_by_text(query)
+        assert isinstance(selector, str)
+        await self.click(selector, auto_wait=auto_wait)
+
+    async def nl_fill(
+        self, query: str, value: str, auto_wait: bool = True
+    ) -> None:
+        """Fill an input element found by natural language text query.
+
+        Args:
+            query: Natural language query (e.g. "email field").
+            value: Value to set in the input field.
+            auto_wait: If True, wait for element to be visible before filling.
+        """
+        selector = await self.find_by_text(query)
+        assert isinstance(selector, str)
+        await self.fill(selector, value, auto_wait=auto_wait)
+
     async def capture_har(self, params: HarParams) -> dict[str, Any]:
         """Capture HAR data via CDP Network domain.