playwright-byob 0.1.0__tar.gz

playwright_byob-0.1.0/.github/workflows/ci-tests.yml

@@ -0,0 +1,56 @@
+name: CI tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+      fail-fast: false
+
+    steps:
+      - uses: actions/checkout@v7
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          # we are using the -e flag, so that code cov finds the source.
+          # this is not ideal, since installing an editable can technically
+          # differ from a normal install in surprising ways.
+          pip install -e '.[all]'
+      - name: Test with pytest
+        run: |
+          pip install pytest
+          pytest
+
+      # - name: Upload coverage reports to Codecov
+      #   uses: codecov/codecov-action@v4
+      #   with:
+      #     name: "py${{ matrix.python-version }}"
+      #     token: ${{ secrets.CODECOV_TOKEN }}
+
+  test-windows:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+      - name: Install dependencies
+        run: |
+          pip install -e '.[all]'
+      - name: Test with pytest
+        run: |
+          pip install pytest
+          pytest

playwright_byob-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,31 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/configure-pages@v6
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.x
+      - run: pip install zensical mkdocstrings-python
+      - run: zensical build --clean
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+      - uses: actions/deploy-pages@v5
+        id: deployment

playwright_byob-0.1.0/.github/workflows/mypy.yml

@@ -0,0 +1,34 @@
+name: Mypy check
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - "**"
+
+jobs:
+  mypy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+
+      - name: Install uv
+        run: |
+          pip install uv
+
+      - name: Install dependencies
+        run: |
+          uv sync --dev
+
+      - name: Run Type Checks
+        run: |
+          uv run mypy .

playwright_byob-0.1.0/.github/workflows/ruff-check.yml

@@ -0,0 +1,25 @@
+name: Ruff check
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - "**"
+
+jobs:
+  ruff-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff
+      - name: Run Ruff
+        run: ruff check --output-format=github .

playwright_byob-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Zensical site
+/site/

playwright_byob-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14.6

playwright_byob-0.1.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## playwright-byob 0.1.0
+
+### New features
+
+- Add sync and async helpers, `launch_chrome()` and `async_launch_chrome()`,
+  for launching Playwright with a persistent Google Chrome context.
+- Add automatic detection for installed Google Chrome and the platform Chrome
+  user data directory on macOS, Windows, and Linux.
+- Add sensible headed Chrome defaults: persistent profile,
+  `Default` profile selection, no fixed Playwright viewport, maximized window,
+  and removal of Playwright's `--enable-automation` default argument.
+- Add explicit customization for Chrome executable path, user data directory,
+  profile directory, Chrome flags, and arbitrary Playwright launch options.
+- Add environment variable overrides via `PLAYWRIGHT_BYOB_CHROME_PATH`,
+  `PLAYWRIGHT_BYOB_USER_DATA_DIR`, and `PLAYWRIGHT_BYOB_PROFILE_DIRECTORY`.
+- Add `build_chrome_launch_config()` for tests, dry runs, and inspecting
+  resolved launch options without starting a browser.
+- Add typed public exceptions for missing Chrome executables,
+  missing Chrome profile directories, and invalid configuration.
+
+### Documentation
+
+- Add README and Zensical documentation covering installation,
+  sync and async usage, defaults, customization, environment variables,
+  and privacy guidance.
+- Add coding-agent guidance documenting privacy rules, development commands,
+  and design preferences for future maintenance.
+
+### Testing
+
+- Add a pytest suite that verifies launch configuration and platform detection
+  without reading real user browser data or requiring Chrome in CI.

playwright_byob-0.1.0/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2026, playwright-byob authors
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

playwright_byob-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: playwright-byob
+Version: 0.1.0
+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.60.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 and profile 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`
+
+## Privacy note
+
+A real Chrome profile can contain cookies, local storage, saved sessions,
+and other sensitive state, **so use this intentionally**.
+Tests in this project never read or launch a real user profile.
+They use temporary directories and fake Playwright objects.

playwright_byob-0.1.0/README.md

@@ -0,0 +1,77 @@
+# 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 and profile 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`
+
+## Privacy note
+
+A real Chrome profile can contain cookies, local storage, saved sessions,
+and other sensitive state, **so use this intentionally**.
+Tests in this project never read or launch a real user profile.
+They use temporary directories and fake Playwright objects.

playwright_byob-0.1.0/pyproject.toml

@@ -0,0 +1,82 @@
+[project]
+name = "playwright-byob"
+version = "0.1.0"
+description = "Playwright but bring your own browser"
+authors = [{ name = "Nan Xiao", email = "me@nanx.me" }]
+readme = "README.md"
+dependencies = ["playwright>=1.60.0"]
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+
+    "Intended Audience :: Developers",
+
+    "Topic :: Software Development :: Testing",
+    "Topic :: Internet :: WWW/HTTP :: Browsers",
+
+    "Operating System :: OS Independent",
+
+    "License :: OSI Approved :: MIT License",
+
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+requires-python = ">=3.10"
+
+[project.urls]
+Homepage = "https://nanx.me/playwright-byob/"
+Documentation = "https://nanx.me/playwright-byob/"
+Repository = "https://github.com/nanxstats/playwright-byob"
+Issues = "https://github.com/nanxstats/playwright-byob/issues"
+Changelog = "https://github.com/nanxstats/playwright-byob/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+exclude = ["/docs", "/scripts", "/AGENTS.md", "/uv.lock", "/zensical.toml"]
+
+[tool.hatch.build.targets.wheel]
+exclude = ["/docs", "/scripts", "/AGENTS.md", "/uv.lock", "/zensical.toml"]
+
+[dependency-groups]
+dev = [
+    "isort>=8.0.1",
+    "mkdocstrings-python>=2.0.5",
+    "mypy>=2.1.0",
+    "pytest>=9.1.1",
+    "ruff>=0.15.19",
+    "zensical>=0.0.46",
+]
+
+[tool.ruff]
+exclude = ["vendor", ".venv"]
+
+[tool.ruff.lint]
+select = [
+    # pycodestyle
+    "E",
+    # Pyflakes
+    "F",
+    # pyupgrade
+    "UP",
+    # flake8-bugbear
+    "B",
+    # flake8-simplify
+    "SIM",
+    # isort
+    "I",
+]
+
+[tool.isort]
+profile = "black"
+skip = ["vendor", ".venv"]
+
+[tool.mypy]
+exclude = ["vendor/"]

playwright_byob-0.1.0/src/playwright_byob/__init__.py

@@ -0,0 +1,53 @@
+"""Bring your own browser to Playwright."""
+
+from ._chrome import (
+    CHROME_PATH_ENV,
+    DEFAULT_CHANNEL,
+    DEFAULT_CHROME_ARGS,
+    DEFAULT_IGNORE_DEFAULT_ARGS,
+    DEFAULT_PROFILE_DIRECTORY,
+    PROFILE_DIRECTORY_ENV,
+    USER_DATA_DIR_ENV,
+    ChromeLaunchConfig,
+    ChromeNotFoundError,
+    ChromeProfileNotFoundError,
+    ConfigurationError,
+    IgnoreDefaultArgs,
+    PathLike,
+    PathSetting,
+    PlaywrightByobError,
+    ProfileSetting,
+    async_launch_chrome,
+    build_chrome_launch_config,
+    chrome_executable_candidates,
+    chrome_user_data_dir_candidates,
+    detect_chrome_executable,
+    detect_chrome_user_data_dir,
+    launch_chrome,
+)
+
+__all__ = [
+    "CHROME_PATH_ENV",
+    "DEFAULT_CHANNEL",
+    "DEFAULT_CHROME_ARGS",
+    "DEFAULT_IGNORE_DEFAULT_ARGS",
+    "DEFAULT_PROFILE_DIRECTORY",
+    "PROFILE_DIRECTORY_ENV",
+    "USER_DATA_DIR_ENV",
+    "ChromeLaunchConfig",
+    "ChromeNotFoundError",
+    "ChromeProfileNotFoundError",
+    "ConfigurationError",
+    "IgnoreDefaultArgs",
+    "PathLike",
+    "PathSetting",
+    "ProfileSetting",
+    "PlaywrightByobError",
+    "async_launch_chrome",
+    "build_chrome_launch_config",
+    "chrome_executable_candidates",
+    "chrome_user_data_dir_candidates",
+    "detect_chrome_executable",
+    "detect_chrome_user_data_dir",
+    "launch_chrome",
+]

playwright_byob-0.1.0/src/playwright_byob/_chrome.py

@@ -0,0 +1,502 @@
+"""Utilities for launching Playwright with an installed Google Chrome profile."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal, TypeAlias
+
+from playwright.async_api import BrowserContext as AsyncBrowserContext
+from playwright.async_api import Playwright as AsyncPlaywright
+from playwright.sync_api import BrowserContext as SyncBrowserContext
+from playwright.sync_api import Playwright as SyncPlaywright
+
+Auto: TypeAlias = Literal["auto"]
+PathLike: TypeAlias = str | os.PathLike[str]
+PathSetting: TypeAlias = PathLike | Auto | None
+ProfileSetting: TypeAlias = str | Auto | None
+IgnoreDefaultArgs: TypeAlias = bool | Sequence[str] | None
+
+CHROME_PATH_ENV = "PLAYWRIGHT_BYOB_CHROME_PATH"
+USER_DATA_DIR_ENV = "PLAYWRIGHT_BYOB_USER_DATA_DIR"
+PROFILE_DIRECTORY_ENV = "PLAYWRIGHT_BYOB_PROFILE_DIRECTORY"
+DEFAULT_CHANNEL = "chrome"
+DEFAULT_PROFILE_DIRECTORY = "Default"
+DEFAULT_IGNORE_DEFAULT_ARGS: tuple[str, ...] = ("--enable-automation",)
+DEFAULT_CHROME_ARGS: tuple[str, ...] = (
+    "--disable-blink-features=AutomationControlled",
+)
+
+
+class PlaywrightByobError(RuntimeError):
+    """Base exception for playwright-byob failures."""
+
+
+class ChromeNotFoundError(PlaywrightByobError):
+    """Raised when an explicitly requested Chrome executable cannot be found."""
+
+
+class ChromeProfileNotFoundError(PlaywrightByobError):
+    """Raised when the default Chrome user data directory cannot be found."""
+
+
+class ConfigurationError(PlaywrightByobError, ValueError):
+    """Raised when launch configuration is invalid."""
+
+
+@dataclass(frozen=True)
+class ChromeLaunchConfig:
+    """Resolved arguments for ``chromium.launch_persistent_context``.
+
+    ``user_data_dir`` is passed as the first positional argument. ``options`` is
+    expanded as keyword arguments.
+    """
+
+    user_data_dir: Path
+    options: Mapping[str, Any]
+
+    def to_playwright_kwargs(self) -> dict[str, Any]:
+        """Return a mutable copy of the keyword arguments for Playwright."""
+        return dict(self.options)
+
+
+def chrome_executable_candidates(
+    *,
+    sys_platform: str | None = None,
+    env: Mapping[str, str] | None = None,
+) -> tuple[Path, ...]:
+    """Return plausible Google Chrome executable paths for the current platform.
+
+    The function only builds candidates; it does not read profile data or launch
+    Chrome. The ``PLAYWRIGHT_BYOB_CHROME_PATH`` environment variable, when set,
+    is returned first.
+    """
+    platform = sys_platform or sys.platform
+    environ = os.environ if env is None else env
+    candidates: list[Path] = []
+
+    env_path = environ.get(CHROME_PATH_ENV)
+    if env_path:
+        candidates.append(Path(env_path).expanduser())
+
+    if platform == "darwin":
+        candidates.append(
+            Path("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome")
+        )
+        home = _home_path(environ)
+        if home is not None:
+            candidates.append(
+                home
+                / "Applications"
+                / "Google Chrome.app"
+                / "Contents"
+                / "MacOS"
+                / "Google Chrome"
+            )
+    elif platform.startswith("win"):
+        for key in ("LOCALAPPDATA", "PROGRAMFILES", "PROGRAMFILES(X86)"):
+            root = environ.get(key)
+            if root:
+                candidates.append(
+                    Path(root) / "Google" / "Chrome" / "Application" / "chrome.exe"
+                )
+    else:
+        for command in (
+            "google-chrome",
+            "google-chrome-stable",
+            "chrome",
+        ):
+            found = shutil.which(
+                command,
+                path=environ.get("PATH") if env is None else environ.get("PATH", ""),
+            )
+            if found:
+                candidates.append(Path(found))
+        candidates.extend(
+            [
+                Path("/usr/bin/google-chrome"),
+                Path("/usr/bin/google-chrome-stable"),
+                Path("/opt/google/chrome/chrome"),
+            ]
+        )
+
+    return _dedupe_paths(candidates)
+
+
+def detect_chrome_executable(
+    browser_path: PathSetting = "auto",
+    *,
+    sys_platform: str | None = None,
+    env: Mapping[str, str] | None = None,
+) -> Path | None:
+    """Return an existing Google Chrome executable, or ``None`` if not found.
+
+    Pass ``browser_path`` to check one explicit path. With the default
+    ``"auto"``, common platform locations and ``PLAYWRIGHT_BYOB_CHROME_PATH``
+    are checked.
+    """
+    explicit = _coerce_optional_path(browser_path)
+    if explicit is not None:
+        return explicit if explicit.exists() else None
+
+    for candidate in chrome_executable_candidates(
+        sys_platform=sys_platform,
+        env=env,
+    ):
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def chrome_user_data_dir_candidates(
+    *,
+    sys_platform: str | None = None,
+    env: Mapping[str, str] | None = None,
+) -> tuple[Path, ...]:
+    """Return plausible Google Chrome user data directories.
+
+    These are profile roots such as ``.../Google/Chrome`` on macOS or
+    ``.../Google/Chrome/User Data`` on Windows. They may contain profile folders
+    named ``Default``, ``Profile 1``, and so on.
+    """
+    platform = sys_platform or sys.platform
+    environ = os.environ if env is None else env
+    candidates: list[Path] = []
+
+    env_path = environ.get(USER_DATA_DIR_ENV)
+    if env_path:
+        candidates.append(Path(env_path).expanduser())
+
+    if platform == "darwin":
+        home = _home_path(environ)
+        if home is not None:
+            candidates.append(
+                home / "Library" / "Application Support" / "Google" / "Chrome"
+            )
+    elif platform.startswith("win"):
+        local_app_data = environ.get("LOCALAPPDATA")
+        if local_app_data:
+            candidates.append(Path(local_app_data) / "Google" / "Chrome" / "User Data")
+    else:
+        home = _home_path(environ)
+        if home is not None:
+            candidates.append(home / ".config" / "google-chrome")
+
+    return _dedupe_paths(candidates)
+
+
+def detect_chrome_user_data_dir(
+    user_data_dir: PathSetting = "auto",
+    *,
+    sys_platform: str | None = None,
+    env: Mapping[str, str] | None = None,
+) -> Path | None:
+    """Return an existing Google Chrome user data directory, or ``None``."""
+    explicit = _coerce_optional_path(user_data_dir)
+    if explicit is not None:
+        return explicit if explicit.exists() else None
+
+    for candidate in chrome_user_data_dir_candidates(
+        sys_platform=sys_platform,
+        env=env,
+    ):
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def build_chrome_launch_config(
+    *,
+    browser_path: PathSetting = "auto",
+    user_data_dir: PathSetting = "auto",
+    profile_directory: ProfileSetting = "auto",
+    channel: str | None = DEFAULT_CHANNEL,
+    headless: bool | None = False,
+    args: Sequence[str] | None = None,
+    default_args: bool = True,
+    ignore_default_args: IgnoreDefaultArgs = DEFAULT_IGNORE_DEFAULT_ARGS,
+    no_viewport: bool | None = True,
+    sys_platform: str | None = None,
+    env: Mapping[str, str] | None = None,
+    **launch_options: Any,
+) -> ChromeLaunchConfig:
+    """Build resolved launch parameters for Playwright's persistent context.
+
+    Defaults are intentionally tuned for using installed Google Chrome in headed
+    mode with a persistent profile:
+
+    - use the installed Chrome executable when it can be found;
+    - otherwise ask Playwright to use the branded ``chrome`` channel;
+    - use the existing platform Chrome user data directory;
+    - select the ``Default`` Chrome profile directory;
+    - run headed with Playwright's fixed viewport disabled;
+    - hide Playwright's ``--enable-automation`` default argument.
+
+    Extra ``launch_options`` are passed directly to Playwright and can override
+    most defaults. Use ``args`` for additional Chrome flags, or set
+    ``default_args=False`` to opt out of this package's default Chrome flags.
+    """
+    environ = os.environ if env is None else env
+    resolved_user_data_dir = _resolve_user_data_dir(
+        user_data_dir,
+        sys_platform=sys_platform,
+        env=environ,
+    )
+    resolved_profile_directory = _resolve_profile_directory(
+        profile_directory,
+        env=environ,
+    )
+    resolved_browser_path = _resolve_browser_path(
+        browser_path,
+        sys_platform=sys_platform,
+        env=environ,
+    )
+
+    options: dict[str, Any] = {}
+    if resolved_browser_path is not None:
+        options["executable_path"] = resolved_browser_path
+    elif channel is not None:
+        options["channel"] = channel
+
+    if headless is not None:
+        options["headless"] = headless
+
+    launch_args = _build_chrome_args(
+        profile_directory=resolved_profile_directory,
+        headless=headless,
+        args=args,
+        default_args=default_args,
+    )
+    if launch_args:
+        options["args"] = launch_args
+
+    if ignore_default_args is not None:
+        options["ignore_default_args"] = ignore_default_args
+
+    if no_viewport is not None and "viewport" not in launch_options:
+        options["no_viewport"] = no_viewport
+
+    options.update(launch_options)
+    return ChromeLaunchConfig(
+        user_data_dir=resolved_user_data_dir,
+        options=options,
+    )
+
+
+def launch_chrome(
+    playwright: SyncPlaywright,
+    *,
+    browser_path: PathSetting = "auto",
+    user_data_dir: PathSetting = "auto",
+    profile_directory: ProfileSetting = "auto",
+    channel: str | None = DEFAULT_CHANNEL,
+    headless: bool | None = False,
+    args: Sequence[str] | None = None,
+    default_args: bool = True,
+    ignore_default_args: IgnoreDefaultArgs = DEFAULT_IGNORE_DEFAULT_ARGS,
+    no_viewport: bool | None = True,
+    **launch_options: Any,
+) -> SyncBrowserContext:
+    """Launch a sync Playwright persistent context with installed Chrome.
+
+    Example:
+        ```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")
+            context.close()
+        ```
+    """
+    config = build_chrome_launch_config(
+        browser_path=browser_path,
+        user_data_dir=user_data_dir,
+        profile_directory=profile_directory,
+        channel=channel,
+        headless=headless,
+        args=args,
+        default_args=default_args,
+        ignore_default_args=ignore_default_args,
+        no_viewport=no_viewport,
+        **launch_options,
+    )
+    return playwright.chromium.launch_persistent_context(
+        config.user_data_dir,
+        **config.to_playwright_kwargs(),
+    )
+
+
+async def async_launch_chrome(
+    playwright: AsyncPlaywright,
+    *,
+    browser_path: PathSetting = "auto",
+    user_data_dir: PathSetting = "auto",
+    profile_directory: ProfileSetting = "auto",
+    channel: str | None = DEFAULT_CHANNEL,
+    headless: bool | None = False,
+    args: Sequence[str] | None = None,
+    default_args: bool = True,
+    ignore_default_args: IgnoreDefaultArgs = DEFAULT_IGNORE_DEFAULT_ARGS,
+    no_viewport: bool | None = True,
+    **launch_options: Any,
+) -> AsyncBrowserContext:
+    """Launch an async Playwright persistent context with installed Chrome."""
+    config = build_chrome_launch_config(
+        browser_path=browser_path,
+        user_data_dir=user_data_dir,
+        profile_directory=profile_directory,
+        channel=channel,
+        headless=headless,
+        args=args,
+        default_args=default_args,
+        ignore_default_args=ignore_default_args,
+        no_viewport=no_viewport,
+        **launch_options,
+    )
+    return await playwright.chromium.launch_persistent_context(
+        config.user_data_dir,
+        **config.to_playwright_kwargs(),
+    )
+
+
+def _resolve_user_data_dir(
+    user_data_dir: PathSetting,
+    *,
+    sys_platform: str | None,
+    env: Mapping[str, str],
+) -> Path:
+    explicit = _coerce_optional_path(user_data_dir)
+    if explicit is not None:
+        return explicit
+
+    env_user_data_dir = env.get(USER_DATA_DIR_ENV)
+    if env_user_data_dir:
+        env_user_data_path = Path(env_user_data_dir).expanduser()
+        if env_user_data_path.exists():
+            return env_user_data_path
+        msg = (
+            f"Chrome user data directory from {USER_DATA_DIR_ENV} "
+            f"does not exist: {env_user_data_path}"
+        )
+        raise ChromeProfileNotFoundError(msg)
+
+    detected = detect_chrome_user_data_dir(
+        "auto",
+        sys_platform=sys_platform,
+        env=env,
+    )
+    if detected is not None:
+        return detected
+
+    candidates = ", ".join(
+        str(path)
+        for path in chrome_user_data_dir_candidates(sys_platform=sys_platform, env=env)
+    )
+    msg = (
+        "Could not find an existing Google Chrome user data directory. "
+        f"Set {USER_DATA_DIR_ENV} or pass user_data_dir=... explicitly. "
+        f"Checked: {candidates}."
+    )
+    raise ChromeProfileNotFoundError(msg)
+
+
+def _resolve_browser_path(
+    browser_path: PathSetting,
+    *,
+    sys_platform: str | None,
+    env: Mapping[str, str],
+) -> Path | None:
+    if browser_path is None:
+        return None
+
+    explicit = _coerce_optional_path(browser_path)
+    if explicit is not None:
+        if explicit.exists():
+            return explicit
+        msg = f"Chrome executable does not exist: {explicit}"
+        raise ChromeNotFoundError(msg)
+
+    env_browser_path = env.get(CHROME_PATH_ENV)
+    if env_browser_path:
+        env_browser = Path(env_browser_path).expanduser()
+        if env_browser.exists():
+            return env_browser
+        msg = f"Chrome executable from {CHROME_PATH_ENV} does not exist: {env_browser}"
+        raise ChromeNotFoundError(msg)
+
+    return detect_chrome_executable(
+        "auto",
+        sys_platform=sys_platform,
+        env=env,
+    )
+
+
+def _resolve_profile_directory(
+    profile_directory: ProfileSetting,
+    *,
+    env: Mapping[str, str],
+) -> str | None:
+    resolved: str | None
+    if profile_directory == "auto":
+        resolved = env.get(PROFILE_DIRECTORY_ENV, DEFAULT_PROFILE_DIRECTORY)
+    else:
+        resolved = profile_directory
+    if resolved is None:
+        return None
+    if not resolved:
+        msg = "profile_directory must be a non-empty folder name or None"
+        raise ConfigurationError(msg)
+    if "/" in resolved or "\\" in resolved or resolved in {".", ".."}:
+        msg = "profile_directory must be a Chrome profile folder name, not a path"
+        raise ConfigurationError(msg)
+    return resolved
+
+
+def _build_chrome_args(
+    *,
+    profile_directory: str | None,
+    headless: bool | None,
+    args: Sequence[str] | None,
+    default_args: bool,
+) -> list[str]:
+    launch_args: list[str] = []
+    if default_args:
+        launch_args.extend(DEFAULT_CHROME_ARGS)
+        if headless is False:
+            launch_args.append("--start-maximized")
+    if profile_directory is not None:
+        launch_args.append(f"--profile-directory={profile_directory}")
+    if args:
+        launch_args.extend(args)
+    return launch_args
+
+
+def _coerce_optional_path(value: PathSetting) -> Path | None:
+    if value is None or value == "auto":
+        return None
+    return Path(value).expanduser()
+
+
+def _home_path(env: Mapping[str, str]) -> Path | None:
+    home = env.get("HOME") or env.get("USERPROFILE")
+    if home:
+        return Path(home).expanduser()
+    return None
+
+
+def _dedupe_paths(paths: Sequence[Path]) -> tuple[Path, ...]:
+    seen: set[str] = set()
+    result: list[Path] = []
+    for path in paths:
+        key = os.fspath(path)
+        if key not in seen:
+            seen.add(key)
+            result.append(path)
+    return tuple(result)

playwright_byob-0.1.0/tests/test_chrome.py

@@ -0,0 +1,314 @@
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+import playwright_byob._chrome as chrome_module
+from playwright_byob import (
+    CHROME_PATH_ENV,
+    DEFAULT_IGNORE_DEFAULT_ARGS,
+    PROFILE_DIRECTORY_ENV,
+    USER_DATA_DIR_ENV,
+    ChromeNotFoundError,
+    ChromeProfileNotFoundError,
+    ConfigurationError,
+    async_launch_chrome,
+    build_chrome_launch_config,
+    chrome_executable_candidates,
+    chrome_user_data_dir_candidates,
+    detect_chrome_executable,
+    detect_chrome_user_data_dir,
+    launch_chrome,
+)
+
+
+class FakeSyncChromium:
+    def __init__(self) -> None:
+        self.calls: list[tuple[Path, dict[str, Any]]] = []
+
+    def launch_persistent_context(self, user_data_dir: Path, **kwargs: Any) -> str:
+        self.calls.append((user_data_dir, kwargs))
+        return "sync-context"
+
+
+class FakeSyncPlaywright:
+    def __init__(self) -> None:
+        self.chromium = FakeSyncChromium()
+
+
+class FakeAsyncChromium:
+    def __init__(self) -> None:
+        self.calls: list[tuple[Path, dict[str, Any]]] = []
+
+    async def launch_persistent_context(
+        self, user_data_dir: Path, **kwargs: Any
+    ) -> str:
+        self.calls.append((user_data_dir, kwargs))
+        return "async-context"
+
+
+class FakeAsyncPlaywright:
+    def __init__(self) -> None:
+        self.chromium = FakeAsyncChromium()
+
+
+def test_chrome_executable_candidates_prefer_env_path(tmp_path: Path) -> None:
+    chrome = tmp_path / "chrome"
+    env = {CHROME_PATH_ENV: str(chrome), "HOME": str(tmp_path)}
+
+    candidates = chrome_executable_candidates(sys_platform="darwin", env=env)
+
+    assert candidates[0] == chrome
+    assert (
+        Path("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome")
+        in candidates
+    )
+
+
+def test_chrome_user_data_dir_candidates_are_platform_specific(tmp_path: Path) -> None:
+    mac_candidates = chrome_user_data_dir_candidates(
+        sys_platform="darwin",
+        env={"HOME": str(tmp_path)},
+    )
+    linux_candidates = chrome_user_data_dir_candidates(
+        sys_platform="linux",
+        env={"HOME": str(tmp_path)},
+    )
+    windows_candidates = chrome_user_data_dir_candidates(
+        sys_platform="win32",
+        env={"LOCALAPPDATA": str(tmp_path)},
+    )
+
+    assert mac_candidates == (
+        tmp_path / "Library" / "Application Support" / "Google" / "Chrome",
+    )
+    assert linux_candidates == (tmp_path / ".config" / "google-chrome",)
+    assert windows_candidates == (tmp_path / "Google" / "Chrome" / "User Data",)
+
+
+def test_empty_env_does_not_fall_back_to_process_home_or_path(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    which_paths: list[str | None] = []
+
+    def fake_which(command: str, path: str | None = None) -> str | None:
+        del command
+        which_paths.append(path)
+        return "/real-path/chrome" if path is None else None
+
+    monkeypatch.setattr(chrome_module.shutil, "which", fake_which)
+
+    executable_candidates = chrome_executable_candidates(sys_platform="linux", env={})
+    user_data_candidates = chrome_user_data_dir_candidates(sys_platform="linux", env={})
+
+    assert which_paths == ["", "", ""]
+    assert Path("/real-path/chrome") not in executable_candidates
+    assert user_data_candidates == ()
+
+
+def test_build_config_empty_env_does_not_use_real_user_profile() -> None:
+    with pytest.raises(ChromeProfileNotFoundError):
+        build_chrome_launch_config(browser_path=None, sys_platform="linux", env={})
+
+
+def test_detect_chrome_executable_checks_explicit_existing_path(tmp_path: Path) -> None:
+    chrome = tmp_path / "chrome"
+    chrome.write_text("fake chrome", encoding="utf-8")
+
+    assert detect_chrome_executable(chrome) == chrome
+    assert detect_chrome_executable(tmp_path / "missing") is None
+
+
+def test_detect_user_data_dir_checks_existing_path_only(tmp_path: Path) -> None:
+    user_data_dir = tmp_path / "Chrome User Data"
+    user_data_dir.mkdir()
+
+    assert detect_chrome_user_data_dir(user_data_dir) == user_data_dir
+    assert detect_chrome_user_data_dir(tmp_path / "missing") is None
+
+
+def test_build_config_uses_explicit_browser_profile_and_sensible_defaults(
+    tmp_path: Path,
+) -> None:
+    chrome = tmp_path / "chrome"
+    chrome.write_text("fake chrome", encoding="utf-8")
+    user_data_dir = tmp_path / "User Data"
+    user_data_dir.mkdir()
+
+    config = build_chrome_launch_config(
+        browser_path=chrome,
+        user_data_dir=user_data_dir,
+        profile_directory="Profile 1",
+        args=["--window-size=1440,1000"],
+        timeout=12_000,
+    )
+
+    options = config.to_playwright_kwargs()
+    assert config.user_data_dir == user_data_dir
+    assert options["executable_path"] == chrome
+    assert "channel" not in options
+    assert options["headless"] is False
+    assert options["no_viewport"] is True
+    assert options["ignore_default_args"] == DEFAULT_IGNORE_DEFAULT_ARGS
+    assert options["timeout"] == 12_000
+    assert options["args"] == [
+        "--disable-blink-features=AutomationControlled",
+        "--start-maximized",
+        "--profile-directory=Profile 1",
+        "--window-size=1440,1000",
+    ]
+
+
+def test_build_config_can_use_playwright_chrome_channel_without_detection(
+    tmp_path: Path,
+) -> None:
+    user_data_dir = tmp_path / "User Data"
+
+    config = build_chrome_launch_config(
+        browser_path=None,
+        user_data_dir=user_data_dir,
+        profile_directory=None,
+        default_args=False,
+        ignore_default_args=None,
+        no_viewport=False,
+    )
+
+    options = config.to_playwright_kwargs()
+    assert config.user_data_dir == user_data_dir
+    assert options == {"channel": "chrome", "headless": False, "no_viewport": False}
+
+
+def test_build_config_honors_environment_overrides(tmp_path: Path) -> None:
+    chrome = tmp_path / "chrome"
+    chrome.write_text("fake chrome", encoding="utf-8")
+    user_data_dir = tmp_path / "Chrome User Data"
+    user_data_dir.mkdir()
+    env = {
+        CHROME_PATH_ENV: str(chrome),
+        USER_DATA_DIR_ENV: str(user_data_dir),
+        PROFILE_DIRECTORY_ENV: "Profile 2",
+    }
+
+    config = build_chrome_launch_config(env=env)
+    options = config.to_playwright_kwargs()
+
+    assert config.user_data_dir == user_data_dir
+    assert options["executable_path"] == chrome
+    assert "--profile-directory=Profile 2" in options["args"]
+
+
+def test_build_config_rejects_missing_environment_paths(tmp_path: Path) -> None:
+    with pytest.raises(ChromeNotFoundError):
+        build_chrome_launch_config(
+            user_data_dir=tmp_path,
+            env={CHROME_PATH_ENV: str(tmp_path / "missing-chrome")},
+        )
+
+    with pytest.raises(ChromeProfileNotFoundError):
+        build_chrome_launch_config(
+            browser_path=None,
+            env={USER_DATA_DIR_ENV: str(tmp_path / "missing-profile")},
+        )
+
+
+def test_build_config_does_not_create_or_use_real_profile_in_auto_mode(
+    tmp_path: Path,
+) -> None:
+    home = tmp_path / "home"
+    home.mkdir()
+
+    with pytest.raises(ChromeProfileNotFoundError):
+        build_chrome_launch_config(
+            browser_path=None,
+            sys_platform="linux",
+            env={"HOME": str(home), "PATH": ""},
+        )
+
+    assert not (home / ".config" / "google-chrome").exists()
+
+
+def test_build_config_rejects_missing_explicit_browser(tmp_path: Path) -> None:
+    with pytest.raises(ChromeNotFoundError):
+        build_chrome_launch_config(
+            browser_path=tmp_path / "missing-chrome",
+            user_data_dir=tmp_path,
+        )
+
+
+def test_build_config_rejects_profile_paths(tmp_path: Path) -> None:
+    with pytest.raises(ConfigurationError):
+        build_chrome_launch_config(
+            browser_path=None,
+            user_data_dir=tmp_path,
+            profile_directory="Default/Nested",
+        )
+
+
+def test_launch_chrome_passes_resolved_config_to_sync_playwright(
+    tmp_path: Path,
+) -> None:
+    fake = FakeSyncPlaywright()
+
+    context = launch_chrome(
+        fake,  # type: ignore[arg-type]
+        browser_path=None,
+        user_data_dir=tmp_path,
+        profile_directory=None,
+        args=["--foo"],
+        base_url="https://example.com",
+    )
+
+    assert context == "sync-context"
+    assert fake.chromium.calls == [
+        (
+            tmp_path,
+            {
+                "channel": "chrome",
+                "headless": False,
+                "args": [
+                    "--disable-blink-features=AutomationControlled",
+                    "--start-maximized",
+                    "--foo",
+                ],
+                "ignore_default_args": DEFAULT_IGNORE_DEFAULT_ARGS,
+                "no_viewport": True,
+                "base_url": "https://example.com",
+            },
+        ),
+    ]
+
+
+def test_async_launch_chrome_passes_resolved_config_to_async_playwright(
+    tmp_path: Path,
+) -> None:
+    async def run() -> None:
+        fake = FakeAsyncPlaywright()
+        context = await async_launch_chrome(
+            fake,  # type: ignore[arg-type]
+            browser_path=None,
+            user_data_dir=tmp_path,
+            profile_directory="Default",
+            headless=True,
+        )
+
+        assert context == "async-context"
+        assert fake.chromium.calls == [
+            (
+                tmp_path,
+                {
+                    "channel": "chrome",
+                    "headless": True,
+                    "args": [
+                        "--disable-blink-features=AutomationControlled",
+                        "--profile-directory=Default",
+                    ],
+                    "ignore_default_args": DEFAULT_IGNORE_DEFAULT_ARGS,
+                    "no_viewport": True,
+                },
+            ),
+        ]
+
+    asyncio.run(run())