# Testing Debugging

> Use when testing or debugging an Electron app — Playwright `_electron.launch`/`firstWindow`, WebdriverIO, Selenium `electron-chromedriver`, headless CI with no display (Xvfb, `xvfb-run`, `xvfb-maybe`), main-process breakpoints via `--inspect`/`--inspect-brk` + `chrome://inspect` or VS Code `launch.json`, renderer DevTools, `--remote-debugging-port`, `session.loadExtension`, `electron --interactiv…

- **Type:** Skill
- **Install:** `agentstack add skill-ohvignas-claude-electron-skills-testing-debugging`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ohvignas](https://agentstack.voostack.com/s/ohvignas)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ohvignas](https://github.com/ohvignas)
- **Source:** https://github.com/ohvignas/claude-electron-skills/tree/main/skills/testing-debugging

## Install

```sh
agentstack add skill-ohvignas-claude-electron-skills-testing-debugging
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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
```js
// 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
})
```

```jsonc
// .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](https://github.com/ohvignas)
- **Source:** [ohvignas/claude-electron-skills](https://github.com/ohvignas/claude-electron-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ohvignas-claude-electron-skills-testing-debugging
- Seller: https://agentstack.voostack.com/s/ohvignas
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.