Driving the Electron app

Overview

scripts/drive.mjs launches the project's Electron app under Playwright in a background daemon and keeps it running between commands, so each action (click, type, snapshot, screenshot, eval) is one fast shell call. Every launch uses a scratch profile, so the agent can check a UI change or reproduce a bug in the real app, not only in unit tests, without touching the user's data.

When to Use This Skill

• Use when you need to verify a UI change in the running Electron app.
• Use when reproducing a renderer or startup bug, or a failure that only shows up in the production build (for example a stricter CSP).
• Use when checking first-run, onboarding or settings screens.
• Use when exercising a feature end to end, including IPC through the preload bridge or code in the main process.
• Do not use it for web apps without Electron, or for multi-window flows (see Limitations).

How It Works

Step 1: Check prerequisites

scripts/drive.mjs, in this skill's directory, finds the project by the nearest package.json, so run it from anywhere inside the project. Set DR to its absolute path.

It needs electron and playwright-core (1.49 or later) installed in the project. If start says either is missing, tell the user rather than installing it yourself. Launch settings come from drive.config.json at the project root (see Step 4); with no file, it runs electron ..

Step 2: Start, look, act, stop

DR=<this skill's directory>/scripts/drive.mjs

$DR start                  # last build, profile 'default'; prints status
$DR snapshot               # accessibility tree: find what to click, by role and name
$DR click 'role=button[name="Get started"]'
$DR fill 'role=textbox[name="Email"]' 'test@example.com'
$DR wait 'text=Welcome'
$DR screenshot             # prints a PNG path; Read it to see the window
$DR logs --lines 80        # main and renderer console, plus the config's logFile
$DR stop                   # ALWAYS, before finishing

• Start options:
  • --build: run the config's build command first. Needed after any source change if the app runs from a build, because the build is otherwise stale; start prints its age.
  • --fresh: wipe the scratch profile, which gives you the app's first-run state.
  • --profile <name>: a separate scratch profile.
  • --dev: see Step 5.
• Targets are Playwright selectors. Prefer role=button[name="…"] from snapshot output, then text=…, then CSS.
• -- ends the flags. Put it before text that starts with dashes: $DR fill 'role=textbox[name="Args"]' -- --verbose.
• Other commands: select <target> <value|label>, press <key>, status, screenshot --selector <css>. $DR help lists everything.

Step 3: Run code in the app

eval <js> runs in the renderer, main <js> in the main process (electron and process are in scope, require is not). Use a bare expression, or a body with return. - reads the code from stdin, which avoids quoting entirely. The result comes back as JSON, so return plain data: a DOM node or a function comes back as undefined or {}.

To exercise IPC, call whatever the app's preload exposes through eval. That goes through the real preload bridge, as the app's own renderer code does.

Step 4: Configure the launch (optional)

drive.config.json at the project root; every field is optional:

{
  "build": "npm run build",
  "args": ["."],
  "env": { "APP_DATA_DIR": "{profile}/data" },
  "logFile": "logs/main.log",
  "dev": {
    "args": ["."],
    "env": { "ELECTRON_RENDERER_URL": "http://localhost:5173" },
    "url": "http://localhost:5173"
  }
}

• args: what Electron is launched with: an app directory whose package.json main is the built entry point, or the entry file itself.
• env: added to the app's environment. {profile} becomes the scratch profile directory (in env values only, not in args). This is how data kept outside userData is redirected: APP_DATA_DIR is only an example name, and it has an effect only if the app reads it. Check the app's source for the variable it actually uses.
• logFile: a log file relative to the profile directory, shown by logs.

If a project has no config and start fails or launches the wrong thing, work out these values from the project's package.json and build setup, then suggest a drive.config.json to the user.

…