playwright-webdriver-py

Run existing Selenium WebDriver Python scripts using Playwright as the browser backend — no ChromeDriver or browser binary installation required.

playwright-webdriver-py is a drop-in compatibility layer that implements the Selenium WebDriver Python API over Playwright's synchronous API. Drop it in and your existing webdriver.Chrome() scripts run backed by Playwright; faster, more reliable, and without the ChromeDriver version-matching headache.

Features

• Zero script changes — existing Selenium scripts run as-is
• No ChromeDriver — Playwright manages its own browser binaries
• Full WebDriverWait / expected_conditions support — unchanged from Selenium
• Chromium, Firefox, and WebKit backends via PlaywrightBrowserType
• CLI runner — execute any .py Selenium script directly from the command line
• PlaywrightBy — opt-in raw Playwright selector strings for power users

Installation

pip install playwright-webdriver-py
playwright install  # downloads browser binaries (first time only)

Or with Poetry:

poetry add playwright-webdriver-py
playwright install

Requirements: Python 3.12+

Quick Start

Run an existing Selenium script unchanged

# my_existing_script.py  — written for standard Selenium, runs on Playwright
from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC

driver = webdriver.Chrome()
wait = WebDriverWait(driver, 10)

driver.get("https://www.wikipedia.org")
search = wait.until(EC.presence_of_element_located((By.ID, "searchInput")))
search.send_keys("Playwright (software)")
search.submit()

heading = wait.until(EC.presence_of_element_located((By.ID, "firstHeading")))
print(heading.text)

driver.quit()

Via the CLI runner (intercepts webdriver.Chrome() transparently):

python -m playwright_webdriver.runner my_existing_script.py
python -m playwright_webdriver.runner my_existing_script.py --headless

Via the Python API (same interception, callable from your own code):

from playwright_webdriver.runner import run_selenium_script

run_selenium_script("my_existing_script.py", headless=True)

Use PlaywrightWebDriver directly

from playwright_webdriver import PlaywrightWebDriver, PlaywrightBrowserType
from selenium.webdriver.common.by import By

with PlaywrightWebDriver.create(
    browser_type=PlaywrightBrowserType.CHROMIUM,
    launch_options={"headless": True},
) as driver:
    driver.get("https://example.com")
    heading = driver.find_element(By.TAG_NAME, "h1")
    print(heading.text)  # "Example Domain"

Supported Selenium API

PlaywrightWebDriver

PlaywrightWebElement

Locator strategies

All standard Selenium By strategies are supported:

In addition, PlaywrightBy.selector(string) passes a raw Playwright selector string through unchanged, giving you access to Playwright-specific features like role=, text=, and :visible filters:

from playwright_webdriver import PlaywrightBy

btn = driver.find_element(PlaywrightBy.selector("role=button[name='Submit']"))

Running Tests

The test suite is a Python port of the original C# NUnit test suite from Selenium.PlaywrightDriver.

# Install dev dependencies
poetry install

# Run the full suite (19 tests, all headless)
pytest tests/

All tests use local HTML fixtures and an ephemeral HTTP server — no internet connection required.

Examples

The examples/ directory contains real-world Selenium scripts that run unmodified through the CLI runner:

python -m playwright_webdriver.runner examples/wikipedia_smoke_test.py
python -m playwright_webdriver.runner examples/apple_homepod_test.py
python -m playwright_webdriver.runner examples/skyscanner_one_way_search_test.py

How It Works

The CLI runner monkey-patches selenium.webdriver.Chrome (and Firefox, Edge, Remote, etc.) on the real selenium.webdriver module before exec()-ing the script. This means:

• WebDriverWait, expected_conditions, Keys, and all other Selenium helpers continue to import from the real Selenium package — nothing breaks.
• The only substitution is the browser factory: webdriver.Chrome() returns a PlaywrightWebDriver instance backed by Playwright's Chromium.
• All patches are restored in a finally block, so running multiple scripts in the same process is safe.

License

MIT © 2026 HappyPath. See LICENSE for details.