py-playwright

Python Playwright Extensions - A comprehensive wrapper around Playwright for browser automation.

Installation

# Install dependencies
pip install -r requirements.txt

# Install Playwright browsers
playwright install --with-deps

Quick Start

Basic Usage

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=False)
    page = browser.new_page()
    page.goto("https://example.com")
    print(page.title())
    browser.close()

Using Extension Classes

from ext_playwright import ExtPlaywrightOption, BrowserTypeNames
from ext_browser_context import ExtBrowserContext

# Create options
ext_pw_opt = ExtPlaywrightOption(
    headless=False,
    browser_type=BrowserTypeNames.Chrome
)

# Create browser context
ext_bc = ExtBrowserContext.new_ext_browser_context(ext_pw_opt)

# Get or create page
ext_page = ext_bc.get_or_new_ext_page()

# Navigate to page
ext_page.navigate_with_loaded_state("https://example.com")

# Use extended locator
ext_locator = ext_page.ext_locator("h1")
print(f"H1 text: {ext_locator.must_inner_text()}")

# Close
ext_page.close_all()

Chrome Management

from chrome import start_chrome, shutdown_chrome

# Start Chrome with debug port
chrome_process, user_data_dir = start_chrome(9222)

# ... do something ...

# Shutdown Chrome
shutdown_chrome(chrome_process, "http://localhost:9222")

Features

• Chrome Browser Management: Start, stop, and manage Chrome browsers with CDP support
• Extended Page Operations: Enhanced page navigation, waiting, and interaction methods
• Extended Locator Operations: Advanced element locating and interaction capabilities
• Browser Context Management: Create and manage browser contexts with persistent sessions
• Debugging Capabilities: Connect to existing Chrome instances for debugging

Project Structure

py-playwright/
├── __init__.py                 # Package initialization
├── chrome.py                   # Chrome browser management
├── ext_playwright.py           # Playwright configuration and options
├── ext_browser_context.py      # Extended browser context
├── ext_page.py                 # Extended page operations
├── ext_locator.py              # Extended locator operations
├── test_chrome.py              # Chrome tests
├── scripts/
│   └── shell/
│       ├── install.sh          # Install browsers
│       ├── driver.sh           # Download driver
│       ├── browsers.sh         # Install browsers
│       └── chrome.sh           # Start Chrome with debug port
└── examples/
    ├── basic_usage.py          # Basic usage examples
    ├── using_ext_classes.py    # Using extension classes
    └── chrome_management.py    # Chrome management examples

API Reference

Chrome Management

start_chrome(debug_port: int = 0) -> Tuple[Optional[subprocess.Popen], str]

Start Chrome browser with remote debugging port.

Parameters:

• debug_port: Remote debugging port (default: 0, auto-detect)

Returns:

• Tuple of (chrome_process, user_data_dir)

shutdown_chrome(process: Optional[subprocess.Popen], base_url: str = "")

Shutdown Chrome browser gracefully.

Parameters:

• process: Chrome process object
• base_url: CDP base URL

Extension Classes

ExtPlaywrightOption

Configuration options for extended Playwright.

Attributes:

• skip_install_browsers: Skip browser installation
• headless: Run in headless mode
• browser_type: Browser type (chrome/firefox/webkit)
• channel: Browser channel
• driver_directory: Driver directory path
• browser_path: Browser executable path
• user_data_dir: User data directory
• remote_debugging_host: Remote debugging host
• remote_debugging_port: Remote debugging port

ExtBrowserContext

Extended browser context with enhanced page management.

Methods:

• new_debug_ext_browser_context(): Create debug mode context
• connect_debug_ext_browser_context(): Connect to existing Chrome
• new_ext_browser_context(): Create new browser context
• get_or_new_ext_page(): Get or create page
• new_ext_page(): Create new page
• close(): Close browser context

ExtPage

Extended page with enhanced operations.

Methods:

• navigate_with_loaded_state(url: str): Navigate and wait for load
• navigate(url: str, wait_until: str): Navigate to URL
• reload_with_loaded_state(): Reload and wait for load
• wait_for_load_state_load(): Wait for load state
• wait_for_dom_content_loaded(): Wait for DOM content loaded
• wait_for_selector_state_visible(selector: str): Wait for selector visible
• random_wait_short(): Random short wait (100-1000ms)
• random_wait_middle(): Random medium wait (3000-6000ms)
• random_wait_long(): Random long wait (10000-20000ms)
• expect_response_text(url_or_predicate: str, cb: Callable) -> str: Wait for response
• html_content() -> str: Get HTML content
• ext_locator(*selectors) -> ExtLocator: Create extended locator
• must_inner_text(*selectors) -> str: Get inner text
• must_text_content(*selectors) -> str: Get text content
• exists(selector: str) -> bool: Check if element exists
• click(selector: str): Click element
• suspend(): Suspend page operations
• continue_page(): Continue page operations

ExtLocator

Extended locator with enhanced element operations.

Methods:

• ext_locator(selector: str) -> ExtLocator: Create child locator
• exists() -> bool: Check if element exists
• must_inner_text() -> str: Get inner text
• must_text_content() -> str: Get text content
• must_get_attribute(attr: str) -> str: Get attribute value
• ext_all() -> List[ExtLocator]: Get all matching elements
• must_all_inner_texts() -> List[str]: Get all inner texts
• must_all_text_contents() -> List[str]: Get all text contents
• must_all_get_attributes(attr: str) -> List[str]: Get all attribute values
• must_click(): Click element
• has_class(class_name: str) -> bool: Check if has class

Scripts

Install Browsers

bash scripts/shell/install.sh

Download Driver

bash scripts/shell/driver.sh

Start Chrome with Debug Port

bash scripts/shell/chrome.sh

Testing

# Run tests
pytest test_chrome.py

# Or run directly
python test_chrome.py

Examples

See the examples/ directory for more usage examples:

• basic_usage.py: Basic Playwright usage
• using_ext_classes.py: Using extension classes
• chrome_management.py: Chrome browser management

License

This project is licensed under the MIT License.