playwright-python

Playwright for Python is Microsoft’s official Python binding for the Playwright browser automation engine, letting developers drive Chromium, Firefox, and WebKit from a single, consistent API. It’s built for end-to-end testing and web scraping/automation workloads that need to reliably interact with real, modern web pages rather than a simplified DOM.

Under the hood, the Python package is a thin, fully-typed client over a bundled Node.js driver process: every call — clicking, navigating, waiting for network activity — is proxied over a message channel to the actual browser-automation engine, while the Python-facing API exposes both a synchronous surface (sync_playwright()) and an asyncio-based surface (async_playwright()) generated from the same underlying implementation. That means teams can pick whichever style fits their codebase (plain pytest scripts vs. asyncio-based scrapers) without giving up feature parity or auto-waiting semantics.

The library ships with built-in auto-waiting (actions wait for elements to be actionable before proceeding), network interception and mocking, multiple browser contexts for isolated sessions, and codegen/trace-viewer tooling exposed through its bundled CLI (playwright install, playwright codegen) for scaffolding and debugging tests.

What You Get

• A single API that drives Chromium, Firefox, and WebKit without browser-specific code paths
• Both a synchronous API (sync_playwright) and an asyncio-native API (async_playwright) generated from one shared implementation
• Auto-waiting actions that wait for elements to become actionable, cutting down on manual sleeps and flaky selectors
• Network interception and request/response mocking via route handlers
• Isolated, disposable browser contexts for parallel, state-free test sessions
• A bundled CLI (playwright install, playwright codegen, trace viewer) for driver setup, test recording, and debugging

Common Use Cases

• End-to-end test suites for web applications, typically wired into pytest via the pytest-playwright plugin
• Web scraping and data extraction from JavaScript-heavy pages that require a real rendering engine
• Automated visual regression testing using screenshot comparisons across Chromium/Firefox/WebKit
• Scripted browser workflows such as form submission, login flows, and multi-step user journeys
• Cross-browser compatibility verification for web apps without maintaining separate browser-specific test code

Under The Hood

Architecture The Python bindings wrap a bundled Node.js driver process launched via playwright/_impl/_driver.py’s compute_driver_executable(), communicating over a stdio-based message channel (playwright/_impl/_connection.py) that serializes calls to the driver process and receives events back as they occur. The public-facing modules (playwright/sync_api, playwright/async_api) are thin, code-generated facades over the shared low-level implementation objects in playwright/_impl/ (_browser.py, _browser_context.py, _page.py, _frame.py, and others), mapped through _impl_to_api_mapping.py so one core implementation backs both API styles. The synchronous facade achieves blocking calls by running the actual async event loop on a background thread and switching context with greenlets (_greenlets.py), so callers get synchronous-looking code while all real browser protocol traffic stays fully async underneath. This is a cleanly layered design: the Python-side objects are essentially typed proxies over remote state living in the driver process, so a change to that message-channel protocol would ripple through every _impl class, but the public API layer itself stays decoupled from that churn via the generated mapping layer.

Tech Stack The package itself is pure Python (>=3.10) with a minimal runtime dependency footprint — pyee for the event-emitter pattern used in the connection/channel messaging layer, and greenlet for the sync/async context-switching bridge — while the actual browser engines are delegated to a versioned Node.js driver (pinned via DRIVER_VERSION/NODE_VERSION) built from Microsoft’s own playwright-core npm package and bundled per-platform at install time through setup.py’s custom wheel logic, covering macOS/Linux/Windows across x86_64/arm64. Packaging uses setuptools with setuptools-scm for version derivation and auditwheel for manylinux compliance, and the playwright console-script entry point simply shells out to the bundled Node.js driver binary.

Code Quality Testing is extensive: a large tests/ suite is split into parallel sync/ and async/ variants plus shared common/ fixtures, run under pytest with asyncio_mode=auto, alongside per-engine golden-image directories (golden-chromium, golden-firefox, golden-webkit) for reference-image comparisons, all exercised across platforms in CI (.github/workflows/ci.yml and Azure Pipelines). Static analysis is comprehensive and enforced via pre-commit hooks covering black, isort, flake8, mypy (with disallow_untyped_defs and warn_redundant_casts), and a local pyright hook, alongside a custom license-header check. Error handling is explicit and typed through a dedicated _errors.py module (TargetClosedError, rewrite_error) rather than broad exception swallowing.

API Design The library’s core design bet is generating both a synchronous API (sync_playwright()) and an asyncio-native API (async_playwright()) from one shared implementation and protocol definition, via scripts/generate_sync_api.py and scripts/generate_async_api.py producing each API’s _generated.py. Rather than forcing developers into either a blocking (Selenium-style) or async-only client, Playwright gives both styles identical semantics and feature parity — auto-waiting, network interception, and multi-browser support — from a single source of truth, reducing the API-surface duplication and drift that hand-maintained sync/async twins usually accumulate.