/e2e-testing

title: Electron E2E Testing
icon: desktop

Electron E2E Testing

:::info The Playwright suite launches the real Electron main process and built React UI on Windows and macOS. It exercises the preload bridge, IPC handlers, and file storage. See [Testing Commands](test-commands.md) for the separate Vitest suite. :::

Install and Run

Run these commands from the repository root with Node.js 25, matching the E2E CI workflow:

npm ci --ignore-scripts --force
node node_modules/electron/install.js
npm run typecheck:e2e
npm run test:e2e

The local Windows plugin packages declare OS and CPU restrictions. `--force` allows dependency installation for the macOS test build, while `--ignore-scripts` skips native installation scripts. Install the Electron binary explicitly afterward. The ordinary `e2e` build substitutes the directly imported Windows plugins.

For the full Windows x64 suite, install the .NET 10 SDK and the Visual Studio C++ build tools required by Native AOT, then run:

npm run test:e2e:windows

This command builds the four native helpers, verifies their output paths, builds Electron with `--mode e2e-windows`, and runs all scenarios with real plugins. The ordinary `e2e` build uses plugin substitutes. To require working audio and brightness devices rather than allow device-dependent skips, set `EISLAND_E2E_REQUIRE_DEVICES=1` before running the Windows suite.

:::important Local tests require a logged-in graphical desktop session. Electron opens visible windows and supplies its own Chromium binary; this suite does not require `playwright install`. :::

| Command | Script | Purpose | |---------|--------|---------| | `npm run build:e2e` | `electron-vite build --mode e2e` | Build the main process, preload, and renderer into `e2e/out/` | | `npm run build:e2e:windows:native` | `node e2e/build-windows-native.mjs` | Build real Windows volume, brightness, SMTC, and icon helpers | | `npm run build:e2e:windows` | Native helper build and `electron-vite build --mode e2e-windows` | Build the isolated Windows application with real plugins | | `npm run test:e2e:windows` | Windows build and `test:e2e:run` | Run the complete Windows suite | | `npm run test:e2e` | `npm run build:e2e && npm run test:e2e:run` | Rebuild and run the complete desktop suite | | `npm run test:e2e:run` | `playwright test --config e2e/playwright.config.ts` | Run the existing E2E build | | `npm run typecheck:e2e` | `tsc --noEmit -p e2e/tsconfig.json` | Check E2E TypeScript files and `electron.vite.config.ts` |

To filter or debug an existing build:

npm run build:e2e
npm run test:e2e:run -- --grep "restores"
npm run test:e2e:run -- --debug

Rebuild after changing application code, the E2E entry, or build configuration. `test:e2e:run` does not rebuild automatically.

Current Coverage

`e2e/desktop.spec.ts` contains five scenarios:

| Scenario | Assertions | |----------|------------| | Startup and standalone navigation | Isolated application profile, real preload API, standalone window, and Todo/Countdown tab switching | | Todo lifecycle and restart | Add, edit, complete, restore after restarting Electron, and delete; verify the actual `todos.json` file | | Cross-window synchronization | Write through the main window's preload API and verify the standalone Todo UI and stored file update | | Standalone close and reopen | Close the actual BrowserWindow, reopen it, and verify the saved Todo UI | | Countdown lifecycle and restart | Add, edit, restore after restart, and delete; verify `countdown-dates.json` and the restored standalone tab |

Windows also runs seven dedicated scenarios:

| Source | Assertions | |--------|------------| | `e2e/windows.spec.ts` | Inspect the actual HWND clipping region after expansion/collapse, preserve horizontal center, and verify always-on-top | | `e2e/windows.spec.ts` | Move the real desktop cursor into the island and outside the visible region to verify hover/leave and resize | | `e2e/windows.spec.ts` | Register a dedicated global shortcut through IPC, send actual Windows keyboard input while the standalone window has focus, hide/restore the island, and unregister the shortcut | | `e2e/windows-native.spec.ts` | Extract and validate a PNG from the Electron executable through the actual native icon DLL; verify a missing path returns null | | `e2e/windows-native.spec.ts` | Query actual SMTC session status and validate the available or unavailable response | | `e2e/windows-native.spec.ts` | Query volume/mute and write back the current volume through the real audio helper | | `e2e/windows-native.spec.ts` | Query brightness and write back the current brightness through the real display helper |

Input tests restore the original cursor and unregister their shortcut during cleanup. Hardware tests attach the helper probe results to the report; helper execution errors fail the tests. A missing default playback endpoint or unsupported WMI/DDC-CI display produces an explicit skip unless `EISLAND_E2E_REQUIRE_DEVICES=1`. SMTC queries do not control personal media playback.

Tests use English accessible names from `i18n/en-US.json` and assert that no renderer page errors were recorded. The configuration runs one worker, disables parallel execution, and uses zero retries. Each test has a 60-second timeout; assertions have a 10-second timeout.

:::note The Windows suite covers native window regions, cursor input, global shortcuts, actual DLL loading, and available audio/display controls. Controlled media playback, installers, and updates need additional scenarios. Running the UI suite on macOS does not establish macOS support for the released application. :::

Source Files

All E2E source files, configuration, build output, and diagnostics are located in the repository-root `e2e/` directory.

| File | Responsibility | |------|----------------| | `e2e/desktop.spec.ts` | Desktop interaction, persistence, and cross-window scenarios | | `e2e/windows.spec.ts` | Windows reg