Metadata-Version: 2.4
Name: playwright-byob
Version: 0.1.2
Summary: Playwright but bring your own browser
Project-URL: Homepage, https://nanx.me/playwright-byob/
Project-URL: Documentation, https://nanx.me/playwright-byob/
Project-URL: Repository, https://github.com/nanxstats/playwright-byob
Project-URL: Issues, https://github.com/nanxstats/playwright-byob/issues
Project-URL: Changelog, https://github.com/nanxstats/playwright-byob/blob/main/CHANGELOG.md
Author-email: Nan Xiao <me@nanx.me>
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Requires-Dist: playwright>=1.50.0
Description-Content-Type: text/markdown

# playwright-byob

[![PyPI version](https://img.shields.io/pypi/v/playwright-byob)](https://pypi.org/project/playwright-byob/)
![Python versions](https://img.shields.io/pypi/pyversions/playwright-byob)
[![CI tests](https://github.com/nanxstats/playwright-byob/actions/workflows/ci-tests.yml/badge.svg)](https://github.com/nanxstats/playwright-byob/actions/workflows/ci-tests.yml)
[![Mypy check](https://github.com/nanxstats/playwright-byob/actions/workflows/mypy.yml/badge.svg)](https://github.com/nanxstats/playwright-byob/actions/workflows/mypy.yml)
[![Ruff check](https://github.com/nanxstats/playwright-byob/actions/workflows/ruff-check.yml/badge.svg)](https://github.com/nanxstats/playwright-byob/actions/workflows/ruff-check.yml)
[![Documentation](https://github.com/nanxstats/playwright-byob/actions/workflows/docs.yml/badge.svg)](https://nanx.me/playwright-byob/)
![License](https://img.shields.io/pypi/l/playwright-byob)

Bring your own browser to Playwright.

playwright-byob is a tiny Python helper for launching Playwright against the
real Google Chrome installation already present on a machine.
It keeps the API close to Playwright, but chooses practical defaults for headed,
persistent Chrome automation.

## Installation

```bash
pip install playwright-byob
```

With `uv`:

```bash
uv add playwright-byob
```

## Quick start

```python
from playwright.sync_api import sync_playwright
from playwright_byob import launch_chrome

with sync_playwright() as p:
    context = launch_chrome(p)
    page = context.new_page()
    page.goto("https://example.com")
    print(page.title())
    context.close()
```

The default launch uses installed Chrome when detected, falls back to
Playwright's `channel="chrome"`, opens headed, uses the platform Chrome user
data directory, selects the `Default` profile, disables Playwright's fixed
viewport, and removes the `--enable-automation` default argument.

## Customize the browser or profile

```python
from playwright.sync_api import sync_playwright
from playwright_byob import launch_chrome

with sync_playwright() as p:
    context = launch_chrome(
        p,
        browser_path="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
        user_data_dir="~/Library/Application Support/Google/Chrome",
        profile_directory="Profile 1",
        args=["--window-size=1440,1000"],
        timeout=30_000,
    )
```

You can also use environment variables:

- `PLAYWRIGHT_BYOB_CHROME_PATH`
- `PLAYWRIGHT_BYOB_USER_DATA_DIR`
- `PLAYWRIGHT_BYOB_PROFILE_DIRECTORY`

## Recommended profile patterns

Using the installed Chrome binary and using your daily Chrome profile are
separate choices. In practice, the most reliable paths are:

1. **Installed Chrome with a temporary profile**.
   Use `tempfile.TemporaryDirectory()` as `user_data_dir` and
   `profile_directory=None`, then log in during the run.
   This avoids downloading Playwright Chromium without touching
   a personal Chrome profile.
2. **Installed Chrome with a dedicated automation profile**.
   Create a separate Chrome profile for automation and point `user_data_dir`
   and `profile_directory` at it. Keep it out of day-to-day browsing.
3. **Installed Chrome with a real user profile**.
   This is convenient for local one-off scripts, but it can expose sensitive
   state, conflict with a profile already open in Chrome, or trigger account
   verification prompts.

Playwright's authentication guide also describes saving authenticated browser
state to JSON files with `context.storage_state(path=...)` and keeping those
files out of source control. Because playwright-byob launches persistent
contexts, it cannot pass `storage_state` directly at launch time, but exporting
state after login is still useful when a workflow later uses standard
Playwright contexts.

## Privacy note

A real Chrome profile or exported storage-state JSON file can contain cookies,
local storage, saved sessions, and other sensitive state,
**so use these intentionally**.
Tests in this project never read or launch a real user profile.
They use temporary directories and fake Playwright objects.

The local integration test is macOS-only and skipped in CI. It launches the
installed Chrome executable with an isolated temporary user data directory,
then verifies cookie and local storage persistence across two browser sessions.
