Testing Debugging

Testing & Debugging

Overview

Electron is Chromium + Node, so you test it by launching the real binary and driving it with a browser-automation tool, and you debug it as two separate things: the main process is a Node program (attach the Node inspector) and the renderer is a web page (attach Chrome DevTools).

When to use

• Writing end-to-end tests that open the app, click around, and assert window state.
• Unit-testing main-process logic, or wiring tests into CI that has no display (Linux) and fails before any test runs.
• Setting a breakpoint in main.js, inspecting why a window won't open, or poking at modules live.
• Loading React/Redux DevTools into the renderer.

When NOT to use: for hardening webPreferences/CSP see security; for startup/jank profiling see performance; for crash dumps see crash diagnostics.

Quick reference

| Goal | API / command | |---|---| | Launch app in a test | const app = await _electron.launch({ args: ['.'] }) (Playwright, recommended) | | Get the first window | const win = await app.firstWindow() | | Run code in the main process | await app.evaluate(({ app }) => app.isPackaged) | | Close the app | await app.close() | | WebdriverIO driver | services: ['electron'], cap wdio:electronServiceOptions | | Selenium driver | electron-chromedriver + goog:chromeOptions.binary → app exe | | Headless Linux CI | wrap the runner in xvfb-run or xvfb-maybe | | Debug main process | electron --inspect=9229 . (or --inspect-brk to pause on line 1) | | Attach a debugger | Chrome chrome://inspect, or VS Code launch.json (below) | | Debug renderer | win.webContents.openDevTools() | | Remote CDP port (dev only) | --remote-debugging-port=8315 — never ship this | | Load a DevTools extension | await session.defaultSession.loadExtension(unpackedDir) | | Live main-process REPL | electron --interactive (not on Windows) |

Example

// tests/launch.spec.ts — Playwright's _electron.launch is the recommended path.
// It spawns YOUR real Electron binary, then exposes both Node (main) and DOM (renderer).
import { test, expect, _electron as electron } from '@playwright/test'

test('opens the first window and shows the right title', async () => {
  // args: ['.'] launches the app in the current directory, like `electron .`
  const app = await electron.launch({ args: ['.'] })

  // app.evaluate runs IN the main process — you get the real `electron` module,
  // so you can assert on app/BrowserWindow state no test harness could fake.
  const isPackaged = await app.evaluate(async ({ app }) => app.isPackaged)
  expect(isPackaged).toBe(false) // running from source, not a packaged build

  // firstWindow() resolves to a Playwright Page bound to the renderer.
  const win = await app.firstWindow()
  expect(await win.title()).toBe('My Electron App')

  await app.close() // always close, or the spawned process leaks into CI
})

// .vscode/launch.json — debug the MAIN process. VS Code launches the Electron
// binary under the Node inspector; set breakpoints in main.js and hit F5.
{
  "version": "0.2.0",
  "configurations": [{
    "name": "Debug Main Process",
    "type": "node",
    "request": "launch",
    "cwd": "${workspaceFolder}",
    "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron",
    "windows": { "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron.cmd" },
    "args": ["."],
    "outputCapture": "std" // capture main-process stdout/stderr in the Debug Console
  }]
}

Common mistakes

• Forgetting await app.close() — leaked Electron processes hang CI runners and skew the next test.
• Running tests on Linux CI with no display — Chromium can't find a display driver and Electron never launches. Wrap the runner in xvfb-run / xvfb-maybe; on macOS/Windows they no-op.
• Confusing the two debuggers — --inspect/chrome://inspect is for the main (Node) process; the renderer uses webContents.openDevTools(). They are separate sessions.
• Calling session.loadExtension before app.whenReady() — it throws; load after ready and before navigating, and point at an unpacked dir, not a .crx.
• Shipping --remote-debugging-port in a release — it opens a full CDP control channel any local process can attach to. Dev only.

Reference

Full API tables: [reference.md](reference.md)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ohvignas
• Source: ohvignas/claude-electron-skills
• License: MIT

Install and usage instructions live in the source repository linked above.