dsh-cdp-browser
Zero-spawn browser automation + pixel-level visual verification as a DeepSeek
Harness plugin. Drives an already-running Chrome/Edge over CDP using Node
built-ins only: global fetch + global WebSocket (Node ≥ 22) + zlib PNG
decode. No child_process, no npm dependencies, no per-use approval.
Why zero-spawn
Plugins that spawn an engine and pipe its stdio (e.g. modlens) collide with
the harness sandbox's pipe ban (EPERM/EINVAL) on every call. Connecting to a
browser the user started themselves is plain network I/O — allowed in confined
mode. The one manual step (launching the browser) happens outside the
harness, so the model never needs approval again for visual checks.
Setup (once)
-
Install into the profile (done via
dsh plugin --profile web add file:<path>). -
Start your browser with CDP (the provided
edge-debug.cmddoes this):msedge.exe --remote-debugging-port=9222 --remote-allow-origins=* --user-data-dir=<dir> <url> -
Restart the Web GUI. The
cdp_*tools appear in the next session.
Tools
| Tool | What it does |
|---|---|
cdp_status |
List tabs/targets of the CDP browser + browser version |
cdp_open |
Open (or reuse) a tab for a url; returns target id |
cdp_eval |
Evaluate JS in a page (awaitPromise, returnByValue) |
cdp_shot |
Navigate + PNG screenshot, saved to an absolute path |
cdp_assert |
Scripted interaction + deterministic checks (pixel / css / dom / js) with a pass/fail report |
cdp_assert check shapes
checks: [
{ type: 'pixel', x: 0.5, y: 0.96, color: '#245edb', tolerance: 16 }, // relative coords 0..1 or absolute px
{ type: 'css', selector: '#taskbar', property: 'background-color', equals: 'rgb(36, 94, 219)' },
{ type: 'css', selector: '.xp-window', property: 'border-radius', matches: '^\\d+px' },
{ type: 'dom', selector: '.xp-desk-icon', text: 'My Computer' },
{ type: 'js', expression: 'window.__XP.selfTest()', equals: { ok: true } },
]
// every check accepts click: '#start-btn' | { selector } | { x, y } and waitMsDevelopment
node plugins/dsh-cdp-browser/test/e2e.mjs # needs dev server + CDP Edge, starts nothingDeterminism notes (learned from the XP app's first plugin e2e):
- Reload the page per test run. A long-lived tab accumulates state across
scripted sweeps (windows, dialogs, menus) and can wedgeopenApp; a fresh
navigate+skipBootper suite is deterministic.probe-apps.mjsbisects
per-app hangs when an app regresses. - Synthetic clicks toggle state.
el.click()runs the real handlers —
clicking a toggle twice flips it twice. One click per assertion. - Gradient surfaces need stop-aware sampling. Sample where a gradient stop
dominates (flat zones or edges), not mid-gradient blends, or use
tolerance-awarenearColoragainst computed-style values.
The package exposes ./cdp (targets, openTarget, withPage, Cdp,
decodePng, samplePixel, nearColor, runChecks, savePng) for reuse
outside the harness.