Skip to content

README.md

Latest commit

 

History

History
236 lines (174 loc) · 6.61 KB

README.md

File metadata and controls

236 lines (174 loc) · 6.61 KB

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.