@accesslint/chrome
Ensure a debuggable Chrome that AccessLint's live-DOM audits can drive, and manage its lifecycle.
The AccessLint CLI (@accesslint/cli) is a pure CDP client: give it a debug
endpoint and a URL, and it injects @accesslint/core and audits. It does not
launch Chrome. This package fills that gap — and launches Chrome detached so
it outlives the one-shot launcher process that started it.
Why a separate package
chrome-launcher's launch() ties Chrome's lifetime to the calling process,
which is wrong for a npx-style one-shot: when the command exits, Chrome would
die before the audit connects. So this package spawns Chrome detached, records
its pid + throwaway profile to a state file, and exposes explicit stop.
It also encodes the HTTP-discovery trap: a Chrome opened via the DevTools
checkbox (or chrome-devtools-mcp) holds the debug port open but serves only a
WebSocket — chrome-remote-interface can't drive it. This package treats a
Chrome as usable only when /json/version answers, never on a bare TCP probe.
When you pin a port (--port or ACCESSLINT_CDP_PORT) it fails if that port is
squatted, so callers stay pointed at the port they asked for; an unpinned
ensure steps to the next free port instead.
Usage
# Get-or-launch a driveable Chrome; prints its endpoint as JSON.
npx @accesslint/chrome ensure
# → {"ok":true,"mode":"launched","host":"127.0.0.1","port":9222,"pid":1234,"managed":true,...}
# Idempotent: a second ensure attaches to the running one.
npx @accesslint/chrome ensure # → {"mode":"attached",...}
# Tear it down.
npx @accesslint/chrome stop --all
Commands
| Command | What it does |
|---|---|
ensure | Attach to a driveable Chrome on the port, or launch a detached one. |
stop | Kill a managed instance (--port) or all of them (--all) and clean up. |
Options
-p, --port <n> CDP port to attach to / launch on (default 9222)
--headed Launch a visible Chrome instead of headless (ensure)
--download Download a managed Chrome for Testing if none is installed (ensure)
--all Stop every managed instance (stop)
If the default port is occupied by an undriveable Chrome (checkbox mode),
an unpinned ensure steps to a free port and reports the actual one — read
port from its JSON output. If you pinned that port with --port, ensure
fails instead; free the port or pass a different one.
By default ensure uses the system Chrome (CHROME_PATH or a platform search)
and fails if none is found. Pass --download (or set ACCESSLINT_CHROME_DOWNLOAD=1)
to fall back to a pinned Chrome for Testing build fetched via
@puppeteer/browsers into a cache dir. The download (~170MB) happens once on
first use; later runs reuse the cached binary. A system Chrome, when present,
always wins — the download is only a fallback.
Environment
ACCESSLINT_CDP_PORT default port
CHROME_PATH override Chrome binary discovery
ACCESSLINT_CHROME_DOWNLOAD 1/true to enable the Chrome for Testing fallback
ACCESSLINT_CHROME_CACHE_DIR where downloaded Chrome is cached (default ~/.cache/accesslint-chrome)
Library API
import { ensure, stop } from "@accesslint/chrome";
const chrome = await ensure({ port: 9222 }); // { mode, host, port, pid, managed, ... }
// … run an audit against chrome.host:chrome.port …
await stop({ port: chrome.port });
License
MIT