playwrong

playwrong is a lightweight browser automation library with a Playwright-like sync/async surface.

If you are an AI coding assistant working on this package, read ai_agent.md first.

It is focused on practical scraping workflows:

• wrap headful crawling around an already-existing browser instance when available
• attach to an already-open Chromium/Edge CDP endpoint when possible
• launch a new debug browser if no endpoint is available
• provide a small, familiar API (sync_playwright, chromium.launch, connect_over_cdp, new_page, goto, content)
• optional Firefox backend via Selenium + local undetected_geckodriver wrapper

Primary intent: allow operators to inject an already-running browser into headful crawling so automation can reuse an established session (cookies/auth state) instead of starting from a cold profile every run.

This way you can still get served relevant ads while automating your browser hehe.

Status

Early alpha (0.x). API may evolve.

Install

python -m pip install -e .

Publishing to PyPI

This package includes GitHub Actions pipelines for build/test and publish:

• projects/playwrong/.github/workflows/ci.yml
• projects/playwrong/.github/workflows/publish-pypi.yml

Publish flow is configured for trusted publishing with pypa/gh-action-pypi-publish.

Recommended release process:

1. Push/tag a release (vX.Y.Z) and publish a GitHub Release.
2. Ensure repository environment pypi exists and is approved for publishing.
3. Configure PyPI trusted publisher for your GitHub repository/workflow.

Quick start

from playwrong.sync_api import sync_playwright

with sync_playwright(verbose=True) as p:
    browser = p.chromium.connect_over_cdp("http://127.0.0.1:9222")
    page = browser.new_page()
    page.goto("https://example.com", wait_until="load")
    html = page.content()
    browser.close()

Open-browser attach

Start Edge/Chrome with remote debugging first, for example:

& "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" --remote-debugging-port=9222 --user-data-dir="$env:TEMP\edge-cdp-profile" about:blank

Then connect:

browser = p.chromium.connect_over_cdp("http://127.0.0.1:9222")

API surface

• sync_playwright(...)
• async_playwright(...)
• p.chromium.launch(...)
• p.chromium.connect_over_cdp(endpoint)
• p.firefox.launch(...)
• browser.new_context(...)
• browser.new_page()
• page.goto(url, wait_until="load", timeout=...)
• page.content()
• browser.close()

Environment variables

• PLAYWRONG_PREFER_OPEN (true/false)
• PLAYWRONG_CDP_ENDPOINTS (comma-separated URLs)
• PLAYWRONG_CDP_TIMEOUT_SECONDS (float)
• PLAYWRONG_VERBOSE (true/false)

Notes

• Edge-compatible target creation uses PUT /json/new?url=... because modern Edge returns 405 on GET /json/new.
• Firefox attach-to-existing-session is not supported; Firefox launches a new WebDriver session.
• This package intentionally exposes a minimal subset rather than full Playwright parity.

Legal Responsibility

This library is distributed as a general-purpose automation toolkit.

• The maintainers/publishers of playwrong do not grant permission to access any specific website, service, or data source.
• Compliance with laws, contracts, robots policies, terms of service, and internal security/privacy requirements is solely the responsibility of the user/operator.
• Users are responsible for obtaining any required authorization before automating browser actions.
• The software is provided under the project license on an "AS IS" basis, without legal or compliance warranties.

See SECURITY.md for reporting and security policy details.