browser Module (stx.browser)

scitex.browser.is_playwright_cli_available()[source]

Check if playwright-cli (npm) is installed.

Return type:

bool

async scitex.browser.show_grid_async(page, func_name='show_grid_async')[source]
async scitex.browser.highlight_element_async(element, duration_ms=1000, func_name='highlight_element_async')[source]

Highlight element with red overlay rectangle.

Parameters:

  • element (Locator) – Locator to highlight

  • duration_ms (int) – Duration to display highlight in milliseconds

  • func_name (str) – Name of calling function for logging context

scitex.browser.inject_visual_effects(page)[source]

Inject CSS and elements for visual effects (sync version).

Return type:

None

scitex.browser.show_cursor_at(page, x, y, state='normal')[source]

Move visual cursor to position (sync version).

Parameters:

  • page (Union[Page, Page]) – Playwright page object

  • x (float) – X coordinate

  • y (float) – Y coordinate

  • state (str) – Cursor state - “normal”, “clicking”, or “dragging”

Return type:

None

scitex.browser.show_click_effect(page, x, y)[source]

Show click ripple effect at position (sync version).

Return type:

None

scitex.browser.show_step(page, step, total, message, level='info')[source]

Show numbered step message in browser (sync version).

Parameters:

  • page (Union[Page, Page]) – Playwright page object

  • step (int) – Current step number

  • total (int) – Total number of steps

  • message (str) – Message to display

  • level (str) – Message level - “info”, “success”, “warning”, or “error”

Return type:

None

scitex.browser.show_test_result(page, success, message='', delay_ms=3000)[source]

Show test result banner (PASS/FAIL) and wait (sync version).

Parameters:

  • page (Union[Page, Page]) – Playwright page object

  • success (bool) – True for PASS, False for FAIL

  • message (str) – Optional message to display

  • delay_ms (int) – How long to display before continuing

Return type:

None

async scitex.browser.inject_visual_effects_async(page)[source]

Inject CSS and elements for visual effects (async version).

Return type:

None

async scitex.browser.show_cursor_at_async(page, x, y, state='normal')[source]

Move visual cursor to position (async version).

Return type:

None

async scitex.browser.show_click_effect_async(page, x, y)[source]

Show click ripple effect at position (async version).

Return type:

None

async scitex.browser.show_step_async(page, step, total, message, level='info')[source]

Show numbered step message in browser (async version).

Return type:

None

async scitex.browser.show_test_result_async(page, success, message='', delay_ms=3000)[source]

Show test result banner (PASS/FAIL) and wait (async version).

Return type:

None

scitex.browser.setup_console_interceptor(page)[source]

Set up console log interceptor with source tracking and error capture.

Features (mirroring console-interceptor.ts): - Intercepts console.log, info, warn, error, debug - Captures source file and line number - Captures unhandled JS errors - Captures unhandled promise rejections - Captures resource loading failures

Call this at the start of each test to begin capturing logs.

Return type:

None

scitex.browser.collect_console_logs(page)[source]

Collect all captured console logs from the browser.

Return type:

list

Returns:

List of log strings in format “[LEVEL] source message”

scitex.browser.collect_console_logs_detailed(page)[source]

Collect all captured console logs with full details.

Returns:

level, message, source, timestamp, url

Return type:

List of dicts with keys

scitex.browser.format_logs_devtools_style(logs)[source]

Format logs in DevTools-like style.

Parameters:

logs (list) – List of detailed log entries from collect_console_logs_detailed()

Return type:

str

Returns:

Formatted string like browser DevTools output

scitex.browser.save_failure_artifacts(page, test_name, artifacts_dir, console_logs=None)[source]

Save screenshot, console logs, and page HTML on test failure.

Parameters:

  • page (Page) – Playwright page object

  • test_name (str) – Name of the failed test (e.g., request.node.nodeid)

  • artifacts_dir (Path | str) – Directory to save artifacts

  • console_logs (list | None) – Pre-collected console logs (optional, will collect if None)

Return type:

dict

Returns:

Dict with paths to saved artifacts

scitex.browser.create_failure_capture_fixture(artifacts_dir)[source]

Create a pytest fixture for automatic failure capture.

Usage in conftest.py:

from scitex_browser.debugging import create_failure_capture_fixture

capture_on_failure = create_failure_capture_fixture(

Path(__file__).parent / “artifacts”

)

Parameters:

artifacts_dir (Path | str) – Directory to save failure artifacts

Returns:

A pytest fixture function

class scitex.browser.TestMonitor(output_dir=None, interval=2.0, quality=70, verbose=False, test_name=None)[source]

Bases: object

Monitor E2E tests with periodic screenshots using scitex.capture.

Captures screenshots at regular intervals during test execution, allowing visual inspection of test progress and debugging.

__init__(output_dir=None, interval=2.0, quality=70, verbose=False, test_name=None)[source]

Initialize test monitor.

Parameters:

  • output_dir (str | Path) – Directory for screenshots (default: $SCITEX_DIR/browser/runtime/test_monitor)

  • interval (float) – Seconds between screenshots (default: 2.0)

  • quality (int) – JPEG quality 1-100 (default: 70)

  • verbose (bool) – Print capture messages

  • test_name (str) – Optional test name for session identification

start(test_name=None)[source]

Start periodic screenshot capture.

Parameters:

test_name (str) – Optional test name to include in session

Return type:

str

Returns:

Session ID for this capture session

stop()[source]

Stop screenshot capture.

Return type:

dict

Returns:

Status dict with session info

get_status()[source]

Get current monitor status.

Return type:

dict

take_snapshot(message=None)[source]

Take an immediate snapshot (in addition to periodic captures).

Parameters:

message (str) – Optional message to include in filename

Return type:

Optional[str]

Returns:

Path to saved screenshot

create_gif(duration=0.5, output_path=None)[source]

Create GIF from captured screenshots.

Parameters:

  • duration (float) – Duration per frame in seconds

  • output_path (str) – Output path for GIF (auto-generated if None)

Return type:

Optional[str]

Returns:

Path to created GIF

get_screenshots()[source]

Get list of captured screenshot paths.

Return type:

list

scitex.browser.create_test_monitor_fixture(output_dir=None, interval=2.0, auto_gif=False)[source]

Create a pytest fixture for test monitoring.

Usage in conftest.py:

from scitex_browser.debugging import create_test_monitor_fixture

test_monitor = create_test_monitor_fixture(interval=2.0, auto_gif=True)

Parameters:

  • output_dir (str | Path) – Directory for screenshots

  • interval (float) – Seconds between screenshots

  • auto_gif (bool) – Create GIF automatically on test completion

Returns:

A pytest fixture function

scitex.browser.monitor_test(test_func=None, interval=2.0, auto_gif=False)[source]

Decorator for monitoring tests with periodic screenshots.

Usage:

@monitor_test(interval=1.0, auto_gif=True) def test_my_feature(page):

# test code…

Parameters:

  • test_func – Test function (for use without parentheses)

  • interval (float) – Seconds between screenshots

  • auto_gif (bool) – Create GIF on completion

class scitex.browser.SyncBrowserSession(page, timeout=60, on_enter=None, on_exit=None)[source]

Bases: object

Sync context manager for playwright browser sessions.

Ensures zombie process cleanup on test failures, timeouts, or crashes. Tracks browser PIDs and kills orphaned processes on exit.

__init__(page, timeout=60, on_enter=None, on_exit=None)[source]

Initialize sync browser session.

Parameters:

  • page (Page) – Playwright page instance from pytest-playwright

  • timeout (int) – Default timeout for operations in seconds

  • on_enter (Optional[Callable[[Page], None]]) – Callback when entering context

  • on_exit (Optional[Callable[[Page, bool], None]]) – Callback when exiting context (receives page and success flag)

__enter__()[source]

Enter context - track browser PIDs and run setup callback.

Return type:

SyncBrowserSession

__exit__(exc_type, exc_val, exc_tb)[source]

Exit context - ensure cleanup happens.

Return type:

bool

static kill_zombie_browsers()[source]

Kill all zombie chromium/chrome processes from failed tests.

Call this at the start of test sessions to clean up from previous runs.

scitex.browser.sync_browser_session(page, timeout=60, on_enter=None, on_exit=None)[source]

Context manager for sync playwright sessions.

Usage:
with sync_browser_session(page) as session:

session.page.goto(url) # … test code

# Cleanup happens automatically

scitex.browser.create_browser_session_fixture(timeout=60, setup=None, teardown=None, kill_zombies_on_start=True)[source]

Create a pytest fixture for browser session with cleanup.

Usage in conftest.py:

from scitex_browser import create_browser_session_fixture

browser_session = create_browser_session_fixture(

timeout=60, setup=lambda page: print(f”Starting test”), teardown=lambda page, success: print(f”Test {‘passed’ if success else ‘failed’}”), kill_zombies_on_start=True,

)

Parameters:

  • timeout (int) – Default timeout for operations

  • setup (Optional[Callable[[Page], None]]) – Callback when entering session

  • teardown (Optional[Callable[[Page, bool], None]]) – Callback when exiting (receives page and success flag)

  • kill_zombies_on_start (bool) – Kill orphaned browsers before first test

Returns:

A pytest fixture function

scitex.browser.save_as_pdf(url, output_path, **kwargs)[source]

Sync wrapper for save_as_pdf_async.

Return type:

str

async scitex.browser.save_as_pdf_async(url, output_path, *, wait_seconds=3, print_background=True, format='A4', margin_top='10mm', margin_bottom='10mm', margin_left='10mm', margin_right='10mm')[source]

Navigate to URL and save page as PDF.

Parameters:

  • url (str) – URL to save as PDF.

  • output_path (str) – Path to save the PDF file.

  • wait_seconds (float) – Extra seconds to wait after page load for JS rendering.

  • print_background (bool) – Whether to print background graphics.

  • format (str) – Paper format (A4, Letter, etc.).

  • margin_top (str) – Page margins (e.g., “10mm”, “1in”).

  • margin_bottom (str) – Page margins (e.g., “10mm”, “1in”).

  • margin_left (str) – Page margins (e.g., “10mm”, “1in”).

  • margin_right (str) – Page margins (e.g., “10mm”, “1in”).

Returns:

Absolute path of the saved PDF.

Return type:

str

async scitex.browser.detect_chrome_pdf_viewer_async(page, verbose=False, func_name='detect_chrome_pdf_viewer_async')[source]

Detect if Chrome PDF viewer is present on the page.

Universal utility for detecting PDF viewer across any browser automation workflow.

NOTE: Caller should wait for networkidle BEFORE calling this function. This function does NOT wait for networkidle to avoid redundant waits.

Parameters:

  • page – Playwright page object

  • verbose (bool) – Enable visual feedback via popup system (default False)

Returns:

True if PDF viewer detected, False otherwise

Return type:

bool

async scitex.browser.click_download_for_chrome_pdf_viewer_async(page, output_path, verbose=False, func_name='click_download_for_chrome_pdf_viewer_async')[source]

Click download button in Chrome PDF viewer and save the PDF file.

This function locates the download button in Chrome’s built-in PDF viewer (typically at top-right corner) and triggers the download, then saves the file to the specified path.

Parameters:

  • page – Playwright page object showing a PDF in Chrome’s PDF viewer

  • output_path (Path | str) – Path where the PDF file should be saved

  • verbose (bool) – Enable visual feedback via popup system (default False)

Returns:

True if download succeeded and file is valid (>1KB), False otherwise

Return type:

bool

Example

>>> await click_download_for_chrome_pdf_viewer_async(
...     page, "paper.pdf", verbose=True
... )
True

Note

  • Expects Chrome PDF viewer to be already loaded on the page

  • Download button position is at approximately (95%, 3%) of viewport

  • Waits up to 120 seconds for download to start

  • Waits 10 seconds for download to complete after starting

async scitex.browser.click_center_async(page, verbose=False, func_name='click_center_async')[source]

Click the center of the viewport.

Parameters:

  • page – Playwright page object

  • verbose (bool) – Enable visual feedback (default False)

Returns:

Click result

async scitex.browser.click_with_fallbacks_async(page, selector, method='auto', verbose=False, capture_debug=True)[source]

Click element using multiple fallback methods.

Parameters:

  • page (Page) – Playwright page object

  • selector (str) – CSS selector for the element

  • method (str) – Click method (“auto”, “playwright”, “force”, “js”)

  • verbose (bool) – Enable visual feedback via popup system (default False)

  • capture_debug (bool) – Save screenshot+HTML before/after the click (default True). Disabled in tight loops or hot paths where artifact volume hurts.

Returns:

True if click successful, False otherwise

Return type:

bool

async scitex.browser.fill_with_fallbacks_async(page, selector, value, method='auto', verbose=False, capture_debug=True)[source]

Fill element using multiple fallback methods.

Parameters:

  • page (Page) – Playwright page object

  • selector (str) – CSS selector for the element

  • value (str) – Value to fill

  • method (str) – Fill method (“auto”, “playwright”, “type”, “js”)

  • verbose (bool) – Enable visual feedback via popup system (default False)

  • capture_debug (bool) – Save screenshot+HTML before/after the fill (default True). Disabled in tight loops or hot paths.

Returns:

True if fill successful, False otherwise

Return type:

bool

class scitex.browser.PopupHandler(page)[source]

Bases: object

Handle various types of popups on web pages.

COOKIE_SELECTORS = ['button#onetrust-accept-btn-handler', 'button#onetrust-pc-btn-handler', 'button[id*="accept-cookie"]', 'button[id*="accept-all"]', 'button[aria-label*="accept cookie"]', 'button[aria-label*="Accept cookie"]', 'button:has-text("Accept all")', 'button:has-text("Accept All")', 'button:has-text("I agree")', 'button:has-text("I Agree")', 'button:has-text("Accept")', '.cookie-notice button.accept', '[class*="cookie"] button[class*="accept"]']
CLOSE_SELECTORS = ['button[aria-label="Close"]', 'button[aria-label="close"]', 'button[aria-label*="Close"]', 'button[aria-label*="close"]', 'button[aria-label*="dismiss"]', 'button[aria-label*="Dismiss"]', 'button.close', 'button.close-button', 'button.modal-close', 'button.popup-close', 'button.dialog-close', 'a.close', 'a.close-button', 'span.close', '[class*="close-button"]', '[class*="close-icon"]', 'svg[class*="close"]', 'button:has-text("No thanks")', 'button:has-text("No Thanks")', 'button:has-text("Maybe later")', 'button:has-text("Maybe Later")', 'button:has-text("Skip")', 'button:has-text("Dismiss")', 'button:has-text("Not now")', 'button:has-text("Not Now")']
MODAL_SELECTORS = ['.modal', '.overlay', '[role="dialog"]', '.popup', '#onetrust-banner-sdk', '.onetrust-pc-dark-filter', '[class*="modal"]', '[class*="popup"]', '[class*="overlay"]', '[class*="dialog"]', '[class*="banner"]', 'div[aria-modal="true"]']
__init__(page)[source]

Initialize popup handler with a page.

async detect_popups()[source]

Detect all visible popups on the page.

Return type:

List[Dict]

Returns:

List of detected popups with their details

Handle cookie consent popups.

Return type:

bool

Returns:

True if handled, False otherwise

async close_popup(popup_info=None)[source]

Close a popup using various strategies.

Parameters:

popup_info (Optional[Dict]) – Optional popup information from detect_popups

Return type:

bool

Returns:

True if closed, False otherwise

async handle_all_popups(max_attempts=3, delay_ms=1000)[source]

Detect and handle all popups on the page.

Parameters:

  • max_attempts (int) – Maximum number of attempts to clear popups

  • delay_ms (int) – Delay between attempts in milliseconds

Return type:

int

Returns:

Number of popups handled

async wait_and_handle_popups(timeout_ms=5000)[source]

Wait for popups to appear and handle them.

Parameters:

timeout_ms (int) – Maximum time to wait for popups

Return type:

int

Returns:

Number of popups handled

async scitex.browser.close_popups_async(page, handle_cookies=True, close_others=True, max_attempts=3, wait_first=True, wait_ms=2000)[source]

Convenience function to handle all popups on a page.

Parameters:

  • page (Page) – Playwright page object

  • handle_cookies (bool) – Whether to accept cookie popups

  • close_others (bool) – Whether to close other popups

  • max_attempts (int) – Maximum attempts to clear popups

  • wait_first (bool) – Whether to wait for popups to appear first

  • wait_ms (int) – Time to wait for popups to appear

Return type:

Tuple[int, List]

Returns:

Tuple of (number handled, list of handled popups)

async scitex.browser.ensure_no_popups_async(page, check_interval_ms=1000)[source]

Ensure no popups are blocking the page.

Parameters:

  • page (Page) – Playwright page object

  • check_interval_ms (int) – Interval to check for popups

Return type:

bool

Returns:

True if page is clear of popups