craftdriver 1.2.0 → 1.4.0

package/docs/recipes/electron-app-from-another-repo.md

@@ -0,0 +1,136 @@
+# Test An Electron App From Another Repo
+
+Use this when your Electron application is built in one repository, but your
+CraftDriver tests live in another repository or package. The important part is
+that the test launches the **packaged executable** produced by the app repo.
+
+This recipe assumes a sibling checkout:
+
+```text
+~/git/
+  my-electron-app/
+  my-electron-tests/
+```
+
+## Build the app first
+
+From the app repo, produce the packaged app the same way CI or release builds do:
+
+```bash
+cd ~/git/my-electron-app
+npm ci
+npm run build
+npm run package
+```
+
+The exact command depends on your app. The output is usually under `dist/`,
+`out/`, or `release/`. Point CraftDriver at the executable inside that output,
+not at the source directory.
+
+## Keep the app path in one helper
+
+In the test repo, create a small fixture helper so every test uses the same
+path and Electron version:
+
+```ts
+// tests/fixtures/electron-app.ts
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Browser } from 'craftdriver';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const workspace = path.resolve(here, '..', '..', '..');
+const appRepo = path.join(workspace, 'my-electron-app');
+
+export function appBinaryPath(): string {
+  const override = process.env.MY_APP_BINARY;
+  if (override) return override;
+
+  switch (`${process.platform}-${process.arch}`) {
+    case 'darwin-arm64':
+    case 'darwin-x64':
+      return path.join(appRepo, 'dist/mac/MyApp.app/Contents/MacOS/MyApp');
+    case 'win32-x64':
+      return path.join(appRepo, 'dist/win-unpacked/MyApp.exe');
+    case 'linux-x64':
+      return path.join(appRepo, 'dist/linux-unpacked/my-app');
+    default:
+      throw new Error(`Unsupported Electron test platform: ${os.platform()}-${os.arch()}`);
+  }
+}
+
+export function launchApp(): Promise<Browser> {
+  return Browser.launch({
+    electron: {
+      appBinaryPath: appBinaryPath(),
+      version: process.env.MY_APP_ELECTRON_VERSION ?? '43.1.0',
+      args: process.platform === 'linux' ? ['--no-sandbox'] : [],
+    },
+  });
+}
+```
+
+Use `MY_APP_BINARY` when CI downloads a prebuilt app artifact instead of building
+from a sibling checkout.
+
+## Write the test like a normal renderer test
+
+Electron defaults to Classic WebDriver, so the app loads itself. Do not call
+`navigateTo()` unless you explicitly opted into BiDi and know the renderer URL.
+
+```ts
+// tests/settings.test.ts
+import { afterEach, describe, it } from 'vitest';
+import { Browser, By } from 'craftdriver';
+import { launchApp } from './fixtures/electron-app';
+
+describe('settings window', () => {
+  let browser: Browser | undefined;
+
+  afterEach(async () => {
+    await browser?.quit();
+  });
+
+  it('saves the profile name', async () => {
+    browser = await launchApp();
+
+    const main = await browser.waitForPage({ title: /My App/ });
+    await main.find(By.testId('app-title')).expect().toHaveText('My App');
+
+    await main.click(By.testId('nav-settings'));
+    await main.fill(By.testId('profile-name'), 'Ada Lovelace');
+    await main.click(By.testId('save-settings'));
+
+    await main.find(By.testId('settings-status')).expect().toHaveText('Saved');
+  });
+});
+```
+
+Prefer stable `data-testid` attributes in the Electron renderer. You can inspect
+or debug the app with DevTools while designing selectors, but the test should
+interact with the packaged UI the way a user would.
+
+## CI shape
+
+A common CI flow is:
+
+1. Check out or download the Electron app.
+2. Build/package the app, or download a packaged artifact.
+3. Set `MY_APP_BINARY` and `MY_APP_ELECTRON_VERSION`.
+4. Run the CraftDriver tests.
+
+On Linux, run the tests under Xvfb:
+
+```bash
+xvfb-run -a npm test
+```
+
+On macOS and Windows hosted runners, a display is already available. Do not pass
+headless flags to Electron; it is a desktop GUI app.
+
+## Learn More
+
+- [Testing Electron Apps](../electron.md)
+- [Browser API](../browser-api.md)
+- [Vitest Hooks](./vitest-browser-lifecycle.md)

package/docs/recipes/electron-deep-link.md

@@ -0,0 +1,117 @@
+# Test An Electron Deep Link
+
+Use this pattern when your app registers a custom URL scheme (`myapp://…`) and you
+want to verify it handles a link the OS delivers from outside the app. CraftDriver
+opens the link through the real OS launcher, so your production `open-url` /
+`second-instance` handler runs unchanged.
+
+## Application code
+
+Register the protocol and route incoming links to the window. This is normal
+production code, not test instrumentation:
+
+```js
+const { app, BrowserWindow } = require('electron');
+
+const SCHEME = 'myapp';
+let mainWindow = null;
+let lastDeeplink = null;
+
+app.setAsDefaultProtocolClient(SCHEME);
+
+function handleDeeplink(url) {
+  if (!url) return;
+  lastDeeplink = url;
+  if (mainWindow && !mainWindow.isDestroyed()) mainWindow.webContents.send('deeplink', url);
+}
+
+// macOS: the running instance receives the URL here.
+app.on('open-url', (event, url) => {
+  event.preventDefault();
+  handleDeeplink(url);
+});
+
+// Windows/Linux: a deep link launches a second process. Hold the single-instance
+// lock so its argv is routed back into the running instance instead of opening a
+// duplicate window.
+if (!app.requestSingleInstanceLock()) {
+  app.quit();
+} else {
+  app.on('second-instance', (_event, argv) => {
+    handleDeeplink(argv.find((a) => a.startsWith(`${SCHEME}://`)));
+  });
+}
+```
+
+Declare the scheme so the packaged app is registered with the OS. With
+electron-builder:
+
+```yaml
+# electron-builder.yml
+protocols:
+  - name: My App Protocol
+    schemes:
+      - myapp
+```
+
+Forward the link to the renderer through a narrow preload API:
+
+```js
+const { contextBridge, ipcRenderer } = require('electron');
+
+contextBridge.exposeInMainWorld('myapp', {
+  onDeeplink: (cb) => ipcRenderer.on('deeplink', (_event, url) => cb(url)),
+});
+```
+
+```js
+// renderer
+window.myapp?.onDeeplink((url) => {
+  document.querySelector('[data-testid="deeplink-result"]').textContent = url;
+});
+```
+
+## Test code
+
+```ts
+import { Browser, By } from 'craftdriver';
+import { expect, test } from 'vitest';
+
+test('handles an incoming deep link', async () => {
+  const browser = await Browser.launch({
+    electron: {
+      appBinaryPath: process.env.APP_PATH!, // required on Windows to route the link
+      version: process.env.ELECTRON_VERSION!,
+      mainProcess: true, // lets craftdriver auto-detect the user-data dir (Windows/Linux)
+    },
+  });
+
+  try {
+    const url = 'myapp://open?file=test.txt';
+    await browser.electron.triggerDeeplink(url);
+
+    // triggerDeeplink is fire-and-forget: assert the effect through the app.
+    await browser.find(By.testId('deeplink-result')).expect().toHaveText(url);
+
+    // Only custom protocols are valid targets.
+    await expect(browser.electron.triggerDeeplink('https://example.com')).rejects.toThrow();
+  } finally {
+    await browser.quit();
+  }
+});
+```
+
+The reference example implements this exact flow (scheme `craftdriver-example://`)
+in [`craftdriver-examples`](https://github.com/dtopuzov/craftdriver-examples/tree/main/electron).
+
+## Notes
+
+- **macOS** needs the app bundle known to LaunchServices — installed in
+  `/Applications`, or registered once with `lsregister -f MyApp.app`.
+- **Windows / Linux** launch a second process for the link; craftdriver appends the
+  running app's user-data dir as a `userData` query parameter so the single-instance
+  lock hands the link to the test instance. Your app should honor that parameter
+  when it sets its user-data path if you run isolated instances.
+- Like `mockDialog()` and `executeMain()`, deep-link routing that inspects the app
+  via the main process needs the `EnableNodeCliInspectArguments` fuse enabled; the
+  OS launch itself does not.

package/docs/recipes/electron-mock-apis.md

@@ -0,0 +1,88 @@
+# Mock Electron APIs (shell, clipboard, app…)
+
+Native dialogs have a typed helper (`mockDialog()`), but plenty of Electron
+behavior you want to keep out of a test run doesn't: opening the user's browser
+(`shell.openExternal`), writing the system clipboard (`clipboard.writeText`),
+resolving OS paths (`app.getPath`), and so on. `browser.electron.mock()` replaces
+any `electron.<api>.<fn>` main-process method with a scripted return and a call
+recorder, so you can drive the real UI and assert what it asked the OS to do —
+without the OS actually doing it.
+
+Needs main-process access (`electron: { mainProcess: true }`), like `executeMain`
+and `mockDialog`.
+
+## Stop a "share" button from launching a browser
+
+Application code — a normal renderer → preload → IPC → `shell.openExternal` flow:
+
+```js
+// main.js
+const { ipcMain, shell } = require('electron');
+ipcMain.handle('share:open', (_event, url) => shell.openExternal(url));
+```
+
+```js
+// preload.js
+const { contextBridge, ipcRenderer } = require('electron');
+contextBridge.exposeInMainWorld('share', { open: (url) => ipcRenderer.invoke('share:open', url) });
+```
+
+Test — mock the final `shell.openExternal`, click, and assert the URL it received:
+
+```ts
+import { Browser, By } from 'craftdriver';
+import { expect, test } from 'vitest';
+
+test('share button opens the right URL without launching a browser', async () => {
+  const browser = await Browser.launch({
+    electron: { appBinaryPath: process.env.APP_PATH!, mainProcess: true },
+  });
+
+  try {
+    // shell.openExternal resolves to true on success — script that.
+    const openExternal = await browser.electron.mock('shell', 'openExternal', true);
+
+    await browser.click(By.testId('share-btn'));
+
+    expect(await openExternal.getCalls()).toEqual([{ args: ['https://example.com/report/42'] }]);
+    await openExternal.restore();
+  } finally {
+    await browser.quit();
+  }
+});
+```
+
+Each recorded call is `{ args: [...] }` with the (JSON-safe) arguments the app
+passed. The rest of the handle mirrors `mockDialog`: `getCallCount()`,
+`clearCalls()`, `mockReturnValue(value)` to re-script mid-test, and `restore()`
+(also restored on `browser.quit()`).
+
+## Assert what the app copied to the clipboard
+
+```ts
+const writeText = await browser.electron.mock('clipboard', 'writeText');
+
+await browser.click(By.testId('copy-link-btn'));
+
+expect(await writeText.getCalls()).toEqual([{ args: ['https://example.com/report/42'] }]);
+await writeText.restore();
+```
+
+Here no return value is scripted — `clipboard.writeText` returns nothing, so the
+mock returns `undefined` and you assert purely on the recorded arguments.
+
+## Notes
+
+- The scripted value is returned **as-is** (not wrapped in a Promise), so it works
+  for synchronous methods (`app.getName()`, `app.getPath()`) and `await`ed
+  asynchronous ones (`shell.openExternal`). Pass the already-resolved value for an
+  async method.
+- Arguments and the return value must be JSON-serializable; a non-serializable
+  argument (a `BrowserWindow`, a `Buffer`) is recorded as a descriptive placeholder
+  rather than crossing the process boundary.
+- `mock()` targets **object-namespace** methods (`shell`, `clipboard`, `app`,
+  `dialog`, …). Class-based APIs such as `Notification` or `Menu` are not covered by
+  it today — mock the app code that *constructs* them instead, or drive them through
+  your own IPC surface.
+- Reach for the typed [`mockDialog()`](../electron.md#mock-native-dialogs) for file,
+  save, and message dialogs; it validates the result shape for you.

package/docs/recipes/electron-native-dialog.md

@@ -0,0 +1,105 @@
+# Mock A Native Electron File Dialog
+
+Use this pattern when a renderer action opens Electron's operating-system file
+picker. The real app remains structured normally: a sandboxed renderer calls a
+narrow preload API, the preload sends IPC, and the main process opens the native
+dialog. The test replaces only the final `dialog.showOpenDialog()` call.
+
+## Application code
+
+Register the dialog in the main process:
+
+```js
+const { BrowserWindow, dialog, ipcMain } = require('electron');
+
+ipcMain.handle('native-dialog:open-file', (event) => {
+  const parent = BrowserWindow.fromWebContents(event.sender);
+  const options = {
+    title: 'Choose a text file',
+    properties: ['openFile'],
+    filters: [{ name: 'Text files', extensions: ['txt', 'md'] }],
+  };
+
+  return parent ? dialog.showOpenDialog(parent, options) : dialog.showOpenDialog(options);
+});
+```
+
+Expose only the operation the renderer needs:
+
+```js
+const { contextBridge, ipcRenderer } = require('electron');
+
+contextBridge.exposeInMainWorld('craftdriverExample', {
+  openFile: () => ipcRenderer.invoke('native-dialog:open-file'),
+});
+```
+
+The renderer can use the returned value like the real Electron result:
+
+```js
+document.querySelector('[data-testid="open-native-file-btn"]').addEventListener('click', async () => {
+  const result = await window.craftdriverExample.openFile();
+  document.querySelector('[data-testid="native-dialog-result"]').textContent = result.canceled
+    ? 'cancelled'
+    : result.filePaths.join(', ');
+});
+```
+
+## Test code
+
+Opt in to main-process access and install the mock before clicking:
+
+```ts
+import { Browser, By } from 'craftdriver';
+import { expect, test } from 'vitest';
+
+test('selects an invoice without opening an OS dialog', async () => {
+  const browser = await Browser.launch({
+    electron: {
+      appBinaryPath: process.env.APP_PATH!,
+      version: process.env.ELECTRON_VERSION!,
+      mainProcess: true,
+    },
+  });
+
+  try {
+    const dialog = await browser.electron.mockDialog('showOpenDialog', {
+      canceled: false,
+      filePaths: ['/fixtures/invoice.txt'],
+    });
+
+    await browser.click(By.testId('open-native-file-btn'));
+    await browser
+      .find(By.testId('native-dialog-result'))
+      .expect()
+      .toHaveText('/fixtures/invoice.txt');
+
+    // The click reached the main process: the mock recorded the exact options the
+    // ipcMain handler passed to dialog.showOpenDialog — no OS dialog ever opened.
+    expect(await dialog.getCalls()).toEqual([
+      {
+        options: {
+          title: 'Choose a text file',
+          properties: ['openFile'],
+          filters: [{ name: 'Text files', extensions: ['txt', 'md'] }],
+        },
+      },
+    ]);
+  } finally {
+    await browser.quit();
+  }
+});
+```
+
+The reference example implements this exact flow in
+[`craftdriver-examples`](https://github.com/dtopuzov/craftdriver-examples/tree/main/electron).
+
+## Production and hardened builds
+
+No application test hook is required. This works against an unchanged packaged
+production artifact when its `EnableNodeCliInspectArguments` Electron fuse is
+enabled. The fuse is enabled by default, but security-hardened builds may disable
+it. A disabled fuse cannot be changed after the app is signed; package a separate
+test artifact with that fuse enabled. See
+[Testing Electron Apps](../electron.md#can-this-test-a-production-build) for the
+Forge configuration and security boundary.

package/docs/recipes.md

@@ -16,23 +16,27 @@ launched `browser` — unless it shows a `Browser.launch(...)` call itself. See
 [Vitest Hooks recipe](./recipes/vitest-browser-lifecycle.md) for the surrounding
 setup.
 
+The [Electron recipes](#electron) are different: they show the project shape for
+driving a packaged desktop app, so they use paths you adapt to your app repo
+rather than the hosted browser examples.
+
 For exact signatures, use the linked feature docs and the
 [API reference](./api-reference.md).
 
 ## Start Here
 
-| Scenario           | Use when                                                          | Recipe                                                     |
-| ------------------ | ---------------------------------------------------------------- | --------------------------------------------------------- |
-| Find elements      | You're new and need to point CraftDriver at the element you want. | [Find Elements On The Page](./recipes/find-elements.md)   |
+| Scenario      | Use when                                                          | Recipe                                                  |
+| ------------- | ----------------------------------------------------------------- | ------------------------------------------------------- |
+| Find elements | You're new and need to point CraftDriver at the element you want. | [Find Elements On The Page](./recipes/find-elements.md) |
 
 ## Test Structure
 
-| Scenario                  | Use when                                                                   | Recipe                                                                     |
-| ------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| Vitest browser lifecycle  | You want one browser per test file and a fresh page per test.              | [Use CraftDriver With Vitest Hooks](./recipes/vitest-browser-lifecycle.md) |
-| Login once, reuse session | Login UI is slow or noisy and most tests start signed in.                  | [Log In Once And Reuse The Session](./recipes/login-once-reuse-session.md) |
-| Multi-user flows          | You need Alice and Bob signed in at the same time without leaking cookies. | [Test Multi-User Workflows](./recipes/multi-user-contexts.md)              |
-| Page objects              | Selectors and steps are copy-pasted across tests and break together.       | [Organize Flows With Page Objects](./recipes/page-objects.md)              |
+| Scenario                       | Use when                                                                   | Recipe                                                                                |
+| ------------------------------ | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| Vitest browser lifecycle       | You want one browser per test file and a fresh page per test.              | [Use CraftDriver With Vitest Hooks](./recipes/vitest-browser-lifecycle.md)            |
+| Login once, reuse session      | Login UI is slow or noisy and most tests start signed in.                  | [Log In Once And Reuse The Session](./recipes/login-once-reuse-session.md)            |
+| Multi-user flows               | You need Alice and Bob signed in at the same time without leaking cookies. | [Test Multi-User Workflows](./recipes/multi-user-contexts.md)                         |
+| Page objects                   | Selectors and steps are copy-pasted across tests and break together.       | [Organize Flows With Page Objects](./recipes/page-objects.md)                         |
 
 ## App Behavior
 
@@ -49,4 +53,19 @@ For exact signatures, use the linked feature docs and the
 | ----------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
 | Accessibility regression gate | CI should fail on serious page or component accessibility issues.               | [Run Accessibility Gates](./recipes/accessibility-gate.md)               |
 | Console and JavaScript errors | Tests should fail if the browser reports unexpected client-side errors.         | [Fail On Console And JavaScript Errors](./recipes/console-error-gate.md) |
-| Evidence on failure           | You want a replayable trail of actions, network, logs, errors, and screenshots. | [Capture Failure Evidence With Tracing](./recipes/trace-failing-test.md) |
+| Debug failing tests           | You need the actions, screenshots, logs, and network activity behind a failure. | [Use Traces To Debug Failing Tests](./recipes/debug-failing-tests-with-traces.md) |
+
+## Electron
+
+Driving a packaged Electron desktop app. These use paths you adapt to your app
+repo rather than the hosted browser examples, and the mocking/deep-link recipes
+need main-process access (`electron: { mainProcess: true }`). See
+[Testing Electron Apps](./electron.md) for setup, drivers, and the security
+boundary.
+
+| Scenario                       | Use when                                                                   | Recipe                                                                                |
+| ------------------------------ | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| Electron app from another repo | Your packaged Electron app is built in one repo and tested from another.   | [Test An Electron App From Another Repo](./recipes/electron-app-from-another-repo.md) |
+| Electron native dialog         | A renderer flow opens an operating-system file, save, or message dialog.   | [Mock A Native Electron File Dialog](./recipes/electron-native-dialog.md)             |
+| Electron API mocking           | A flow calls `shell.openExternal`, `clipboard.writeText`, or similar.      | [Mock Electron APIs](./recipes/electron-mock-apis.md)                                 |
+| Electron deep link             | Your app registers a `myapp://` scheme and must handle links from the OS.  | [Test An Electron Deep Link](./recipes/electron-deep-link.md)                         |