rules_chrome

bazel_dep(name = "rules_chrome", version = "0.1.1")

common --registry=https://registry.fastverk.com/
common --registry=https://bcr.bazel.build/

bazel_dep(name = "rules_chrome", version = "0.1.0")

chrome = use_extension("@rules_chrome//chrome:extensions.bzl", "chrome")
use_repo(chrome, "chrome", "chromedriver")
register_toolchains("@chrome//:chrome_toolchain_def")

chrome.toolchain(version = "148.0.7778.167")

# BUILD.bazel
load("@rules_chrome//chrome:defs.bzl", "chrome_run", "chromedriver_run")

chrome_run(
    name = "browser",
    headless = True,
    extra_args = ["--disable-gpu"],
)

chromedriver_run(
    name = "driver",
    port = 9515,
)

bazel run //:browser -- https://example.com
bazel run //:driver

sh_test(
    name = "page_loads",
    srcs = ["page_loads.sh"],
    data = [
        "@chrome//:chrome",
        "@chromedriver//:chromedriver",
    ],
)

tools/refresh_versions.py --version 148.0.7778.167

# MODULE.bazel — add rules_python and your own pip hub
bazel_dep(name = "rules_python", version = "2.0.1")

pip = use_extension("@rules_python//python/extensions:pip.bzl", "pip")
pip.parse(
    hub_name = "my_pip",
    python_version = "3.12",
    requirements_lock = "//:requirements_lock.txt",   # must include playwright
)
use_repo(pip, "my_pip")

# BUILD.bazel
load("@rules_chrome//chrome/playwright:py.bzl", "playwright_chrome_py_test")
load("@my_pip//:requirements.bzl", "requirement")

playwright_chrome_py_test(
    name = "browser_test",
    srcs = ["browser_test.py"],
    user_data_dir_mode = "workspace",  # persistent profile under bazel run
    deps = [requirement("playwright")],
)

# browser_test.py
from rules_chrome_playwright import chrome_context

def test_thing():
    with chrome_context() as ctx:           # BrowserContext, not Browser
        page = ctx.new_page()
        page.goto("https://example.com")
        # cookies/extensions/local-storage survive across `bazel run` in workspace mode

bazel run //docs:update

tools/refresh_versions.py                       # latest Stable
tools/refresh_versions.py --channel Beta        # latest Beta
tools/refresh_versions.py --version 149.0.7800.0   # specific build

Real usage, taken from the module’s examples/.

examples/smoke/BUILD.bazel

load("@aspect_rules_js//js:defs.bzl", "js_test")
load("@rules_chrome//chrome:defs.bzl", "chrome_run", "chromedriver_run")
load("@rules_chrome//chrome/playwright:js.bzl", "playwright_chrome_js_test")
load("@rules_chrome//chrome/playwright:py.bzl", "playwright_chrome_py_test")
load("@rules_python//python:py_test.bzl", "py_test")
load("@rules_shell//shell:sh_test.bzl", "sh_test")
load("@smoke_npm//:defs.bzl", "npm_link_all_packages")
load("@smoke_pip//:requirements.bzl", "requirement")

# `bazel run //examples/smoke:chrome` — launches headless chrome with a
# fresh ephemeral profile. Verifies the toolchain resolves and the
# binary executes on the host.
chrome_run(
    name = "chrome",
    extra_args = ["--disable-gpu"],
    headless = True,
)

# `bazel run //examples/smoke:chromedriver` — launches chromedriver on
# the OS-assigned port. Read it from chromedriver's stdout.
chromedriver_run(
    name = "chromedriver",
)

# Smoke test: `chrome --version` exits 0 and prints a version string.
sh_test(
    name = "chrome_version_test",
    srcs = ["version_smoke.sh"],
    args = ["$(rootpath @chrome//:chrome)"],
    data = ["@chrome"],
)

# Smoke test: `chromedriver --version` exits 0 and prints a version string.
sh_test(
    name = "chromedriver_version_test",
    srcs = ["version_smoke.sh"],
    args = ["$(rootpath @chromedriver//:chromedriver)"],
    data = ["@chromedriver"],
)

# Playwright integration: launches headless chrome via the @chrome
# launcher, drives it over CDP, evaluates a trivial JS expression.
# Confirms our wrapper survives Playwright's subprocess-spawn /
# CDP-handshake path (chromedriver isn't in this loop — Playwright
# speaks CDP directly).
py_test(
    name = "playwright_smoke_test",
    srcs = ["playwright_smoke.py"],
    args = ["$(rootpath @chrome//:chrome)"],
    data = ["@chrome"],
    # Playwright's launch spawns a subprocess and refuses to find its
    # bundled node driver if PATH is empty under sandboxing — let it
    # inherit the host PATH. Same goes for HOME (used by tmpdir).
    env_inherit = [
        "PATH",
        "HOME",
    ],
    main = "playwright_smoke.py",
    deps = [requirement("playwright")],
)

# Materialize the @smoke_npm/* labels under this package so js_test can
# depend on `//examples/smoke:node_modules/playwright`. The macro
# expands per pnpm-lock entry — no per-package boilerplate.
npm_link_all_packages(name = "node_modules")

# Playwright (Node) integration: same shape as the py_test, but
# exercises Playwright's primary (Node) bindings rather than the Python
# wrapper. Covers the launcher under a different subprocess-spawn path.
js_test(
    name = "playwright_node_smoke_test",
    args = ["$(rootpath @chrome//:chrome)"],
    data = [
        "playwright_smoke.js",
        ":node_modules/playwright",
        "@chrome",
    ],
    entry_point = "playwright_smoke.js",
    env = {
        # Skip the post-install chromium fetch. We point Playwright at
        # @chrome via executablePath; its bundled browser is dead weight.
        "PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD": "1",
    },
)

# `playwright_chrome_py_test` macro smoke: exercises the rules_chrome
# sub-module abstraction (env wiring + helper module) end-to-end.
# Ephemeral mode → profile lives under $TEST_TMPDIR.
playwright_chrome_py_test(
    name = "playwright_module_py_test",
    srcs = ["playwright_module_smoke.py"],
    deps = [requirement("playwright")],
)

# Same shape, JS side — `playwright_chrome_js_test` macro.
playwright_chrome_js_test(
    name = "playwright_module_js_test",
    data = [":node_modules/playwright"],
    entry_point = "playwright_module_smoke.js",
)

# Workspace-mode coverage: fakes BUILD_WORKSPACE_DIRECTORY so the
# launch_persistent_context path that's normally only reachable via
# `bazel run` (not `bazel test`) gets CI coverage too. Also exercises
# the helper's clear-error behavior when the env var is missing.
playwright_chrome_py_test(
    name = "playwright_workspace_mode_test",
    srcs = ["workspace_mode_smoke.py"],
    deps = [requirement("playwright")],
)

from docs/defs.md

User-facing Bazel rules for rules_chrome.

Exports two bazel run-friendly launchers:

• chrome_run: launches Chrome for Testing with an isolated user-data-dir and the standard testing flags pre-applied. Reusable across smoke tests, screenshot tools, scripted browser sessions.
• chromedriver_run: launches chromedriver on a configurable port; used as the WebDriver backend for selenium / playwright / pytest-selenium.

Both rules resolve their binaries through @rules_chrome//chrome:toolchain_type, so consumers can swap in a locally-built or alternate-channel chrome via register_toolchains(...) without editing target attributes.

For the bare binaries (without launcher ergonomics) consumers can depend directly on @chrome//:chrome and @chromedriver//:chromedriver.

chrome_run

load("@rules_chrome//chrome:defs.bzl", "chrome_run")

chrome_run(name, extra_args, headless, user_data_dir, user_data_dir_mode)

Run Chrome for Testing via bazel run, with a managed user-data-dir and the standard automation flags pre-applied. Additional CLI arguments are forwarded to chrome verbatim.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
extra_args	Extra command-line flags appended after the rules_chrome defaults but before any args passed on the CLI. Use this to bake in test-specific flags (e.g. --remote-debugging-port=9222).	List of strings	optional	[]
headless	Append --headless=new to the command line.	Boolean	optional	False
user_data_dir	Workspace-relative profile path used when user_data_dir_mode = "workspace". Defaults to .cache/rules_chrome/<target name>.	String	optional	""
user_data_dir_mode	How to seed --user-data-dir: * ephemeral (default): a fresh $TMPDIR/chrome_run.XXXXXX per invocation, cleaned on exit. Safe for tests and parallel runs. * workspace: a persistent directory under $BUILD_WORKSPACE_DIRECTORY/<user_data_dir> (cookies, extensions, signed-in state survive across bazel run). Requires bazel run. * system: omit --user-data-dir entirely. Chrome uses the real per-user profile — almost never what you want for automation.	String	optional	"ephemeral"

chromedriver_run

load("@rules_chrome//chrome:defs.bzl", "chromedriver_run")

chromedriver_run(name, extra_args, port)

Run chromedriver via bazel run. The matching driver version is resolved through the registered chrome toolchain; extra CLI arguments are forwarded to chromedriver verbatim.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
extra_args	Extra command-line flags appended after the configured --port and before any args passed on the CLI.	List of strings	optional	[]
port	Listen port. 0 (default) lets chromedriver pick — read the chosen port from its first line of stdout.	Integer	optional	0

from docs/extensions.md

Module extension for rules_chrome.

Auto-fetches the prebuilt Chrome for Testing + chromedriver binaries for the host platform. Versions are pinned by sha256 in private/known_versions.bzl. Consumers can override the version via the toolchain tag class.

Default usage (pulls the default-pinned Chrome + chromedriver):

chrome = use_extension("@rules_chrome//chrome:extensions.bzl", "chrome")
use_repo(chrome, "chrome", "chromedriver")
register_toolchains("@chrome//:chrome_toolchain_def")

Pin a specific Chrome for Testing version:

chrome = use_extension("@rules_chrome//chrome:extensions.bzl", "chrome")
chrome.toolchain(version = "148.0.7778.167")
use_repo(chrome, "chrome", "chromedriver")

chrome

chrome = use_extension("@rules_chrome//chrome:extensions.bzl", "chrome")
chrome.toolchain(version)

Sets up @chrome and @chromedriver as Bazel-fetched prebuilt binaries.

TAG CLASSES

toolchain

Attributes

Name	Description	Type	Mandatory	Default
version	Override the Chrome for Testing version. Defaults to the value in known_versions.bzl.	String	optional	""

from docs/playwright_js.md

Playwright (Node) wrappers for rules_chrome.

Exports playwright_chrome_js_test, a thin macro over js_test (aspect_rules_js) that wires @chrome into the test’s runfiles and exposes a Bazel-managed user-data-dir through env vars. The runtime helper at @rules_chrome//chrome/playwright:rules_chrome_playwright.js reads those env vars and returns a Playwright BrowserContext via launchPersistentContext.

Consumers bring their own playwright npm dep (so the version isn’t pinned by rules_chrome). The typical layout:

bazel_dep(name = "rules_chrome", version = "...")
bazel_dep(name = "aspect_rules_js", version = "...")
bazel_dep(name = "rules_nodejs", version = "...")

node = use_extension("@rules_nodejs//nodejs:extensions.bzl", "node")
node.toolchain(node_version = "22.11.0")

npm = use_extension("@aspect_rules_js//npm:extensions.bzl", "npm")
npm.npm_translate_lock(
    name = "my_npm",
    pnpm_lock = "//:pnpm-lock.yaml",  # must include playwright
)
use_repo(npm, "my_npm")

chrome = use_extension("@rules_chrome//chrome:extensions.bzl", "chrome")
use_repo(chrome, "chrome", "chromedriver")

In your BUILD.bazel:

load("@rules_chrome//chrome/playwright:js.bzl", "playwright_chrome_js_test")
load("@my_npm//:defs.bzl", "npm_link_all_packages")

npm_link_all_packages(name = "node_modules")

playwright_chrome_js_test(
    name = "browser_test",
    entry_point = "browser_test.js",
    data = [":node_modules/playwright"],
)

Then in browser_test.js:

const { withChromeContext } = require(process.env.RULES_CHROME_PLAYWRIGHT_HELPER);

withChromeContext(async (ctx) => {
    const page = await ctx.newPage();
    await page.goto('about:blank');
    if (await page.evaluate(() => 1 + 1) !== 2) process.exit(1);
});

playwright_chrome_js_test

load("@rules_chrome//chrome/playwright:js.bzl", "playwright_chrome_js_test")

playwright_chrome_js_test(name, entry_point, user_data_dir_mode, user_data_dir, headless, data, env,
                          env_inherit, **kwargs)

Define a Node test that drives Chrome for Testing through Playwright.

PARAMETERS

Name	Description	Default Value
name	Test target name.	none
entry_point	Path to the JS file to execute. The script reads the helper’s runfiles path from RULES_CHROME_PLAYWRIGHT_HELPER.	none
user_data_dir_mode	One of "ephemeral" (fresh per test, default — cleaned by Bazel’s sandbox via $TEST_TMPDIR) or "workspace" (persistent under $BUILD_WORKSPACE_DIRECTORY/<user_data_dir>). "workspace" mode requires bazel run — Bazel’s test sandbox doesn’t set BUILD_WORKSPACE_DIRECTORY, so bazel test will fail at runtime.	"ephemeral"
user_data_dir	Workspace-relative profile path for workspace mode. Defaults to .cache/rules_chrome_playwright/<name>.	""
headless	Whether to run chrome in headless mode (default True).	True
data	Extra js_test data. @chrome, the helper JS file, and any node_modules deps the consumer adds get appended. The playwright npm package (:node_modules/playwright) must be included here (consumer-supplied).	None
env	Extra env vars. The macro adds RULES_CHROME_PATH, RULES_CHROME_PLAYWRIGHT_HELPER, RULES_CHROME_PROFILE_REL (workspace mode only), and RULES_CHROME_HEADFUL (when headless = False).	None
env_inherit	Extra env vars to inherit from the host. PATH and HOME are inherited by default — Playwright needs both.	None
kwargs	Forwarded to js_test.	none

from docs/playwright_py.md

Playwright (Python) wrappers for rules_chrome.

Exports playwright_chrome_py_test, a thin macro over py_test that wires @chrome into the test’s runfiles and exposes a Bazel-managed user-data-dir through env vars. The runtime helper at @rules_chrome//chrome/playwright:helper.py reads those env vars and returns a Playwright BrowserContext via launch_persistent_context.

Consumers bring their own playwright pip dep (so the version isn’t pinned by rules_chrome). The typical layout:

bazel_dep(name = "rules_chrome", version = "...")
bazel_dep(name = "rules_python", version = "...")

pip = use_extension("@rules_python//python/extensions:pip.bzl", "pip")
pip.parse(
    hub_name = "my_pip",
    python_version = "3.12",
    requirements_lock = "//:requirements_lock.txt",  # must include playwright
)
use_repo(pip, "my_pip")

chrome = use_extension("@rules_chrome//chrome:extensions.bzl", "chrome")
use_repo(chrome, "chrome", "chromedriver")

In your BUILD.bazel:

load("@rules_chrome//chrome/playwright:py.bzl", "playwright_chrome_py_test")
load("@my_pip//:requirements.bzl", "requirement")

playwright_chrome_py_test(
    name = "browser_test",
    srcs = ["browser_test.py"],
    deps = [requirement("playwright")],
)

Then in browser_test.py:

from rules_chrome_playwright import chrome_context

def test_x():
    with chrome_context() as ctx:
        page = ctx.new_page()
        page.goto("about:blank")
        assert page.evaluate("1+1") == 2

playwright_chrome_py_test

load("@rules_chrome//chrome/playwright:py.bzl", "playwright_chrome_py_test")

playwright_chrome_py_test(name, srcs, main, user_data_dir_mode, user_data_dir, headless, deps, data,
                          env, env_inherit, **kwargs)

Define a Python test that drives Chrome for Testing through Playwright.

PARAMETERS

Name	Description	Default Value
name	Test target name.	none
srcs	Python source files.	none
main	Entry-point Python file. Defaults to srcs[0] when a single src is given, so srcs = ["browser_test.py"] Just Works regardless of the target’s name.	None
user_data_dir_mode	One of "ephemeral" (fresh per test, default — cleaned by Bazel’s sandbox via $TEST_TMPDIR) or "workspace" (persistent under $BUILD_WORKSPACE_DIRECTORY/<user_data_dir>). "workspace" mode requires bazel run — Bazel’s test sandbox doesn’t set BUILD_WORKSPACE_DIRECTORY, so bazel test will fail at runtime.	"ephemeral"
user_data_dir	Workspace-relative profile path for workspace mode. Defaults to .cache/rules_chrome_playwright/<name>.	""
headless	Whether to run chrome in headless mode (default True).	True
deps	Extra py_test deps. The playwright pip requirement must be included here (consumer-supplied). The helper py_library is added automatically.	None
data	Extra py_test data. @chrome is added automatically.	None
env	Extra env vars. The macro adds RULES_CHROME_PATH, RULES_CHROME_PROFILE_REL (workspace mode only), and RULES_CHROME_HEADFUL (when headless = False).	None
env_inherit	Extra env vars to inherit from the host. PATH and HOME are inherited by default — Playwright needs both to spawn its bundled node driver.	None
kwargs	Forwarded to py_test.	none

from docs/toolchains.md

Toolchain rule for rules_chrome.

chrome_toolchain wraps a Chrome for Testing binary plus the matching chromedriver as a single Bazel toolchain. Consumers (the chrome_run and chromedriver_run rules) resolve chrome through @rules_chrome//chrome:toolchain_type, so users can register custom chrome builds (locally-built fork, dev/canary channel, …) via register_toolchains(...) without modifying rule attributes.

The module extension at @rules_chrome//chrome:extensions.bzl generates a default toolchain (@chrome//:chrome_toolchain_def) wrapping the prebuilt binaries. Users register it from their MODULE.bazel:

register_toolchains("@chrome//:chrome_toolchain_def")

chrome_toolchain

load("@rules_chrome//chrome:toolchains.bzl", "chrome_toolchain")

chrome_toolchain(name, chrome, chromedriver)

Declare a Chrome for Testing binary + chromedriver as a Bazel toolchain.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
chrome	The chrome executable target (its runfiles carry the rest of the bundle).	Label	required
chromedriver	The chromedriver executable target. Optional — leave unset for chrome-only setups.	Label	optional	None

ChromeToolchainInfo

load("@rules_chrome//chrome:toolchains.bzl", "ChromeToolchainInfo")

ChromeToolchainInfo(chrome, chromedriver)

The Chrome for Testing binaries, resolved via a toolchain.

FIELDS

Name	Description
chrome	Target: the chrome executable target (carries its bundle as runfiles).
chromedriver	Target: the chromedriver executable target. May be None if the toolchain was registered without driver support.