qufe.wbhandler module
Web Browser Automation Handler
This module provides enhanced browser automation capabilities using pure Selenium with custom timeout configurations, network monitoring, tab management, and interactive element discovery.
- Required dependencies:
pip install qufe[web]
This installs: selenium>=4.0.0
- Classes:
Browser: Base class for browser automation with common functionality and tab management Chrome: Chrome browser implementation with advanced configuration options Firefox: Firefox browser implementation with profile management
- class qufe.wbhandler.Browser(private_mode: bool = True, mobile_mode: bool = False, headless: bool = False, window_size: str = '1920,1080', window_position: str = '10,10')[source]
Bases:
objectBase browser automation class with enhanced functionality including tab management.
Provides network monitoring, element discovery, tab management, and automation utilities built on top of pure Selenium WebDriver with auto-detecting selectors.
- driver
Selenium WebDriver instance for browser automation
- wait
WebDriverWait instance for explicit waits
- window_handles
List of window handles for tab management
- __init__(private_mode: bool = True, mobile_mode: bool = False, headless: bool = False, window_size: str = '1920,1080', window_position: str = '10,10')[source]
Initialize browser instance.
- Parameters:
private_mode – Enable private/incognito browsing mode
mobile_mode – Enable mobile device emulation
headless – Run browser in headless mode
window_size – Browser window size as “width,height”
window_position – Browser window position as “x,y”
- Raises:
ImportError – If required dependencies are not installed
- click(selector: str, by: str | None = None, timeout: int = 10) None[source]
Click on element identified by selector.
- Parameters:
selector – Element selector (auto-detects XPath: //, CSS: $)
by – Explicit selection method (‘css’ or ‘xpath’, optional)
timeout – Timeout for element finding
- close_current_tab() bool[source]
Close current tab and switch to previous tab.
- Returns:
True if successful, False otherwise
- static extract_url_parameters(url: str, param: str, split_char: str = '') List[List[str]][source]
Extract parameter values from URL query string.
- Parameters:
url – URL to parse
param – Parameter name to extract (‘get_all’ returns all parameters)
split_char – Character to split parameter values on
- Returns:
List of parameter value lists
- find_common_attribute(selectors: List[str], attribute: str, verbose: bool = False) str[source]
Find the most common attribute value among elements matched by selectors.
This method helps discover common patterns in element attributes, useful for building robust selectors when class names might change.
- Parameters:
selectors – List of CSS, XPath, or auto-detected selectors
attribute – Attribute name to analyze (e.g., ‘class’, ‘id’)
verbose – Print detailed information if True
- Returns:
Most frequently occurring attribute value
Example
names = [‘RaspberryPi’, ‘BlackBerry’, ‘Apple’] selectors = [f”//label[normalize-space(text())=’{name}’]” for name in names] common_class = browser.find_common_attribute(selectors, ‘class’)
- find_element(selector: str, by: str | None = None, wait_if_needed: bool = True, timeout: int = 10)[source]
Find a single element with gradual approach.
Implements fail-fast + gradual fallback pattern: 1. Try immediate find (fast path for static content) 2. If not found and wait_if_needed=True, wait for element (safe path for dynamic content)
- Parameters:
selector – Element selector (auto-detects XPath: //, CSS: $)
by – Explicit selection method (‘css’ or ‘xpath’, optional)
wait_if_needed – Enable gradual fallback with waiting
timeout – Timeout for waiting phase
- Returns:
WebElement if found
- Raises:
NoSuchElementException – If element not found
ValueError – If selector is invalid
- find_element_info(selector: str, concat_text: bool = False) None[source]
Find and display information about elements matching the selector.
- Parameters:
selector – CSS, XPath selector, or auto-detected (XPath: //, CSS: $)
concat_text – If True, concatenate element text; if False, show detailed info
- find_elements(selector: str, by: str | None = None)[source]
Find multiple elements using auto-detected or explicit selector type.
- Parameters:
selector – Element selector (auto-detects XPath: //, CSS: $)
by – Explicit selection method (‘css’ or ‘xpath’, optional)
- Returns:
List of WebElements
- static generate_text_selectors(texts: List[str], element_type: str) List[str][source]
Generate XPath selectors for elements containing specific text.
- Parameters:
texts – List of text content to match
element_type – HTML element type (e.g., ‘a’, ‘span’, ‘button’)
- Returns:
List of XPath selectors
Example
generate_text_selectors([‘Home’, ‘About’], ‘a’) # Returns: [“//a[normalize-space(.)=’Home’]”, “//a[normalize-space(.)=’About’]”]
- get_network_logs() List[Dict[str, Any]][source]
Retrieve captured network requests.
- Returns:
List of network request dictionaries containing type, URL, status, method, request body, and response data.
- inject_network_capture() None[source]
Inject JavaScript to capture fetch/XHR network requests.
Creates a global __selenium_logs array that stores network request details including URL, status, method, request body, and response.
- open(url: str, safe_timeout: bool = False, timeout: int | None = None, wait_for_idle: bool = False, idle_time: float = 2.0) None[source]
Navigate to the specified URL with enhanced timeout handling.
- Parameters:
url – URL to navigate to
safe_timeout – Use shorter timeout for protected environments
timeout – Custom timeout in seconds (overrides safe_timeout)
wait_for_idle – Wait for network activity to settle after loading
idle_time – Time to wait for network idle (seconds)
- Raises:
RuntimeError – If driver not initialized or page fails to load
- open_new_tab(url: str | None = None, safe_timeout: bool = False) bool[source]
Open new tab and optionally navigate to URL.
- Parameters:
url – Optional URL to open in new tab
safe_timeout – Use safe timeout for page loading
- Returns:
True if successful, False otherwise
- select_option_by_text(dropdown_selector: str, option_text: str, by: str | None = None, max_retries: int = 2, retry_delay: float = 0.5) None[source]
Select dropdown option by visible text with retry logic.
- Parameters:
dropdown_selector – Selector for the <select> element
option_text – Visible text of the option to select
by – Explicit selection method (‘css’ or ‘xpath’, optional)
max_retries – Maximum number of retry attempts
retry_delay – Delay between retries in seconds
- Raises:
RuntimeError – If selection fails after all retries
- switch_to_tab(index: int = -1) bool[source]
Switch to tab by index.
- Parameters:
index – Tab index (-1 for last tab)
- Returns:
True if successful, False otherwise
- switch_to_window(handle: str) bool[source]
Switch to window by handle.
- Parameters:
handle – Window handle to switch to
- Returns:
True if successful, False otherwise
- type_text(selector: str, text: str, by: str | None = None, timeout: int = 10) None[source]
Type text into element identified by selector.
- Parameters:
selector – Element selector (auto-detects XPath: //, CSS: $)
text – Text to type
by – Explicit selection method (‘css’ or ‘xpath’, optional)
timeout – Timeout for element finding
- wait_for_ajax(timeout: int = 20) None[source]
Wait for AJAX requests to complete.
- Parameters:
timeout – Maximum time to wait in seconds
- wait_for_element(selector: str, by: str | None = None, timeout: int | None = None, condition: str = 'visibility')[source]
Wait for element to be present and meet the specified condition.
- Parameters:
selector – Element selector (auto-detects XPath: //, CSS: $)
by – Explicit selection method (‘css’ or ‘xpath’, optional)
timeout – Custom timeout in seconds
condition – Wait condition (‘visibility’, ‘presence’, ‘clickable’)
- Returns:
WebElement when found
- Raises:
TimeoutException – If element not found within timeout
ValueError – If invalid condition specified
- wait_for_network_idle(idle_time: float = 2.0, timeout: int = 30) bool[source]
Wait for network activity to settle by monitoring JavaScript activity.
This method checks for jQuery activity and document ready state, then waits for a period of network inactivity.
- Parameters:
idle_time – Time in seconds to wait for network to be idle
timeout – Maximum time to wait for network to become idle
- Returns:
True if network became idle within timeout, False otherwise
- class qufe.wbhandler.Chrome(private_mode: bool = True, mobile_mode: bool = False, headless: bool = False, window_size: str = '1920,1080', window_position: str = '10,10')[source]
Bases:
BrowserChrome browser implementation with enhanced configuration options and method chaining.
- __init__(private_mode: bool = True, mobile_mode: bool = False, headless: bool = False, window_size: str = '1920,1080', window_position: str = '10,10')[source]
Initialize Chrome browser with enhanced configuration.
- Parameters:
private_mode – Enable private/incognito browsing mode
mobile_mode – Enable mobile device emulation
headless – Run browser in headless mode
window_size – Browser window size as “width,height”
window_position – Browser window position as “x,y”
- add_argument(argument: str) Chrome[source]
Add Chrome argument with method chaining.
- Parameters:
argument – Chrome command line argument
- Returns:
Self for method chaining
- class qufe.wbhandler.Firefox(private_mode: bool = True, mobile_mode: bool = False, headless: bool = False, window_size: str = '1920,1080', window_position: str = '10,10')[source]
Bases:
BrowserFirefox browser implementation with profile management and enhanced ARM support.