electron-playwright
Overview
Playwright ships a first-class _electron namespace that launches a
packaged Electron app by executablePath and drives both the main
process (Node.js, IPC, native modules) and renderer windows
(Chromium DOMs) from a single test (pwelectron). Per
Electron's own automated-testing tutorial (electrontest),
Playwright is one of three sanctioned test stacks (alongside WebdriverIO
and Selenium) for modern Electron projects.
Differentiation: unlike playwright-testing (which drives a running
Chromium / Firefox / WebKit browser via the browser / context / page
namespaces), electron-playwright uses the separate _electron namespace to
launch a packaged binary by path and probe the main process via
electronApp.evaluate() (pwelectronapp). Renderer-side page
patterns (Page Object, accessibility-first locators, trace viewer) carry over.
For legacy Spectron suites, see
references/spectron-migration.md; for the
strategic frame, desktop-test-strategy-reference.
When to use
- New Electron desktop app - pick Playwright
_electron as the
modern default per electrontest.
- Existing Electron suite still on Spectron - see the migration shopping
list in references/spectron-migration.md.
- Tests need to assert main-process state (e.g.,
app.isPackaged, BrowserWindow count, IPC channel payloads) in
addition to renderer DOM.
- Tests need to exercise packaged-app behaviour (file
associations, single-instance lock, custom protocol handlers) that
is unreachable from browser-only Playwright.
Step 1 - Install
Per electrontest:
npm install --save-dev @playwright/test
Playwright's _electron module is bundled inside playwright /
@playwright/test - no extra package is needed
(pwelectron). Supported Electron versions per
pwelectron: "Electron v12.2.0+, v13.4.0+, and v14+".
Step 2 - Author the first test
The canonical example from electrontest:
import { test, expect, _electron as electron } from '@playwright/test';
test('app launches and is not packaged in dev', async () => {
const electronApp = await electron.launch({ args: ['.'] });
// Main-process assertion: probe the Electron `app` module
const isPackaged = await electronApp.evaluate(async ({ app }) => {
return app.isPackaged;
});
expect(isPackaged).toBe(false);
// Renderer assertion: take a screenshot of the first window
const window = await electronApp.firstWindow();
await window.screenshot({ path: 'intro.png' });
await electronApp.close();
});
What's going on:
electron.launch({ args: ['.'] }) launches Electron with the
current directory as the main-script argument
(pwelectron). For a packaged app, pass
executablePath to the packaged binary instead - its default per
pwelectron is node_modules/.bin/electron.electronApp.evaluate(pageFunction) runs pageFunction inside
the main process; the first argument is "always the result of
the require('electron') in the main app script"
(pwelectronapp).electronApp.firstWindow() "waits for the first application
window to be opened" (pwelectronapp) and returns
a Playwright Page - every standard
playwright-testing
locator (getByRole, getByLabel) works on it.
Step 3 - Launching a packaged binary
For tests of the packaged app (the artifact users install):
import path from 'node:path';
import { _electron as electron } from '@playwright/test';
const PACKAGED_BIN = process.platform === 'win32'
? path.resolve('dist/win-unpacked/MyApp.exe')
: process.platform === 'darwin'
? path.resolve('dist/mac/MyApp.app/Contents/MacOS/MyApp')
: path.resolve('dist/linux-unpacked/myapp');
const electronApp = await electron.launch({
executablePath: PACKAGED_BIN,
args: [],
env: { ...process.env, NODE_ENV: 'test' },
recordVideo: { dir: 'test-results/videos' },
});
The executablePath, env, cwd, recordVideo, recordHar, and
timeout options are documented on the _electron launch reference
(pwelectron).
Step 4 - Probing main + renderer in one test
Multi-surface assertion - main process owns app lifecycle, renderer
owns DOM:
test('opening a project loads it into the renderer', async () => {
const electronApp = await electron.launch({ args: ['.'] });
const window = await electronApp.firstWindow();
// Renderer-side action via Playwright Page API
await window.getByRole('button', { name: /open project/i }).click();
await window.getByLabel('Project path').fill('/tmp/demo-project');
await window.getByRole('button', { name: /confirm/i }).click();
// Renderer-side assertion
await expect(window.getByRole('heading', { name: /demo-project/i })).toBeVisible();
// Main-process assertion: recent-projects state mutated
const recents: string[] = await electronApp.evaluate(({ app }) => {
return app.getRecentDocuments();
});
expect(recents).toContain('/tmp/demo-project');
await electronApp.close();
});
electronApp.evaluate(pageFunction) returns the function's value and awaits a
returned Promise, so async main-process queries work naturally
(pwelectronapp).
Step 5 - Mapping renderer windows to main-process BrowserWindow
When a test needs the underlying BrowserWindow object for a window
(to assert size, fullscreen state, devtools open, etc.):
const window = await electronApp.firstWindow();
const bwHandle = await electronApp.browserWindow(window);
const isFullScreen = await bwHandle.evaluate((bw) => bw.isFullScreen());
expect(isFullScreen).toBe(false);
electronApp.browserWindow(page) returns the BrowserWindow for a page as a
JSHandle; multi-window apps iterate electronApp.windows()
(pwelectronapp). Full API table:
references/electron-ci-and-api.md.
Step 6 - Waiting for new windows + console output
The 'window', 'console', and 'close' events fire for each new window,
main-process console writes, and process termination respectively
(pwelectronapp); event payloads and the full API table are in
references/electron-ci-and-api.md.
// Wait for a secondary window to open after clicking
const [secondary] = await Promise.all([
electronApp.waitForEvent('window'),
window.getByRole('button', { name: /preferences/i }).click(),
]);
await expect(secondary.getByRole('heading', { name: /preferences/i })).toBeVisible();
Step 7 - Configuration
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
testDir: './tests/electron',
fullyParallel: false, // Electron launches are heavy; serialize
workers: 1,
forbidOnly: !!process.env.CI,
retries: process.env.CI ? 2 : 0,
reporter: [
['html'],
['junit', { outputFile: 'reports/electron-junit.xml' }],
],
use: {
trace: 'on-first-retry',
screenshot: 'only-on-failure',
},
});
Electron-launch tests typically run with workers: 1 because each
launch spawns an Electron process with its own GPU/IPC stack; full
parallel launches collide on the user-data directory and on
GPU-shared-memory regions. (Web-only Playwright defaults to parallel
per
playwright-testing.)
Step 8 - Running
# All Electron tests
npx playwright test --config=playwright.electron.config.ts
# A specific test file
npx playwright test tests/electron/launch.spec.ts
# Headed (the Electron window stays visible)
npx playwright test --headed
# Trace viewer for a failing run
npx playwright show-trace test-results/<…>/trace.zip
The trace viewer shows DOM snapshots of the renderer windows and the
evaluate calls into the main process side-by-side - debug parity
with normal Playwright traces (the trace viewer surface is part of
the shared Playwright toolchain per
playwright-testing).
Step 9 - Parsing results
JUnit XML output (reports/electron-junit.xml from Step 7) feeds
junit-xml-analysis
for aggregation. The HTML reporter is identical to web-Playwright
(pwelectron).
Step 10 - CI integration
Run across a Windows / macOS / Linux matrix; Linux needs an xvfb-run virtual
display because Electron requires a display server, while macOS and Windows
GitHub-hosted runners are display-capable out of the box. Full workflow:
references/electron-ci-and-api.md.
Anti-patterns
| Anti-pattern | Why it fails | Fix |
|---|
Driving Electron via plain chromium.launch() from web-only Playwright | Misses main-process surface entirely; can't query app.* or BrowserWindow.* | Use _electron.launch() (pwelectron) |
Hard-coded executablePath checked into the repo for a single OS | Cross-OS CI matrix breaks | Resolve per process.platform (Step 3) |
Tests that share a single electronApp across many tests without cleanup | One leaked window state contaminates the next test | Per-test electronApp = await electron.launch(...) + await electronApp.close() |
Running Electron tests with default workers > 1 | GPU / user-data directory collisions; flaky launches | workers: 1 (Step 7) |
Forgetting xvfb-run on hosted Linux CI | "Failed to initialize display" launch failure | xvfb-run --auto-servernum wrapper (Step 10) |
Probing main-process modules from window.evaluate() | window.evaluate() runs in the renderer; doesn't see main-process globals | Use electronApp.evaluate() (pwelectronapp) |
| Mixing Spectron and Playwright assertions in the same suite | Two driver lifecycles compete for the same Electron process | Migrate file-by-file per references/spectron-migration.md |
Asserting on Electron internal IDs (__electron_id) for locators | Internal; changes between Electron versions | Use accessibility-first locators (getByRole / getByLabel) per playwright-testing |
Limitations
_electron is documented as experimental historically; per
electrontest it is one of the three recommended
paths but Playwright's own docs do not warrant the same stability
guarantees as the browser API.- Electron version drift. A new Electron major can change main-
process module shapes (
app.getRecentDocuments() deprecations,
etc.); pin Electron in package.json and update intentionally.
- GPU-rendered content (WebGL,
<canvas>, accelerated video) is
opaque to renderer-side accessibility queries - same caveat as in
desktop-test-strategy-reference.
- Multi-instance apps with single-instance-lock need a custom
userData per-test (via app.setPath('userData', …) in test
fixture) - otherwise a second launch races the first.
- Native OS dialogs (Win32 file picker, macOS
NSSavePanel) are
outside the Electron renderer; tests should stub dialog.showOpenDialog
via electronApp.evaluate() rather than try to click through them.
workers: 1 slows the suite. For large suites, shard across
CI jobs (--shard=1/4) rather than raise per-job concurrency.
References
- Playwright
_electron API - pwelectron.
- Playwright
ElectronApplication API - pwelectronapp.
- Electron Automated Testing tutorial - electrontest.
- Legacy migration reference:
references/spectron-migration.md.
- Strategic frame:
desktop-test-strategy-reference.
- Web-side neighbour:
playwright-testing - page-automation patterns that carry over to the renderer surface.