wavexis 2.2.4__tar.gz → 2.2.5__tar.gz

{wavexis-2.2.4 → wavexis-2.2.5}/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to wavexis are documented in this file.
 
+## v2.2.5 — 2026-07-07
+
+### Improved
+
+- Error messages now include actionable hints for common failures
+- `ElementNotFoundError` suggests `wavexis dom` and `wavexis screenshot` for debugging
+- `WaitTimeoutError` suggests increasing `--timeout` and alternative wait strategies
+- `NavigationError` suggests checking URL, `--timeout`, and `--proxy`
+- `SessionNotInitializedError` suggests `--headed` and checking Chromium installation
+- `BackendNotAvailableError` shows install commands for both backends
+- `MultiConfigError` suggests `--dry-run` to validate config
+
 ## v2.2.4 — 2026-07-07
 
 ### Added

{wavexis-2.2.4 → wavexis-2.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wavexis
-Version: 2.2.4
+Version: 2.2.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.2.4 → wavexis-2.2.5}/pyproject.toml

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

{wavexis-2.2.4 → wavexis-2.2.5}/wavexis/__init__.py

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

{wavexis-2.2.4 → wavexis-2.2.5}/wavexis/cli/_shared.py

@@ -21,6 +21,7 @@ from wavexis.exceptions import (
     ElementNotFoundError,
     MultiConfigError,
     NavigationError,
+    SessionNotInitializedError,
     WaitTimeoutError,
     WavexisError,
 )
@@ -39,6 +40,7 @@ __all__ = [
     "MultiConfigError",
     "NavigationError",
     "Output",
+    "SessionNotInitializedError",
     "WaitTimeoutError",
     "WavexisError",
     "_browser_options",
@@ -209,20 +211,28 @@ def _handle_error(e: Exception) -> None:
     """
     if isinstance(e, BackendNotAvailableError):
         Output.error(
-            "No backend available. Install cdpwave: pip install wavexis[cdp]"
+            "No backend available.\n"
+            "Hint: Install cdpwave with `pip install wavexis[cdp]`, "
+            "or bidiwave with `pip install wavexis[bidi]`."
         )
         raise typer.Exit(EXIT_BACKEND_ERROR) from e
+    if isinstance(e, SessionNotInitializedError):
+        Output.error(str(e))
+        raise typer.Exit(EXIT_BROWSER_ERROR) from e
     if isinstance(e, NavigationError):
-        Output.error(f"Navigation failed: {e}")
+        Output.error(str(e))
         raise typer.Exit(EXIT_BROWSER_ERROR) from e
     if isinstance(e, WaitTimeoutError):
-        Output.error(f"Timeout waiting: {e}")
+        Output.error(str(e))
         raise typer.Exit(EXIT_BROWSER_ERROR) from e
     if isinstance(e, ElementNotFoundError):
-        Output.error(f"Element not found: {e}")
+        Output.error(str(e))
         raise typer.Exit(EXIT_BROWSER_ERROR) from e
     if isinstance(e, MultiConfigError):
-        Output.error(f"Invalid multi config: {e}")
+        Output.error(
+            f"Invalid multi config: {e}\n"
+            "Hint: Run `wavexis multi <config> --dry-run` to validate the config."
+        )
         raise typer.Exit(EXIT_CONFIG_ERROR) from e
     if isinstance(e, WavexisError):
         Output.error(str(e))

{wavexis-2.2.4 → wavexis-2.2.5}/wavexis/exceptions.py

@@ -41,6 +41,21 @@ class BackendNotSupportedError(WavexisError):
 class SessionNotInitializedError(WavexisError):
     """Raised when a backend method is called before launch()."""
 
+    def __init__(self, msg: str | None = None) -> None:
+        """Initialize the error.
+
+        Args:
+            msg: Optional custom message.
+        """
+        if msg:
+            super().__init__(msg)
+        else:
+            super().__init__(
+                "Browser session not initialized. Call launch() first.\n"
+                "Hint: This usually means the browser failed to start. "
+                "Try --headed to see the browser window, or check if Chromium is installed."
+            )
+
 
 class NavigationError(WavexisError):
     """Raised when navigation fails or times out."""
@@ -52,7 +67,11 @@ class NavigationError(WavexisError):
             url: The URL that failed to navigate to.
             reason: The failure reason.
         """
-        super().__init__(f"Navigation to '{url}' failed: {reason}")
+        super().__init__(
+            f"Navigation to '{url}' failed: {reason}\n"
+            f"Hint: Check the URL is reachable, try --timeout 60000, "
+            f"or use --proxy if behind a firewall."
+        )
 
 
 class WaitTimeoutError(WavexisError):
@@ -66,7 +85,9 @@ class WaitTimeoutError(WavexisError):
             timeout_ms: The timeout duration in milliseconds.
         """
         super().__init__(
-            f"Wait strategy '{strategy}' timed out after {timeout_ms}ms"
+            f"Wait strategy '{strategy}' timed out after {timeout_ms}ms\n"
+            f"Hint: Increase timeout with --timeout {max(timeout_ms * 2, 60000)}, "
+            f"or use a different wait strategy (load, domcontentloaded, networkidle)."
         )
 
 
@@ -79,7 +100,11 @@ class ElementNotFoundError(WavexisError):
         Args:
             selector: The CSS selector that matched no elements.
         """
-        super().__init__(f"No element found matching selector: {selector}")
+        super().__init__(
+            f"No element found matching selector: {selector}\n"
+            f"Hint: Verify the selector with `wavexis dom --selector '{selector}'`, "
+            f"or use `wavexis screenshot` to inspect the page visually."
+        )
 
 
 class ActionError(WavexisError):