Driving the Electron app

Electron App Driving launches a project's Electron application under Playwright using scripts/drive.mjs. A background daemon keeps the application running between shell calls, so inspection and actions share the same session. Every launch uses a scratch profile, allowing first-run checks or bug reproduction without directing userData to the user's normal profile. Data stored outside userData still requires explicit configuration before write operations.

The workflow starts with a snapshot or screenshot of the current window, then uses Playwright selectors to click, fill, wait, select, or press keys. Role and name selectors from the accessibility snapshot are preferred, followed by text and CSS. Screenshot output provides a PNG path, while logs combine main and renderer console messages with an optional configured log file. First-run verification can use:

$DR start --build --fresh
$DR snapshot
$DR click 'role=button[name=/Next/]'
$DR screenshot
$DR logs --lines 40
$DR stop

The DR variable must refer to the skill's script. Start can rebuild the configured application, clear the scratch profile, select a named profile, or use development settings. Applications running from compiled output need a rebuild after source changes. Production builds are preferred when reproducing failures such as stricter Content-Security-Policy behavior.

Use it for running Electron UI changes, startup and renderer bugs, onboarding or settings screens, and features that cross the preload IPC bridge into the main process. Web apps without Electron and multi-window flows are outside its scope. Commands target the first window that is not DevTools; a splash screen remains the target until it closes. Only one application runs per project, and start refuses a second launch.

The skill requires Node.js 18 or later, Electron, and playwright-core 1.49 or later installed in the project. Missing dependencies are reported to the user rather than installed automatically. It does not replace the project's tests or a human visual-design check.

Optional drive.config.json settings provide the build command, Electron arguments, additional environment values, log path, and development launch settings. Profile substitution applies to environment values, allowing an application's actual external-data variable to point into the scratch directory. A variable name alone has no effect unless the app reads it. Read the config before the first --build: its build command runs in a shell. Missing builds or failed build commands stop launch, and --build cannot be combined with --dev. The driver discovers the project through its nearest package.json and checks an existing daemon before starting another.

wait accepts an optional --timeout in milliseconds; screenshot accepts --out and a CSS --selector. A -- separator preserves text beginning with dashes. Commands send authenticated JSON requests to the local daemon and surface returned errors. stop removes stale state and handles an orphaned Electron process if the daemon has disappeared.

Renderer eval and main-process main commands return JSON-compatible data and accept code from standard input. Preload calls through eval exercise the actual renderer bridge. Main-process code has application privileges and full Node.js access, so actions are limited to the task and require confirmation for exceptional deletion or network behavior.

The daemon listens locally on 127.0.0.1 using a random session token and sends nothing to third-party services. Development mode checks the renderer server before launch and avoids a second Electron instance. Always stop after success or failure, inspect abnormal shutdown reports, and run the script directly to avoid wrapper argument corruption. Windows uses node to invoke the script; its process-tree shutdown fallback is POSIX-only.