seleniumbase 4.54.1__tar.gz → 4.54.3__tar.gz

{seleniumbase-4.54.1/seleniumbase.egg-info → seleniumbase-4.54.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: seleniumbase
-Version: 4.54.1
+Version: 4.54.3
 Summary: SeleniumBase is a framework for web crawling, scraping, and testing. Supports pytest. CDP Mode adds stealth. Includes many tools.
 Home-page: https://github.com/seleniumbase/SeleniumBase
 Author: Michael Mintz
@@ -171,6 +171,7 @@ Dynamic: requires-python
 Dynamic: summary
 
 <!-- SeleniumBase Docs -->
+<!-- mcp-name: io.github.seleniumbase/seleniumbase -->
 
 <meta property="og:site_name" content="SeleniumBase">
 <meta property="og:title" content="SeleniumBase: Stealthy Chromium Automation with Python; and E2E Testing." />

{seleniumbase-4.54.1 → seleniumbase-4.54.3}/README.md

@@ -1,4 +1,5 @@
 <!-- SeleniumBase Docs -->
+<!-- mcp-name: io.github.seleniumbase/seleniumbase -->
 
 <meta property="og:site_name" content="SeleniumBase">
 <meta property="og:title" content="SeleniumBase: Stealthy Chromium Automation with Python; and E2E Testing." />

{seleniumbase-4.54.1 → seleniumbase-4.54.3}/mcp_servers/server.py

@@ -34,7 +34,8 @@ having to choose between multiple near-identical tools.
 
 Tool-selection philosophy:
 - Use 'start_browser'/'close_browser' for opening/quitting the web browser.
-- Use 'navigate'/'manage_history' for browser navigation & history inspection.
+- Use 'goto_url'/'manage_history' for browser navigation and history
+  inspection.
 - Use 'get_page_info' for reading browser/page metadata such as URL/title.
 - Use 'get_content'/'get_attributes' for reading text, HTML, or attributes.
 - Use 'find_elements' for discovering and inspecting multiple matching
@@ -43,11 +44,12 @@ Tool-selection philosophy:
 - Use 'wait_for' when the agent needs to wait for a condition to become true.
 - Use 'assert_condition' when the agent needs to verify an expected condition
   and treat failure as an assertion error.
-- Use 'click'/'type_text'/'select_option' for standard page interactions.
+- Use 'click_element'/'type_text'/'select_option' for standard page
+  interactions.
 - Use 'hover_action' for just a hover, with a click, or with a drag/drop.
-- Use 'focus' for element positioning and visual focus.
+- Use 'focus_element' for element positioning and visual focus.
 - Use 'solve_captcha' for clicking the checkbox of a CAPTCHA on the page.
-- Use 'save_output' for saving page output as a PNG, a PDF, or an HTML file.
+- Use 'save_page' for saving page output as a PNG, a PDF, or an HTML file.
 """
 from __future__ import annotations
 import atexit
@@ -109,8 +111,8 @@ def start_browser(
 ) -> str:
     """Launch a persistent SeleniumBase Pure CDP Mode browser session.
 
-    Call this before using browser interaction tools such as navigate,
-    get_content, click, type_text, or find_elements. The same browser
+    Call this before using browser interaction tools such as goto_url,
+    get_content, click_element, type_text, or find_elements. The same browser
     session remains active across subsequent MCP tool calls until
     close_browser is called or the server process exits.
 
@@ -336,7 +338,7 @@ def get_page_info() -> dict[str, Any]:
 
 @mcp.tool()
 @handle_sb_errors
-def navigate(url: str) -> str:
+def goto_url(url: str) -> str:
     """Navigate the current browser tab to a URL.
 
     Use this when the browser needs to visit a new URL rather than move
@@ -358,7 +360,7 @@ def navigate(url: str) -> str:
         A confirmation message containing the requested URL.
 
     Tool selection:
-        - Go to a new URL -> use navigate.
+        - Go to a new URL -> use goto_url.
         - Return to the previous page -> use manage_history(action="back").
         - Go forward in history -> use manage_history(action="forward").
         - Refresh the current page -> use manage_history(action="reload").
@@ -377,7 +379,7 @@ def manage_history(
 
     Use 'back' or 'forward' for history navigation, 'reload' to refresh
     while bypassing the cache, or 'list' to inspect history.
-    Use 'navigate' for an arbitrary URL.
+    Use 'goto_url' for navigation to an arbitrary URL.
 
     Args:
         action:
@@ -446,10 +448,16 @@ def find_elements(
     dictionaries. It does not return live SeleniumBase element objects.
 
     Args:
-        selector: A SeleniumBase-supported selector, typically CSS or XPath.
+        selector: A CSS selector, or an XPath selector that SeleniumBase can
+            convert to CSS. In sb.find_elements, SeleniumBase automatically
+            attempts to convert XPath to CSS. Some XPath expressions, such
+            as those using `contains(...)`, cannot be converted to CSS and
+            therefore aren't supported by this tool.
 
         timeout: Maximum number of seconds to wait for at least one matching
-            element to appear.
+            element to appear. If the selector is an XPath selector that
+            cannot be converted into a valid CSS selector, then the wait
+            might be less than the timeout.
 
         include_html: If True, include each matching element's outer HTML.
             If False, return only tag name and text.
@@ -459,115 +467,102 @@ def find_elements(
         - count: Number of matching elements found.
         - matches: A list of element dictionaries containing tag_name and
           text, plus html when include_html=True.
-        If there's an error, returns a string with error details.
+        If there's an error during search, then "error" is added into the
+        returned dictionary with error details.
 
     Tool selection:
         - Need structured information about matching elements ->
           use find_elements.
         - Need the visible text/HTML of a page or a single element ->
           use get_content.
-        - Need to click one of several matches -> use click with nth.
+        - Need to click one of several matches -> use click_element with nth.
         - Need to know whether an element is present/visible ->
           use check_condition.
 
-    Note:
+    Notes:
         Element handles cannot be persisted across MCP calls. If you find
         elements and then need to act on one, resolve it again with the
         appropriate interaction tool.
+
+        For uncaught errors, @handle_sb_errors returns strings.
     """
     sb = _get_sb()
-    elements = sb.find_elements(selector, timeout=timeout)
-
-    if include_html:
+    try:
+        elements = sb.find_elements(selector, timeout=timeout)
+    except Exception as e:
         return {
-            "count": len(elements),
-            "matches": [
-                {
-                    "tag_name": element.tag_name,
-                    "text": element.text,
-                    "html": element.get_html(),
-                }
-                for element in elements
-            ],
+            "count": 0,
+            "matches": [],
+            "error": str(e),
+        }
+
+    matches = []
+    for element in elements:
+        match = {
+            "tag_name": element.tag_name,
+            "text": element.text,
         }
+        if include_html:
+            match["html"] = element.get_html()
+        matches.append(match)
 
     return {
-        "count": len(elements),
-        "matches": [
-            {
-                "tag_name": element.tag_name,
-                "text": element.text,
-            }
-            for element in elements
-        ],
+        "count": len(matches),
+        "matches": matches,
     }
 
 
 @mcp.tool()
 @handle_sb_errors
 def get_content(
-    selector: str | None = None,
+    selector: str = "body",
     output_format: Literal["text", "html", "urls"] = "text",
-    include_shadow_dom: bool = True,
+    timeout: float = 5,
 ) -> str | list[str]:
-    """Read visible text, HTML, or discovered URLs from the current page.
+    """Read visible text, HTML, or discovered URLs from the selected element.
 
-    Use this tool when you need actual page content or URL information rather
-    than page metadata.
+    Use this tool when you need to get actual page content or URL information
+    rather than page metadata.
 
     Args:
-        selector: Optional CSS selector or SeleniumBase text-matching selector
-            identifying the element whose content should be read. For
-            output_format="text" or "html", the selector scopes the returned
-            content to that element. For output_format="urls", the selector
-            scopes URL discovery to URLs within that element. When omitted,
-            the operation applies to the whole page.
+        selector: CSS selector or SeleniumBase-supported XPath selector.
+            Default: "body".
 
         output_format:
-            - "text": Return visible text from the page or selected element.
-            - "html": Return HTML from the page or selected element.
-            - "urls": Return URLs discovered by SeleniumBase from the page
-              or selected element. URLs associated with elements such as
-              anchors, links, images, scripts, and metadata may be included.
-              SeleniumBase returns full URLs with their URL protocol prefixes.
-
-        include_shadow_dom: When output_format="html" and selector is omitted,
-            include any shadow-root HTML present in the page. This option has
-            no effect for "text" or "urls", or when a selector is specified.
+            - "text": Return visible text from the selected element.
+            - "html": Return HTML from the selected element.
+            - "urls": Return URLs discovered by SeleniumBase within the
+              selected element. Returned URLs are normalized to full URLs
+              with their protocol prefixes.
 
-    Returns:
-        For output_format="text", a string containing visible text.
-        For output_format="html", a string containing HTML.
-        For output_format="urls", a list of URL strings. This is useful for
-        crawling, link discovery, resource inspection, and finding candidate
-        URLs before navigating to them.
+        timeout: Maximum seconds to wait for the target element. Default: 5.
 
     Tool selection:
         - Need URL, title, origin, or User-Agent -> use get_page_info.
-        - Need visible text -> use output_format="text".
-        - Need page or element HTML -> use output_format="html".
-        - Need URLs from the page or an element -> use output_format="urls".
+        - Need visible text, html, or URLs on a page -> use get_content.
         - Need structured information about matching elements ->
           use find_elements.
         - Need to check element presence/visibility -> use check_condition.
         - Need to wait for content to appear -> use wait_for.
+
+    If there's no matching element found within the timeout,
+        then @handle_sb_errors returns details from the exception raised.
     """
     sb = _get_sb()
 
-    if output_format == "urls":
-        return sb.get_all_urls(selector=selector)
-
-    if selector is None:
-        if output_format == "html":
-            return sb.get_page_source(
-                include_shadow_dom=include_shadow_dom
-            )
-        return sb.get_text("body")
+    if output_format == "text":
+        return sb.get_text(selector, timeout=timeout)
 
     if output_format == "html":
-        return sb.get_element_html(selector)
+        return sb.get_element_html(selector, timeout=timeout)
 
-    return sb.get_text(selector)
+    if output_format == "urls":
+        return sb.get_all_urls(selector=selector, timeout=timeout)
+
+    return (
+        f"Error: unknown output_format '{output_format}'. "
+        "Use 'text', 'html', or 'urls'."
+    )
 
 
 @mcp.tool()
@@ -575,22 +570,21 @@ def get_content(
 def get_attributes(
     selector: str,
     attribute: str | None = None,
-) -> Any:
-    """Read HTML attributes from a matching element.
+    timeout: float = 5,
+) -> str | dict[str, Any] | None:
+    """Read HTML attributes from the first matching element.
 
-    Use this tool when you need the value of one or more HTML attributes
-    such as href, src, value, class, id, name, type, aria-label, or data-*.
+    Use this tool when you need the value of a specific HTML attribute,
+    or all HTML attributes of an element. Attributes could be something
+    such as href, src, value, class, id, name, type, aria-label, etc.
 
     Args:
-        selector: CSS selector or SeleniumBase text-matching selector for
-            the target element.
+        selector: CSS selector or SeleniumBase-supported XPath selector.
 
         attribute: Specific HTML attribute to retrieve. When omitted, return
-            all HTML attributes of the element as a dictionary.
+            all HTML attributes of the first matching element as a dictionary.
 
-    Returns:
-        The requested attribute value, or a dictionary containing all
-        HTML attributes of the element when attribute is omitted.
+        timeout: Maximum seconds to wait for the target element. Default: 5.
 
     Tool selection:
         - Need one or more HTML attribute values from a specific element ->
@@ -601,13 +595,16 @@ def get_attributes(
         - Need to check element presence/visibility -> use 'check_condition'.
 
     This is a read-only operation.
+
+    If there's no matching element found within the timeout,
+        then @handle_sb_errors returns details from the exception raised.
     """
     sb = _get_sb()
 
     if attribute:
-        return sb.get_attribute(selector, attribute)
+        return sb.get_attribute(selector, attribute, timeout=timeout)
 
-    return sb.get_element_attributes(selector)
+    return sb.get_element_attributes(selector, timeout=timeout)
 
 
 @mcp.tool()
@@ -683,7 +680,7 @@ def check_condition(
 
 @mcp.tool()
 @handle_sb_errors
-def click(
+def click_element(
     selector: str,
     nth: int | None = None,
     all_matches: bool = False,
@@ -736,11 +733,14 @@ def click(
             indexed click. Default: True.
 
     Examples:
-        - Click one element: `click("button.submit")`
-        - Click the 2nd matching element: `click("button", nth=2)`
-        - Click all visible matches: `click(".dismiss", all_matches=True)`
-        - Click only if already visible: `click("#menu", only_if_visible=True)`
-        - Click inside a container: `click(".item", parent_selector="#result")`
+        - Click one element: `click_element("button.submit")`
+        - Click the 2nd matching element: `click_element("button", nth=2)`
+        - Click all visible matches:
+          `click_element(".dismiss", all_matches=True)`
+        - Click only if already visible:
+          `click_element("#menu", only_if_visible=True)`
+        - Click inside a container:
+          `click_element(".item", parent_selector="#result")`
     """
     sb = _get_sb()
 
@@ -771,11 +771,7 @@ def click(
 def hover_action(
     selector1: str,
     selector2: str | None = None,
-    action: Literal[
-        "none",
-        "click",
-        "drag_and_drop",
-    ] = "none",
+    action: Literal["hover", "hover_and_click", "drag_and_drop"] = "hover",
 ) -> str:
     """Hover over an element, optionally click another, or drag-and-drop.
 
@@ -785,46 +781,39 @@ def hover_action(
     Args:
         selector1:
             The primary element selector.
-            For action="none", this is the element to hover over.
-            For action="click", this is the element to hover over before
-            clicking selector2.
+            For action="hover", this is the element to hover over.
+            For action="hover_and_click", this is the element to hover over
+            before clicking selector2.
             For action="drag_and_drop", this is the draggable source element.
 
         selector2:
             The secondary element selector.
-            Required for action="click", where it identifies the element
-            revealed or targeted after hovering selector1.
+            Required for action="hover_and_click", where it identifies
+            the element revealed or targeted after hovering selector1.
             Required for action="drag_and_drop", where it identifies the
             destination/drop target.
-            Not used for action="none".
+            Not used for action="hover".
 
         action:
-            - "none": Hover over selector1 only.
-            - "click": Hover over selector1, then click selector2.
+            - "hover": Hover over selector1 only.
+            - "hover_and_click": Hover over selector1, then click selector2.
             - "drag_and_drop": Drag selector1 and drop it onto selector2.
 
     Returns:
         A confirmation message describing the performed operation.
 
     Tool selection:
-        - Simple hover -> action="none".
-        - Hover over one element and then click another -> action="click".
+        - Simple hover -> action="hover".
+        - Hover over one element and click another -> action="hover_and_click".
         - Drag one element onto another -> action="drag_and_drop".
-
-    Notes:
-        For action="click", selector1 is the hover target and selector2 is
-        the click target.
-
-        For action="drag_and_drop", selector1 is the source and selector2
-        is the destination.
     """
     sb = _get_sb()
 
-    if action == "none":
+    if action == "hover":
         sb.hover_element(selector1)
         return f"Hovered {selector1}"
 
-    if action == "click":
+    if action == "hover_and_click":
         if selector2 is None:
             return "Error: action='click' requires selector2."
         sb.hover_and_click(selector1, selector2)
@@ -838,7 +827,7 @@ def hover_action(
 
     return (
         f"Error: unknown action '{action}'. "
-        "Use 'none', 'click', or 'drag_and_drop'."
+        "Use 'hover', 'hover_and_click', or 'drag_and_drop'."
     )
 
 
@@ -937,8 +926,8 @@ def select_option(
         An error when the dropdown or requested option cannot be found.
 
     This tool is for native <select> elements. For custom JavaScript
-    dropdowns made from div/button/list elements, use click or other
-    element-interaction tools instead.
+    dropdowns made from div/button/list elements, use click_element
+    or other element-interaction tools instead.
     """
     sb = _get_sb()
 
@@ -956,18 +945,20 @@ def select_option(
 
 @mcp.tool()
 @handle_sb_errors
-def focus(
+def focus_element(
     selector: str,
     action: Literal[
         "scroll_to_element",
         "focus",
         "highlight",
     ] = "scroll_to_element",
+    timeout: float = 5,
 ) -> str:
     """Scroll to, focus, or highlight an element.
 
     This tool does not click, type, select, hover, or otherwise activate the
-    element. Use `click`, `type_text`, or `hover_action` for those operations.
+    element. Use `click_element`, `type_text`, or `hover_action` for those
+    operations.
 
     Args:
         selector: CSS selector or SeleniumBase selector identifying the target.
@@ -976,16 +967,22 @@ def focus(
             - "scroll_to_element": Scroll the element into the viewport.
             - "focus": Move keyboard focus to the element.
             - "highlight": Temporarily highlight the element for debugging or
-              demonstration. May affect timing and reduce stealth.
+              demonstration by changing the border color. May affect timing
+              and/or reduce stealth.
+
+        timeout: Maximum seconds to wait for the target element. Default: 5.
+
+    If there's no matching element found within the timeout,
+        then @handle_sb_errors returns details from the exception raised.
     """
     sb = _get_sb()
 
     if action == "scroll_to_element":
-        sb.scroll_into_view(selector)
+        sb.scroll_into_view(selector, timeout=timeout)
     elif action == "focus":
-        sb.find_element(selector).focus()
+        sb.find_element(selector, timeout=timeout).focus()
     elif action == "highlight":
-        sb.highlight(selector)
+        sb.highlight(selector, timeout=timeout)
     else:
         return (
             f"Error: unknown action '{action}'. "
@@ -1375,7 +1372,7 @@ def manage_storage(
 
 @mcp.tool()
 @handle_sb_errors
-def scroll(
+def scroll_page(
     direction: Literal["up", "down", "top", "bottom"] = "down",
     amount: int = 25,
 ) -> str:
@@ -1395,8 +1392,8 @@ def scroll(
     Values greater than 100 for `amount` are allowed.
     For example, 200 means approximately two viewport heights.
 
-    Use focus(action="scroll_to_element") when the goal is to reveal a
-    specific element rather than scroll the page by a relative amount.
+    Use focus_element(action="scroll_to_element") when the goal is to reveal
+    a specific element rather than scroll the page by a relative amount.
     """
     sb = _get_sb()
 
@@ -1502,7 +1499,7 @@ def manage_tabs(
     """Manage browser tabs, including opening new ones.
 
     Use this for listing, opening, switching, or closing tabs.
-    Use `navigate` and `manage_history` for navigation within the active tab.
+    Use `goto_url` and `manage_history` for navigation within the active tab.
 
     Args:
         action:
@@ -1617,7 +1614,7 @@ def solve_captcha() -> str:
 
 @mcp.tool()
 @handle_sb_errors
-def save_output(
+def save_page(
     format: Literal["screenshot", "html", "pdf"] = "screenshot",
     filename: str | None = None,
     folder: str | None = None,
@@ -1669,7 +1666,7 @@ def save_output(
         - Do not use this tool when you only need page metadata such as the
           URL or title; use get_page_info instead.
         - Do not use this tool to manipulate the page; use the appropriate
-          interaction tool such as click, type_text, or select_option.
+          interaction tool such as click_element, type_text, or select_option.
 
     Returns:
         A confirmation message containing the requested output format and
@@ -1709,9 +1706,9 @@ def run_javascript(expression: str) -> Any:
     and other same-origin page resources available to JavaScript.
 
     Tool selection:
-        - Prefer click, type_text, select_option, hover_action,
-          focus, scroll, and other higher-level tools for normal browser
-          interactions.
+        - Prefer click_element, type_text, select_option, hover_action,
+          focus_element, scroll_page, and other higher-level tools for normal
+          browser interactions.
         - Prefer get_content, get_attributes, and find_elements for reading
           page content or element information.
         - Prefer manage_storage for ordinary localStorage/sessionStorage

{seleniumbase-4.54.1 → seleniumbase-4.54.3}/seleniumbase/__version__.py

@@ -1,2 +1,2 @@
 # seleniumbase package
-__version__ = "4.54.1"
+__version__ = "4.54.3"

{seleniumbase-4.54.1 → seleniumbase-4.54.3}/seleniumbase/core/sb_cdp.py

@@ -827,7 +827,7 @@ class CDPMethods():
             driver = driver.cdp_base
         return self.loop.run_until_complete(driver.reset_permissions())
 
-    def get_all_urls(self, absolute=True, selector=None):
+    def get_all_urls(self, absolute=True, selector=None, timeout=None):
         """
         Convenience function that returns all links (a,link,img,script).
         :param absolute:
@@ -838,13 +838,15 @@ class CDPMethods():
          instead of the entire page.
         :return: List of URLs.
         """
+        if not timeout:
+            timeout = settings.SMALL_TIMEOUT
         if isinstance(absolute, str) and selector is None:
             # The `selector` is usually first, so the user may get confused.
             # Therefore, if first arg is string, it's probably the selector.
             selector = absolute
             absolute = True
         if selector:
-            html = self.find_element(selector).get_html()
+            html = self.find_element(selector, timeout=timeout).get_html()
             soup = self.get_beautiful_soup(html)
             page_url = self.get_current_url()
             return page_utils._get_unique_links(page_url, soup)
@@ -1876,8 +1878,11 @@ class CDPMethods():
     def get_flattened_document(self):
         return self.loop.run_until_complete(self.page.get_flattened_document())
 
-    def get_element_attributes(self, selector):
+    def get_element_attributes(self, selector, timeout=None):
+        if not timeout:
+            timeout = settings.SMALL_TIMEOUT
         selector = self.__convert_to_css_if_xpath(selector)
+        self.find_element(selector, timeout=timeout)
         return self.loop.run_until_complete(
             self.page.js_dumps(
                 """document.querySelector('%s')"""
@@ -1885,10 +1890,13 @@ class CDPMethods():
             )
         )
 
-    def get_element_attribute(self, selector, attribute):
+    def get_element_attribute(self, selector, attribute, timeout=None):
         """Find an element and return the value of an attribute.
         Raises an exception if there's no such element or attribute."""
-        attributes = self.get_element_attributes(selector)
+        if not timeout:
+            timeout = settings.SMALL_TIMEOUT
+        selector = self.__convert_to_css_if_xpath(selector)
+        attributes = self.get_element_attributes(selector, timeout=timeout)
         with suppress(Exception):
             return attributes[attribute]
         locate = ' %s="' % attribute
@@ -3685,8 +3693,10 @@ class CDPMethods():
         with suppress(Exception):
             self.loop.run_until_complete(self.page.evaluate(js_code))
 
-    def scroll_into_view(self, selector):
-        self.find_element(selector).scroll_into_view()
+    def scroll_into_view(self, selector, timeout=None):
+        if not timeout:
+            timeout = settings.SMALL_TIMEOUT
+        self.find_element(selector, timeout=timeout).scroll_into_view()
         self.loop.run_until_complete(self.page.wait(0.05))
 
     def scroll_to_y(self, y):

{seleniumbase-4.54.1 → seleniumbase-4.54.3/seleniumbase.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: seleniumbase
-Version: 4.54.1
+Version: 4.54.3
 Summary: SeleniumBase is a framework for web crawling, scraping, and testing. Supports pytest. CDP Mode adds stealth. Includes many tools.
 Home-page: https://github.com/seleniumbase/SeleniumBase
 Author: Michael Mintz
@@ -171,6 +171,7 @@ Dynamic: requires-python
 Dynamic: summary
 
 <!-- SeleniumBase Docs -->
+<!-- mcp-name: io.github.seleniumbase/seleniumbase -->
 
 <meta property="og:site_name" content="SeleniumBase">
 <meta property="og:title" content="SeleniumBase: Stealthy Chromium Automation with Python; and E2E Testing." />