BrowserJQuery API Documentation

Overview

BrowserJQuery is a Python library that provides jQuery-like functionality for browser automation using Selenium WebDriver. It allows you to interact with web elements using familiar jQuery-style selectors and methods.

Core Classes

BrowserJQuery

The main class for jQuery-based browser interactions.

Initialization

from browserjquery import BrowserJQuery
from selenium import webdriver

driver = webdriver.Chrome()  # or Firefox
browser = BrowserJQuery(driver)

Core Methods

Element Finding

find(selector: str) -> BrowserJQueryCollection: Find elements using jQuery selector
find_elements_with_text(text: str, selector: str = "*") -> BrowserJQueryCollection: Find elements containing specific text
find_lowest_element_with_text(text: str, selector: str = "*", exact_match: bool = False) -> BrowserJQuery: Find the lowest element containing text
find_elements_with_selector_and_text(selector: str, text: str, exact_match: bool = False) -> BrowserJQueryCollection: Find elements matching both selector and text

Element Traversal

parent() -> BrowserJQuery: Get the parent element
parents() -> list[BrowserJQuery]: Get all parent elements
children(selector: str | None = None) -> list[BrowserJQuery]: Get direct children
siblings(selector: str | None = None) -> list[BrowserJQuery]: Get sibling elements
next(selector: str | None = None) -> BrowserJQuery: Get next sibling
prev(selector: str | None = None) -> BrowserJQuery: Get previous sibling

Element State

has_class(class_name: str) -> bool: Check if element has a class
matches_selector(selector: str) -> bool: Check if element matches selector
has(selector: str) -> bool: Check if element has matching descendants
is_visible() -> bool: Check if element is visible
is_checked() -> bool: Check if checkbox/radio is checked
is_disabled() -> bool: Check if element is disabled

Element Properties

attr(attribute_name: str) -> str | None: Get attribute value
text() -> str: Get text content
html() -> str: Get HTML content

BrowserJQueryCollection

A collection of elements that can be filtered and transformed.

Methods

__len__() -> int: Get number of elements
__iter__(): Iterate over elements
__getitem__(index: int) -> BrowserJQuery: Get element by index
first() -> BrowserJQuery: Get first element
last() -> BrowserJQuery: Get last element
items() -> list[BrowserJQuery]: Get all elements

Usage Examples

Basic Element Selection

# Find elements by selector
elements = browser.find(".my-class")
first_element = elements.first()

# Find elements with specific text
elements_with_text = browser.find_elements_with_text("Click me")

Element Traversal

# Get parent element
parent = element.parent()

# Get all children
children = element.children()

# Get siblings
siblings = element.siblings()

Element State Checking

# Check element state
if element.is_visible():
    if element.has_class("active"):
        print(element.text())

Attribute Access

# Get element attributes
href = element.attr("href")
text = element.text()
html = element.html()

jQuery Integration

The library automatically injects jQuery into the page if it’s not already present. You can control this behavior:

# Check if jQuery is injected
if browser.is_jquery_injected:
    print("jQuery is available")

# Manually inject jQuery
browser.inject_jquery(by="file")  # or "cdn"

class browserjquery.jquery.BrowserJQuery(driver: WebDriver | WebDriver, default_element=None)

Bases: object

Main class for jQuery-based browser interactions.

attr(attribute_name: str) → str | None

Get attribute value of element.

Args:: attribute_name: Name of the attribute.
Returns:: The attribute value or None if not found.

children(selector: str | None = None) → list[WebElement]

Get direct children of element.

Args:: selector: Optional selector to filter children.
Returns:: List of child WebElements.

property document

Get the document element wrapped in jQuery.

Returns:: The document element as a jQuery object.

ensure_jquery()

Ensures that jQuery is injected into the page.

Returns:: bool: True if jQuery is successfully injected, False otherwise.

execute(script, *args, **kwargs)

Execute JavaScript on the page.

Args:: script: The JavaScript code to execute. *args: Additional arguments to pass to the script.
Returns:: The result of the JavaScript execution.

find(selector: str) → list[WebElement] | WebElement | None

Find elements using jQuery selector.

Args:: selector: jQuery selector to find elements.
Returns:: A BrowserJQueryCollection of matching elements.

find_closest_ancestor(selector: str) → WebElement | None

Find the closest ancestor matching the selector.

Args:: selector: jQuery selector to match ancestor.
Returns:: The closest matching ancestor WebElement or None if not found.

find_elements_with_selector_and_text(selector: str, text: str, *, exact_match: bool = False) → list[WebElement] | WebElement | None

Find elements matching both selector and text criteria.

Args:: selector: jQuery selector to filter elements. text: Text to search for. exact_match: Whether to require an exact text match.
Returns:: A BrowserJQueryCollection of matching elements.

find_elements_with_text(text: str, selector: str = '*') → list[WebElement] | WebElement | None

Find elements containing specific text.

Args:: text: Text to search for. selector: jQuery selector to filter elements.
Returns:: A BrowserJQueryCollection of matching elements.

find_lowest_element_with_text(text: str, selector: str = '*', *, exact_match: bool = False) → WebElement | None

Find the lowest element in the DOM tree containing specific text.

Args:: text: Text to search for. selector: jQuery selector to filter elements. exact_match: Whether to require an exact text match.
Returns:: The lowest matching WebElement or None if not found.

first() → WebElement | None

Get the first child element of the default element.

Returns:: The first child WebElement or None if no children exist.

has(selector: str) → bool

Check if element has descendants matching selector.

Args:: selector: jQuery selector to match descendants.
Returns:: bool: True if element has matching descendants, False otherwise.

has_class(class_name: str) → bool

Check if element has a specific class.

Args:: class_name: Class name to look for.
Returns:: bool: True if element has the class, False otherwise.

html() → str

Get HTML content of element.

Returns:: The HTML content of the element.

inject_jquery(by: str = 'file', wait: int = 5) → bool

Inject jQuery into the current page.

Args:: by: Method of injection, either “file” or “cdn”. wait: Time to wait after injection in seconds.
Returns:: bool: True if jQuery was successfully injected, False otherwise.

is_checked() → bool

Check if checkbox/radio is checked.

Returns:: bool: True if element is checked, False otherwise.

is_disabled() → bool

Check if element is disabled.

Returns:: bool: True if element is disabled, False otherwise.

property is_jquery_injected: bool

Check if jQuery is already injected into the page.

Returns:: bool: True if jQuery is present, False otherwise.

is_visible() → bool

Check if element is visible.

Returns:: bool: True if element is visible, False otherwise.

items() → list[WebElement]

Get all child elements of the default element.

Returns:: List of child WebElements.

last() → WebElement | None

Get the last child element of the default element.

Returns:: The last child WebElement or None if no children exist.

matches_selector(selector: str) → bool

Check if element matches a selector.

Args:: selector: jQuery selector to match against.
Returns:: bool: True if element matches selector, False otherwise.

next(selector: str | None = None) → WebElement | None

Get next sibling element.

Args:: selector: Optional selector to filter next sibling.
Returns:: The next sibling WebElement or None if not found.

property page_html: str

Get the complete HTML of the current page.

Returns:: str: The HTML content of the page.

parent() → WebElement

Get the parent element.

Returns:: The parent WebElement.

parents() → list[WebElement]

Get all parent elements.

Returns:: List of parent WebElements.

prev(selector: str | None = None) → WebElement | None

Get previous sibling element.

Args:: selector: Optional selector to filter previous sibling.
Returns:: The previous sibling WebElement or None if not found.

query(script: str, element: WebElement | None = None, *args, **kwargs)

Execute jQuery script on an element.

Args:: script: The jQuery script to execute. element: The WebElement to execute the script on. If None, uses default_element. *args: Additional arguments to pass to the script. **kwargs: Additional keyword arguments.
Returns:: The result of the jQuery script execution.

siblings(selector: str | None = None) → list[WebElement]

Get sibling elements.

Args:: selector: Optional selector to filter siblings.
Returns:: List of sibling WebElements.

text() → str

Get text content of element.

Returns:: The text content of the element.

class browserjquery.jquery.BrowserJQueryCollection(driver: WebDriver | WebDriver, elements: list[T])

Bases: Generic[T]

A collection of elements that can be filtered and transformed.

first() → BrowserJQuery | str | None

Get the first element in the collection.

Returns:: A BrowserJQuery instance wrapping the first element, or None if empty.

items() → list[BrowserJQuery | str]

Get all elements in the collection.

Returns:: List of elements wrapped in BrowserJQuery instances.

last() → BrowserJQuery | str | None

Get the last element in the collection.

Returns:: A BrowserJQuery instance wrapping the last element, or None if empty.

Decorator to prepare query results. If result is a WebElement or list of WebElements, wraps it appropriately. Text elements are left as is.

Args:: func: The function to decorate.
Returns:: The decorated function that processes its result.