electron-cdp-automation

Electron CDP Automation

Electron embeds Chromium, so packaged apps can be launched with --remote-debugging-port, then controlled from an external Node script via CDP to inject JS and manipulate the DOM. No source code access required.

Four traps are almost guaranteed to bite you, and all look "correct" — read this through before writing code, or you'll spend hours debugging an await that can never succeed.

Step 0: Verify the Debug Port Works First (Don't Skip This)

Validate this step before writing any automation code. The app may have debugging disabled, at which point the entire CDP route is impossible — better to find out early.

# Launch (any port 9000-65535)
./YourApp.exe --remote-debugging-port=9222 --remote-allow-origins=*

# Verify in another terminal
curl http://localhost:9222/json/version

Works — returns JSON containing webSocketDebuggerUrl:

{"Browser":"Chrome/120.0.6099.109","Protocol-Version":"1.3",
 "webSocketDebuggerUrl":"ws://localhost:9222/devtools/browser/..."}

Doesn't work — connection refused / timeout / app reports "unsupported parameter" / app launches normally but port doesn't listen.

When it doesn't work, inform the user CDP automation is not possible and provide alternatives. Don't try to work around it (changing ports, adding --inspect, injecting DLLs won't solve build-time disabled debugging):

❌ This app has remote debugging disabled. CDP automation is not possible.

Possible reasons: Disabled during build / Enterprise security policy / ASAR hardening.

Alternatives:
  1. OS-level automation — Windows UI Automation, pyautogui, AutoHotkey
     (based on coordinates and control trees, doesn't depend on debug port)
  2. If you have source access, add to main.js:
     app.commandLine.appendSwitch('remote-debugging-port', '9222')
     For testing builds only, never ship this
  3. If the app has a CLI / HTTP API, use that instead

Also remind: Never open debug ports in production — any local process can completely control the app through it.