OpenParable
Skip to content
← Back to skills

Chrome Cdp

Testing & Quality
chrome-cdp

Chrome Cdp is an Agent Skill for testing & quality published in the mattzcarey/shippie repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Drive a headless Chrome over the Chrome DevTools Protocol (CDP) for browser QA — navigate, click, fill forms, read the DOM/accessibility tree, screenshot, and assert. Use whenever a task requires loading a web page and interacting with it like a user. Chrome is launched by a bash step (recipe below); this skill attaches over CDP — no MCP server, no Puppeteer/Playwright needed to drive.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/mattzcarey/shippie/blob/HEAD/src/skills/chrome-cdp/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/chrome-cdp, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Driving Chrome over CDP (no MCP, no Playwright-for-driving)

scripts/cdp.mjs is a dependency-free CLI (Node 22+ built-in WebSocket). You launch headless Chrome from a bash step, then attach to it on a port. Every command is:

node .agents/skills/chrome-cdp/scripts/cdp.mjs --port $PORT <command> <target> [args]

where <target> is a targetId prefix from cdp list (copy the prefix shown, e.g. 18EB6379).

1. Launch ONCE per flow — survives across bash calls

Each bash tool call is a fresh process group, so a launched browser is only reachable later if it is detached. The helper handles that portably (setsid on Linux, nohup+disown on macOS), uses $CHROME_BIN, bakes in --no-sandbox --disable-dev-shm-usage (mandatory as root / in a container), and blocks until the CDP endpoint is ready. Use a unique port per flow (parallel-safe):

PORT=$(( 9222 + ${FLOW_INDEX:-0} ))
bash .agents/skills/chrome-cdp/scripts/launch-chrome.sh "$PORT"

2. Drive it. --port $PORT re-discovers the ws endpoint via /json/version each call —

no shell variable survives between bash calls, only the port does.

CDP="node .agents/skills/chrome-cdp/scripts/cdp.mjs --port $PORT"
T=$($CDP list | head -1 | awk '{print $1}')        # the open page's targetId prefix
$CDP nav  "$T" "$BASE_URL/login"
$CDP snap "$T"                                       # accessibility tree → derive getByRole locators
$CDP fill "$T" "input[name=email]" "[email protected]" # focus + select + insertText (React/Vue-safe)
$CDP fill "$T" "input[name=password]" "hunter2"
$CDP click "$T" "button[type=submit]"               # JS el.click() via eval — covers standard buttons/links
# $CDP clickxy "$T" 412 388                          # real Input.dispatchMouseEvent at CSS px, for
#                                                     #   real-input-only handlers (see `shot` DPR note)
$CDP eval "$T" "location.pathname"                  # assert post-conditions
$CDP shot "$T" /tmp/f$PORT-01.png                   # then `read` the PNG (vision) to assert visually
$CDP evalraw "$T" "DOM.getDocument" '{}'             # raw-CDP escape hatch (method + JSON params)

Notes:

  • fill <target> <selector> <text> is the reliable way to set a form field — it focuses the element, selects existing content, then Input.insertText so frameworks see real input events.
  • Raw type <target> <text> has no selector; it inserts at whatever currently has focus.
  • click is el.click() via eval — won't fire real-input-only handlers (drag, native pickers); use clickxy with CSS pixels for those.
  • Prefer snap (accessibility tree) to find stable, semantic elements (by role / name / label), then translate them to robust CSS selectors (e.g. input[name=email], button[type=submit], [aria-label="Email"]) for the committed CDP test — far more resilient than coordinates.

2a. Record a flow → generate a test → add assertions → run (preferred authoring loop)

Don't hand-write the replay from memory. Set $CDP_RECORD to a scratch JSONL path and drive the WHOLE flow once: cdp.mjs appends one JSON op per successful nav/fill/click/ type/clickxy — so the log holds selectors that actually worked. Then gen-test.mjs turns that log into a faithful e2e/tests/<slug>.cdp.mjs (imports ../cdp-client.mjs, replays your captured actions, leaves a // TODO: add assertions marker + safe placeholder asserts).

$CDP_RECORD is read fresh on each cdp.mjs call, but export does NOT survive between separate bash tool calls (each is a fresh process group). Drive the whole flow in ONE bash call (recommended), or inline CDP_RECORD=/tmp/$SLUG.jsonl on every command.

SLUG=login
export CDP_RECORD=/tmp/$SLUG.jsonl
rm -f "$CDP_RECORD"                                   # don't append onto a stale log
CDP="node .agents/skills/chrome-cdp/scripts/cdp.mjs --port $PORT"
T=$($CDP list | head -1 | awk '{print $1}')
$CDP nav  "$T" "$BASE_URL/login"
$CDP fill "$T" "input[name=email]" "[email protected]"  # use `snap` to pick resilient selectors
$CDP fill "$T" "input[name=password]" "hunter2"
$CDP click "$T" "button[type=submit]"
# only SUCCESSFUL actions are logged — a failed selector leaves no line in the log

# generate the test skeleton FROM the recording (not from memory):
node .agents/skills/chrome-cdp/scripts/gen-test.mjs \
  --from "$CDP_RECORD" --out e2e/tests/$SLUG.cdp.mjs --name "$SLUG" --base "$BASE_URL"

Then OPEN e2e/tests/$SLUG.cdp.mjs, replace the // TODO: add assertions block with the flow's real user-visible guarantee (waitForText / assert.match on b.text(...), etc.) — keep the replayed actions (verified selectors). VERIFY with run_spec; fix the test (asserts/ waits, or re-record a bad selector) until it exits 0. Teardown: unset CDP_RECORD (or delete /tmp/$SLUG.jsonl) and stop Chrome at flow end.

Concurrent drivers on different ports MUST use different $CDP_RECORD paths (e.g. /tmp/$SLUG.jsonl, unique per flow) or their logs interleave.

3. Remote browser override seam (do NOT use in v0)

node .agents/skills/chrome-cdp/scripts/cdp.mjs \
  --ws-endpoint "$CDP_WS_ENDPOINT" --headers "$CDP_HEADERS" snap "$T"

4. Teardown at flow end (you own the lifecycle; flue won't reap it)

node .agents/skills/chrome-cdp/scripts/cdp.mjs --port $PORT stop || true
pkill -f "remote-debugging-port=$PORT" || true

Coordinates (for clickxy)

shot saves an image at native resolution: image px = CSS px × DPR. clickxy takes CSS pixels (CSS px = image px / DPR). shot prints the page DPR; on a typical Retina (DPR=2) divide by 2.