SurfSense/.cursor/skills/playwright-testing/electron-testing.md

# Electron Testing

> **When to use**: When your application is an Electron desktop app and you need end-to-end tests covering the renderer process, main process, IPC communication, native dialogs, system tray, and multi-window workflows.
> **Prerequisites**: [core/configuration.md](configuration.md), [core/fixtures-and-hooks.md](fixtures-and-hooks.md)

## Quick Reference

```typescript
import { _electron as electron } from 'playwright';

// Launch the Electron app
const app = await electron.launch({ args: ['./main.js'] });

// Get the first window (renderer process)
const window = await app.firstWindow();

// Access the main process for evaluation
const appPath = await app.evaluate(async ({ app }) => {
  return app.getPath('userData');
});

// Close the app
await app.close();
```

## Patterns

### Basic Electron App Setup

**Use when**: Starting to test an Electron app with Playwright for the first time.
**Avoid when**: Your app is a web app, not an Electron app.

**TypeScript**
```typescript
import { test, expect, _electron as electron, ElectronApplication, Page } from '@playwright/test';

let app: ElectronApplication;
let window: Page;

test.beforeAll(async () => {
  // Launch the Electron app from your project directory
  app = await electron.launch({
    args: ['./dist/main.js'],
    env: {
      ...process.env,
      NODE_ENV: 'test',
    },
  });

  // Wait for the first BrowserWindow to open
  window = await app.firstWindow();

  // Optional: wait for the app to be fully loaded
  await window.waitForLoadState('domcontentloaded');
});

test.afterAll(async () => {
  await app.close();
});

test('app window has correct title', async () => {
  const title = await window.title();
  expect(title).toBe('My Electron App');
});

test('main page renders', async () => {
  await expect(window.getByRole('heading', { name: 'Welcome' })).toBeVisible();
});
```

**JavaScript**
```javascript
const { test, expect, _electron: electron } = require('@playwright/test');

let app;
let window;

test.beforeAll(async () => {
  app = await electron.launch({
    args: ['./dist/main.js'],
    env: {
      ...process.env,
      NODE_ENV: 'test',
    },
  });
  window = await app.firstWindow();
  await window.waitForLoadState('domcontentloaded');
});

test.afterAll(async () => {
  await app.close();
});

test('app window has correct title', async () => {
  const title = await window.title();
  expect(title).toBe('My Electron App');
});

test('main page renders', async () => {
  await expect(window.getByRole('heading', { name: 'Welcome' })).toBeVisible();
});
```

### Electron App Fixture (Recommended)

**Use when**: You want isolated, reusable Electron app instances across test files.
**Avoid when**: All tests can share a single app instance (rare in practice).

**TypeScript**
```typescript
// fixtures.ts
import { test as base, expect, _electron as electron, ElectronApplication, Page } from '@playwright/test';

type ElectronFixtures = {
  electronApp: ElectronApplication;
  window: Page;
};

export const test = base.extend<ElectronFixtures>({
  electronApp: async ({}, use) => {
    const app = await electron.launch({
      args: ['./dist/main.js'],
      env: { ...process.env, NODE_ENV: 'test' },
    });
    await use(app);
    await app.close();
  },

  window: async ({ electronApp }, use) => {
    const window = await electronApp.firstWindow();
    await window.waitForLoadState('domcontentloaded');
    await use(window);
  },
});

export { expect };
```

```typescript
// app.spec.ts
import { test, expect } from './fixtures';

test('navigate to settings', async ({ window }) => {
  await window.getByRole('link', { name: 'Settings' }).click();
  await expect(window.getByRole('heading', { name: 'Settings' })).toBeVisible();
});
```

**JavaScript**
```javascript
// fixtures.js
const { test: base, expect, _electron: electron } = require('@playwright/test');

const test = base.extend({
  electronApp: async ({}, use) => {
    const app = await electron.launch({
      args: ['./dist/main.js'],
      env: { ...process.env, NODE_ENV: 'test' },
    });
    await use(app);
    await app.close();
  },

  window: async ({ electronApp }, use) => {
    const window = await electronApp.firstWindow();
    await window.waitForLoadState('domcontentloaded');
    await use(window);
  },
});

module.exports = { test, expect };
```

### Accessing the Main Process

**Use when**: You need to read Electron app state, check paths, get app version, or verify main process behavior.
**Avoid when**: Everything you need is in the renderer (UI). Prefer testing through the UI.

`app.evaluate()` runs code in the main process with access to all Electron APIs.

**TypeScript**
```typescript
import { test, expect } from './fixtures';

test('verify app version and paths', async ({ electronApp }) => {
  // Evaluate in the main process — receives the Electron module
  const appInfo = await electronApp.evaluate(async ({ app }) => {
    return {
      version: app.getVersion(),
      name: app.getName(),
      userData: app.getPath('userData'),
      locale: app.getLocale(),
      isPackaged: app.isPackaged,
    };
  });

  expect(appInfo.version).toMatch(/^\d+\.\d+\.\d+$/);
  expect(appInfo.name).toBe('my-electron-app');
  expect(appInfo.userData).toBeTruthy();
  expect(appInfo.isPackaged).toBe(false); // false during development
});

test('main process environment variables are set', async ({ electronApp }) => {
  const nodeEnv = await electronApp.evaluate(async () => {
    return process.env.NODE_ENV;
  });

  expect(nodeEnv).toBe('test');
});
```

**JavaScript**
```javascript
const { test, expect } = require('./fixtures');

test('verify app version and paths', async ({ electronApp }) => {
  const appInfo = await electronApp.evaluate(async ({ app }) => {
    return {
      version: app.getVersion(),
      name: app.getName(),
      userData: app.getPath('userData'),
      isPackaged: app.isPackaged,
    };
  });

  expect(appInfo.version).toMatch(/^\d+\.\d+\.\d+$/);
  expect(appInfo.name).toBe('my-electron-app');
});
```

### Testing IPC Communication

**Use when**: Your app uses `ipcMain` / `ipcRenderer` for communication between the main and renderer processes.
**Avoid when**: IPC is an implementation detail and the behavior is fully testable through the UI.

**TypeScript**
```typescript
import { test, expect } from './fixtures';

test('renderer sends IPC message and gets response', async ({ electronApp, window }) => {
  // Trigger an IPC call from the renderer
  const result = await window.evaluate(async () => {
    // Assumes your preload script exposes ipcRenderer via contextBridge
    return await (window as any).electronAPI.getSystemInfo();
  });

  expect(result).toHaveProperty('platform');
  expect(result).toHaveProperty('arch');
  expect(result.platform).toBeTruthy();
});

test('main process handles IPC file-read request', async ({ electronApp, window }) => {
  // Set up a listener in the main process first
  await electronApp.evaluate(async ({ ipcMain }) => {
    ipcMain.handle('test-ping', async () => {
      return { pong: true, timestamp: Date.now() };
    });
  });

  // Send from renderer
  const response = await window.evaluate(async () => {
    return await (window as any).electronAPI.invoke('test-ping');
  });

  expect(response.pong).toBe(true);
  expect(response.timestamp).toBeGreaterThan(0);
});

test('IPC event triggers UI update', async ({ window }) => {
  // Simulate the main process sending an event to the renderer
  await window.evaluate(() => {
    // Trigger a custom event that the app listens for
    window.dispatchEvent(new CustomEvent('app:notification', {
      detail: { message: 'Update available', version: '2.0.0' },
    }));
  });

  await expect(window.getByText('Update available')).toBeVisible();
  await expect(window.getByText('Version 2.0.0')).toBeVisible();
});
```

**JavaScript**
```javascript
const { test, expect } = require('./fixtures');

test('renderer sends IPC message and gets response', async ({ electronApp, window }) => {
  const result = await window.evaluate(async () => {
    return await window.electronAPI.getSystemInfo();
  });

  expect(result).toHaveProperty('platform');
  expect(result).toHaveProperty('arch');
});

test('IPC event triggers UI update', async ({ window }) => {
  await window.evaluate(() => {
    window.dispatchEvent(new CustomEvent('app:notification', {
      detail: { message: 'Update available', version: '2.0.0' },
    }));
  });

  await expect(window.getByText('Update available')).toBeVisible();
});
```

### File System Dialogs

**Use when**: Your app uses Electron's `dialog.showOpenDialog`, `dialog.showSaveDialog`, or similar native file dialogs.
**Avoid when**: File selection is handled by a web input (`<input type="file">`). Use standard Playwright file chooser for that.

Native dialogs cannot be interacted with directly. Mock them in the main process.

**TypeScript**
```typescript
import { test, expect } from './fixtures';

test('open file dialog and load a document', async ({ electronApp, window }) => {
  // Mock the dialog to return a specific file path
  await electronApp.evaluate(async ({ dialog }) => {
    dialog.showOpenDialog = async () => ({
      canceled: false,
      filePaths: ['/tmp/test-document.txt'],
    });
  });

  // Click the "Open File" button in the renderer
  await window.getByRole('button', { name: 'Open File' }).click();

  // Verify the app loaded the file
  await expect(window.getByTestId('file-name')).toHaveText('test-document.txt');
});

test('save file dialog returns selected path', async ({ electronApp, window }) => {
  await electronApp.evaluate(async ({ dialog }) => {
    dialog.showSaveDialog = async () => ({
      canceled: false,
      filePath: '/tmp/exported-report.pdf',
    });
  });

  await window.getByRole('button', { name: 'Export PDF' }).click();
  await expect(window.getByText('Saved to /tmp/exported-report.pdf')).toBeVisible();
});

test('handle canceled file dialog', async ({ electronApp, window }) => {
  await electronApp.evaluate(async ({ dialog }) => {
    dialog.showOpenDialog = async () => ({
      canceled: true,
      filePaths: [],
    });
  });

  await window.getByRole('button', { name: 'Open File' }).click();

  // App should not crash or change state
  await expect(window.getByTestId('file-name')).toHaveText('No file selected');
});
```

**JavaScript**
```javascript
const { test, expect } = require('./fixtures');

test('open file dialog and load a document', async ({ electronApp, window }) => {
  await electronApp.evaluate(async ({ dialog }) => {
    dialog.showOpenDialog = async () => ({
      canceled: false,
      filePaths: ['/tmp/test-document.txt'],
    });
  });

  await window.getByRole('button', { name: 'Open File' }).click();
  await expect(window.getByTestId('file-name')).toHaveText('test-document.txt');
});

test('handle canceled file dialog', async ({ electronApp, window }) => {
  await electronApp.evaluate(async ({ dialog }) => {
    dialog.showOpenDialog = async () => ({
      canceled: true,
      filePaths: [],
    });
  });

  await window.getByRole('button', { name: 'Open File' }).click();
  await expect(window.getByTestId('file-name')).toHaveText('No file selected');
});
```

### System Tray Testing

**Use when**: Your app has a system tray icon with context menus or status indicators.
**Avoid when**: Your app has no tray functionality.

Playwright cannot directly click system tray icons. Test the tray logic by evaluating in the main process.

**TypeScript**
```typescript
import { test, expect } from './fixtures';

test('tray icon is created on app launch', async ({ electronApp }) => {
  const hasTray = await electronApp.evaluate(async ({ BrowserWindow }) => {
    // Access the tray via a reference your app stores
    const { tray } = require('./tray-manager');
    return tray !== null && !tray.isDestroyed();
  });

  expect(hasTray).toBe(true);
});

test('tray tooltip shows unread count', async ({ electronApp }) => {
  const tooltip = await electronApp.evaluate(async () => {
    const { tray } = require('./tray-manager');
    return tray.getToolTip();
  });

  expect(tooltip).toMatch(/\d+ unread messages?/);
});

test('clicking tray "Show" menu item opens the window', async ({ electronApp }) => {
  // Simulate clicking a tray menu item by invoking its callback
  await electronApp.evaluate(async ({ BrowserWindow }) => {
    const { trayMenu } = require('./tray-manager');
    // Find the "Show" menu item and invoke its click handler
    const showItem = trayMenu.items.find((item: any) => item.label === 'Show');
    if (showItem && showItem.click) {
      showItem.click();
    }
  });

  // The main window should now be visible
  const window = await electronApp.firstWindow();
  const isVisible = await window.evaluate(() => {
    return document.visibilityState === 'visible';
  });
  expect(isVisible).toBe(true);
});
```

**JavaScript**
```javascript
const { test, expect } = require('./fixtures');

test('tray icon is created on app launch', async ({ electronApp }) => {
  const hasTray = await electronApp.evaluate(async () => {
    const { tray } = require('./tray-manager');
    return tray !== null && !tray.isDestroyed();
  });

  expect(hasTray).toBe(true);
});
```

### Multiple Windows

**Use when**: Your Electron app opens multiple windows (preferences, about, detached panels).
**Avoid when**: Your app uses a single window.

**TypeScript**
```typescript
import { test, expect } from './fixtures';

test('open and interact with preferences window', async ({ electronApp, window }) => {
  // Click the menu item or button that opens the preferences window
  await window.getByRole('menuitem', { name: 'Preferences' }).click();

  // Wait for the new window to appear
  const prefsWindow = await electronApp.waitForEvent('window');
  await prefsWindow.waitForLoadState('domcontentloaded');

  // Interact with the preferences window
  await prefsWindow.getByLabel('Theme').selectOption('dark');
  await prefsWindow.getByRole('button', { name: 'Save' }).click();

  // Verify the main window reflects the change
  await expect(window.locator('html')).toHaveAttribute('data-theme', 'dark');

  // Close the preferences window
  await prefsWindow.close();
});

test('get all open windows', async ({ electronApp, window }) => {
  // Open a second window
  await window.getByRole('button', { name: 'New Window' }).click();

  // Get all windows
  const allWindows = electronApp.windows();
  expect(allWindows.length).toBe(2);

  // Find the new window (not the main one)
  const newWindow = allWindows.find((w) => w !== window)!;
  await expect(newWindow.getByRole('heading')).toBeVisible();
});
```

**JavaScript**
```javascript
const { test, expect } = require('./fixtures');

test('open and interact with preferences window', async ({ electronApp, window }) => {
  await window.getByRole('menuitem', { name: 'Preferences' }).click();

  const prefsWindow = await electronApp.waitForEvent('window');
  await prefsWindow.waitForLoadState('domcontentloaded');

  await prefsWindow.getByLabel('Theme').selectOption('dark');
  await prefsWindow.getByRole('button', { name: 'Save' }).click();

  await expect(window.locator('html')).toHaveAttribute('data-theme', 'dark');
  await prefsWindow.close();
});
```

### Testing Packaged/Built Apps

**Use when**: You want to test the production build of your Electron app (after `electron-builder`, `electron-forge`, etc.).
**Avoid when**: Development mode testing is sufficient for your CI pipeline.

**TypeScript**
```typescript
import { test, expect, _electron as electron } from '@playwright/test';
import path from 'path';

test('packaged app launches and works', async () => {
  // Path to the packaged app executable
  const appPath = process.platform === 'darwin'
    ? path.join(__dirname, '../dist/mac/MyApp.app/Contents/MacOS/MyApp')
    : process.platform === 'win32'
      ? path.join(__dirname, '../dist/win-unpacked/MyApp.exe')
      : path.join(__dirname, '../dist/linux-unpacked/my-app');

  const app = await electron.launch({
    executablePath: appPath,
  });

  const window = await app.firstWindow();
  await window.waitForLoadState('domcontentloaded');

  // Verify the packaged app works correctly
  const title = await window.title();
  expect(title).toBe('My Electron App');

  await expect(window.getByRole('heading', { name: 'Welcome' })).toBeVisible();

  // Verify it reports as packaged
  const isPackaged = await app.evaluate(async ({ app }) => app.isPackaged);
  expect(isPackaged).toBe(true);

  await app.close();
});
```

**JavaScript**
```javascript
const { test, expect, _electron: electron } = require('@playwright/test');
const path = require('path');

test('packaged app launches and works', async () => {
  const appPath = process.platform === 'darwin'
    ? path.join(__dirname, '../dist/mac/MyApp.app/Contents/MacOS/MyApp')
    : process.platform === 'win32'
      ? path.join(__dirname, '../dist/win-unpacked/MyApp.exe')
      : path.join(__dirname, '../dist/linux-unpacked/my-app');

  const app = await electron.launch({
    executablePath: appPath,
  });

  const window = await app.firstWindow();
  await window.waitForLoadState('domcontentloaded');

  const title = await window.title();
  expect(title).toBe('My Electron App');

  await expect(window.getByRole('heading', { name: 'Welcome' })).toBeVisible();
  await app.close();
});
```

## Decision Guide

| Scenario | Approach | Why |
|---|---|---|
| Launch Electron app for testing | `_electron.launch({ args: ['./main.js'] })` | Playwright's built-in Electron support |
| Get the main window | `app.firstWindow()` | Returns the first `BrowserWindow` as a Playwright `Page` |
| Read main process state | `app.evaluate(({ app }) => ...)` | Runs code in the main process with Electron APIs |
| Test IPC round-trips | `window.evaluate` (renderer) + `app.evaluate` (main) | Cover both sides of the IPC bridge |
| Mock native file dialogs | Override `dialog.showOpenDialog` via `app.evaluate` | Native dialogs cannot be automated directly |
| Test system tray | `app.evaluate` to invoke tray callbacks | Tray icons are OS-native; not clickable via Playwright |
| Multiple windows | `app.waitForEvent('window')` | Captures new `BrowserWindow` instances as they open |
| Test packaged builds | `electron.launch({ executablePath })` | Points to the built binary instead of source |

## Anti-Patterns

| Don't Do This | Problem | Do This Instead |
|---|---|---|
| `const { app } = require('electron')` in test files | Electron APIs are not available in Playwright's Node process | Use `electronApp.evaluate(({ app }) => ...)` |
| Directly import renderer code into tests | Bypasses the actual app lifecycle and IPC | Test through the UI via the `window` (Page) object |
| Skip `waitForLoadState` after `firstWindow()` | Window may not be fully rendered | Always `await window.waitForLoadState('domcontentloaded')` |
| Test tray by clicking system-level UI | Playwright cannot interact with native OS chrome | Mock tray menu callbacks via `app.evaluate` |
| Share a single `ElectronApplication` across all tests without cleanup | State leaks between tests | Use fixtures with `app.close()` in teardown |
| Forget to close the app in `afterAll` | Leaves Electron processes running, eating CI resources | Always `await app.close()` in teardown |

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| `electron.launch()` throws "cannot find module" | `args` path does not point to your main entry file | Verify the path: `args: ['./dist/main.js']` relative to the working directory |
| `firstWindow()` times out | App does not open a `BrowserWindow` in time | Check that the app creates a window on startup; increase timeout |
| `app.evaluate` cannot access Electron modules | Destructuring the wrong parameter | Destructure correctly: `evaluate(async ({ app, dialog, BrowserWindow }) => ...)` |
| Dialog mock does not take effect | Mock applied after the dialog was already called | Set up mocks before triggering the UI action that opens the dialog |
| Second window not captured | `waitForEvent('window')` registered after the window opened | Register the event listener before triggering the action that opens the window |
| Tests hang after `app.close()` | Child processes spawned by the app are still running | Ensure your Electron app cleans up child processes on quit |
| Packaged app test fails with path error | Executable path varies by OS and build tool | Use `process.platform` to compute the correct path |
| `window.evaluate` throws context destroyed | Window was closed or navigated during evaluation | Ensure the window is stable before evaluating |

## Related

- [core/fixtures-and-hooks.md](fixtures-and-hooks.md) -- wrapping Electron app launch in fixtures
- [core/assertions-and-waiting.md](assertions-and-waiting.md) -- all standard assertions work on Electron windows
- [core/iframes-and-shadow-dom.md](iframes-and-shadow-dom.md) -- Electron apps often embed web components or iframes
- [core/browser-apis.md](browser-apis.md) -- localStorage, IndexedDB, and other APIs work the same in Electron