Electron end-to-end tests with Playwright

# AGENTS.md: Electron app tested end to end with Playwright

An Electron desktop app with a sandboxed, context-isolated renderer and a narrow preload API. End-to-end tests
use Playwright's Electron support to drive the real app. Check `package.json` for the Electron and Playwright
versions before using an API.

## Commands

- Start: `npm start`.
- End-to-end tests: `npx playwright test` (Linux without a display: `xvfb-run -a npx playwright test`).
- One test: `npx playwright test -g "rejects an empty title"`. Traces: `npx playwright show-trace test-results/.../trace.zip`.
- Done means: the suite passes and the behaviour you changed has an end-to-end test.

## Rules

- Use the `electron-e2e-test` skill for any change that crosses IPC, touches `webPreferences`, the preload or
  window handlers, or adds tests.
- Keep `contextIsolation: true`, `sandbox: true` and `nodeIntegration: false`, and keep the tests that assert
  them. Never weaken a security assertion to make a test pass.
- The renderer reaches main only through named preload functions. Every `ipcMain.handle` checks the sender
  frame and validates its arguments, and has a test for bad input.
- Tests use the shared fixture: a fresh app and `userData` per test. No `waitForTimeout`, no CSS selectors.
- Never add `--no-sandbox`, `--disable-web-security` or `ELECTRON_RUN_AS_NODE` to scripts or CI.

# CLAUDE.md

@AGENTS.md

## Claude Code notes

- Skills from this loadout live in `.claude/skills/`: `electron-e2e-test`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Electron end-to-end tests with Playwright" v1.0.0 — https://loadout.jnw-it.com/loadouts/electron-playwright-e2e/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes

- Skills from this loadout live in `.agents/skills/`: `electron-e2e-test`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "Electron end-to-end tests with Playwright" v1.0.0 — https://loadout.jnw-it.com/loadouts/electron-playwright-e2e/ -->

---
name: electron-e2e-test
description: Write and run Playwright end-to-end tests that drive the real Electron app - main process, preload and renderer together - including security assertions on webPreferences, the preload API, IPC validation and blocked navigation. Use when adding a feature that crosses IPC, changing window or preload settings, or setting up Electron tests in CI.
---

# Electron end-to-end tests with Playwright

Unit tests of the renderer miss the bugs that matter in Electron: a preload that leaks `ipcRenderer`, a
handler that trusts its input, a window that someone set to `sandbox: false`. Playwright's Electron support
launches the real app and lets a test reach both sides: `page` for the renderer, `app.evaluate` for the main
process.

## Setup

- Dev dependencies, pinned: `@playwright/test` and `electron`. No browser download is needed for Electron
  tests (`npx playwright install` is not required).
- `references/playwright.config.js`: one worker, traces kept on failure, one retry on CI only.
- `references/electron-fixture.js`: `test.extend` fixtures. Every test gets a fresh `userData` folder,
  its own app instance (`app.current`), its first window (`page`), and `app.relaunch()` for restart tests.
  The main process must honour `E2E_USER_DATA`:

  ```js
  if (process.env.E2E_USER_DATA) app.setPath("userData", process.env.E2E_USER_DATA);
  ```

- Run: `npx playwright test`. On Linux without a display: `xvfb-run -a npx playwright test`.

## What every app's suite covers

`references/app.spec.js` is a complete example. Adapt these to your app:

1. Secure defaults, read from the main process:
   `webContents.getLastWebPreferences()` has `contextIsolation: true`, `sandbox: true`,
   `nodeIntegration: false`. A change that weakens one fails here, not in a security review.
2. The renderer sees only the preload API: `typeof window.require`, `window.process` and
   `window.ipcRenderer` are `"undefined"`, and the exposed object has exactly the functions you expect.
3. Each IPC feature end to end: act in the UI, assert the UI, then assert the main-process effect (a file
   in `userData`, a value from `app.evaluate`). Restart with `app.relaunch()` when persistence matters.
4. Each handler's validation: send bad input through the UI and assert the error and that nothing was written.
5. `window.open` and navigation away are denied, and there is still one window.

## Rules

- Locate by role and label (`getByRole`, `getByLabel`), never by CSS classes or XPath.
- Wait with web-first assertions (`expect(locator).toHaveText`, `expect.poll`), never `waitForTimeout`.
- One app per test via the fixture. No shared state between tests, no real home-directory data.
- Never trigger `shell.openExternal` from a test (use a URL your handler denies outright); on CI it can hang shutdown.
- Never pass `--no-sandbox`, `--disable-web-security` or similar flags to make a test pass. If the app only
  starts with them, report it as a bug.
- Do not stub `ipcRenderer` or the preload in e2e tests. That is what the test is for.
- A failing test gets fixed or reported, not skipped. `test.fixme` only with a linked issue.

## CI

`references/electron-e2e.yml`: Ubuntu runner, `npm ci`, a step that downloads the Electron binary
(`node -e "require('electron')"`, verified against Electron's checksums), then
`xvfb-run -a npx playwright test`. Traces upload on failure.

## Done means

The suite passes locally or under `xvfb-run`, the new behaviour has a test from the list above, and the
summary names any security assertion you changed and why.

// Electron end-to-end tests. One worker: each test launches its own app instance.
const { defineConfig } = require("@playwright/test");

module.exports = defineConfig({
  testDir: "e2e",
  timeout: 30_000,
  workers: 1,
  retries: process.env.CI ? 1 : 0,
  reporter: [["list"]],
  use: { trace: "retain-on-failure" },
});

// Playwright fixtures for Electron: every test gets its own app instance and an empty userData folder.
// `relaunch()` closes and restarts the app on the same userData, for persistence tests.
const base = require("@playwright/test");
const fs = require("node:fs");
const os = require("node:os");
const path = require("node:path");

const launch = (userData) =>
  base._electron.launch({
    args: ["."],
    env: { ...process.env, E2E_USER_DATA: userData, ELECTRON_ENABLE_LOGGING: "1" },
  });

exports.test = base.test.extend({
  userData: async ({}, use) => {
    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "electron-e2e-"));
    await use(dir);
    fs.rmSync(dir, { recursive: true, force: true });
  },
  app: async ({ userData }, use) => {
    const holder = { current: await launch(userData) };
    holder.relaunch = async () => {
      await holder.current.close();
      holder.current = await launch(userData);
      return holder.current;
    };
    await use(holder);
    // Close normally, but never let a stuck app hang the run: kill it after 10 seconds.
    const proc = holder.current.process();
    const timer = setTimeout(() => proc.kill("SIGKILL"), 10_000);
    await holder.current.close().catch(() => {});
    clearTimeout(timer);
  },
  page: async ({ app }, use) => {
    const page = await app.current.firstWindow();
    await page.waitForLoadState("domcontentloaded");
    await use(page);
  },
});

exports.expect = base.expect;

// Drives the real Electron app: main process, preload and renderer together.
const fs = require("node:fs");
const path = require("node:path");
const { test, expect } = require("./electron-fixture");

test("window opens with the secure web preferences", async ({ app, page }) => {
  await expect(page).toHaveTitle("Notes");
  const prefs = await app.current.evaluate(({ BrowserWindow }) => {
    const p = BrowserWindow.getAllWindows()[0].webContents.getLastWebPreferences();
    return { contextIsolation: p.contextIsolation, sandbox: p.sandbox, nodeIntegration: p.nodeIntegration };
  });
  expect(prefs).toEqual({ contextIsolation: true, sandbox: true, nodeIntegration: false });
});

test("the renderer has the preload API and no Node", async ({ page }) => {
  const globals = await page.evaluate(() => ({
    require: typeof window.require,
    process: typeof window.process,
    ipcRenderer: typeof window.ipcRenderer,
    notes: Object.keys(window.notes).sort(),
  }));
  expect(globals).toEqual({ require: "undefined", process: "undefined", ipcRenderer: "undefined", notes: ["add", "list"] });
});

test("adding a note goes through IPC, is saved by main, and survives a restart", async ({ app, page, userData }) => {
  await page.getByLabel("Title").fill("  Buy milk  ");
  await page.getByRole("button", { name: "Add note" }).click();
  await expect(page.getByRole("list", { name: "Notes" }).getByRole("listitem")).toHaveText(["Buy milk"]);

  const saved = JSON.parse(fs.readFileSync(path.join(userData, "notes.json"), "utf8"));
  expect(saved.map((n) => n.title)).toEqual(["Buy milk"]);

  const again = await (await app.relaunch()).firstWindow();
  await expect(again.getByRole("listitem")).toHaveText(["Buy milk"]);
});

test("the main process rejects an empty title", async ({ page, userData }) => {
  await page.getByLabel("Title").fill("   ");
  await page.getByRole("button", { name: "Add note" }).click();
  await expect(page.getByRole("alert")).toHaveText("Title must be 1-120 characters");
  expect(fs.existsSync(path.join(userData, "notes.json"))).toBe(false);
});

test("window.open and navigation away are denied", async ({ app, page }) => {
  // http:// is denied without being handed to the OS browser; https:// would go to shell.openExternal,
  // which a test must never trigger (on CI it can leave xdg-open hanging and block shutdown).
  expect(await page.evaluate(() => window.open("http://example.com") === null)).toBe(true);
  await page.evaluate(() => {
    window.location.href = "https://example.com";
  });
  await expect.poll(() => page.url()).toMatch(/index\.html$/);
  expect(app.current.windows()).toHaveLength(1);
});

# .github/workflows/e2e.yml
# Electron needs a display on Linux: xvfb-run provides a virtual one. The Electron binary is
# downloaded (and checksum-verified by @electron/get) on first use, then cached.
name: Electron e2e

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

jobs:
  e2e:
    runs-on: ubuntu-24.04
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 22
          cache: npm
      - uses: actions/cache@v6
        with:
          path: ~/.cache/electron
          key: electron-${{ hashFiles('package-lock.json') }}
      - run: npm ci
      - run: node -e "require('electron')"
      - run: xvfb-run -a npx playwright test
      - uses: actions/upload-artifact@v7
        if: failure()
        with:
          name: playwright-traces
          path: test-results/
          retention-days: 7