API Reference | WebdriverIO
Skip to main content

API Reference

This document provides a complete reference for all browser.electron.* methods and exported utility functions provided by the service.

Table of Contents​

Utility Functions​

These functions are exported directly from the package and can be used independently of the WDIO test runner.

createElectronCapabilities()​

Creates an Electron capabilities object for use with startWdioSession() or in WDIO configuration. Builds the correct capability structure including goog:chromeOptions and wdio:electronServiceOptions.

Signature:

import { createElectronCapabilities } from '@wdio/electron-service';

createElectronCapabilities(options: ElectronServiceOptions): ElectronStandaloneCapability

Parameters:

ParameterTypeDescription
optionsElectronServiceOptionsService options. Must include at least appBinaryPath or appEntryPoint.

Common fields:

FieldTypeDescription
appBinaryPathstringPath to the compiled Electron app binary
appEntryPointstringPath to the unpackaged app entry point (e.g., main.js)
appArgsstring[]Command-line arguments passed to the app
captureMainProcessLogsbooleanEnable main process log capture
captureRendererLogsbooleanEnable renderer process log capture
logDirstringDirectory for standalone mode logs

See Configuration for the full list of ElectronServiceOptions fields.

Returns:

ElectronStandaloneCapability - A single capabilities object

Throws:

ErrorCondition
ErrorIf neither appBinaryPath nor appEntryPoint is provided

Example:

import { startWdioSession, createElectronCapabilities } from '@wdio/electron-service';

const caps = createElectronCapabilities({
  appBinaryPath: './dist/mac/MyApp.app/Contents/MacOS/MyApp',
  appArgs: ['--disable-gpu', '--headless'],
  captureMainProcessLogs: true,
  logDir: './test-logs',
});

const browser = await startWdioSession([caps]);

See Also:

getElectronBinaryPath()​

Resolves the path to the Electron binary for a given app directory. Uses the same detection logic as the service (reading package.json, checking Electron Forge/Builder configs) without starting a session.

Signature:

import { getElectronBinaryPath } from '@wdio/electron-service';

getElectronBinaryPath(appDir: string): Promise<string>

Parameters:

ParameterTypeDescription
appDirstringPath to the Electron app directory (must contain a package.json)

Returns:

Promise<string> - The resolved path to the Electron binary

Throws:

ErrorCondition
ErrorIf no package.json is found in appDir
ErrorIf the binary path cannot be resolved

Example:

import { getElectronBinaryPath } from '@wdio/electron-service';

const binaryPath = await getElectronBinaryPath('/path/to/my-electron-app');
console.log(binaryPath);
// e.g. '/path/to/my-electron-app/dist/mac-arm64/MyApp.app/Contents/MacOS/MyApp'

See Also:

startWdioSession()​

Starts a WebdriverIO session in standalone mode (without the WDIO test runner). Performs the same launcher setup the runner does — binary detection, capability mutation, log writer initialization — and returns a browser instance.

Signature:

import { startWdioSession } from '@wdio/electron-service';

startWdioSession(
  capabilities: ElectronServiceCapabilities,
  globalOptions?: ElectronServiceGlobalOptions,
): Promise<WebdriverIO.Browser>

Parameters:

ParameterTypeDescription
capabilitiesElectronServiceCapabilitiesAn array of standalone capability objects (typically one, built with createElectronCapabilities()), or a multiremote capabilities object.
globalOptionsElectronServiceGlobalOptionsOptional. Service-level options applied to all capabilities (e.g., rootDir).

Returns:

Promise<WebdriverIO.Browser> - The browser instance, with browser.electron.* available.

Example:

import { startWdioSession, cleanupWdioSession, createElectronCapabilities } from '@wdio/electron-service';

const caps = createElectronCapabilities({
  appBinaryPath: '/path/to/MyApp',
  captureMainProcessLogs: true,
  logDir: './logs',
});

const browser = await startWdioSession([caps]);

try {
  const name = await browser.electron.execute((electron) => electron.app.getName());
  console.log(name);
} finally {
  await cleanupWdioSession(browser);
}

See Also:

cleanupWdioSession()​

Tears down a standalone session started with startWdioSession(). Calls browser.deleteSession() and runs the launcher's onComplete cleanup so the Electron process and any spawned drivers are released.

Signature:

import { cleanupWdioSession } from '@wdio/electron-service';

cleanupWdioSession(browser: WebdriverIO.Browser): Promise<void>

Parameters:

ParameterTypeDescription
browserWebdriverIO.BrowserThe browser instance returned from startWdioSession().

Returns:

Promise<void>

See Also:

Execution Methods​

execute()​

Executes arbitrary JavaScript code in the Electron main process context.

Signature:

browser.electron.execute<T>(
  script: (electron, ...args) => T | Promise<T>,
  ...args: any[]
): Promise<T>

Parameters:

ParameterTypeDescription
script(electron, ...args) => T | Promise<T>Function to execute in main process. First arg is always the electron module.
...argsany[]Additional arguments passed to the script function

Returns:

Promise<T> - Resolves with the return value of the script

Example:

// Simple execution
const appName = await browser.electron.execute((electron) => {
  return electron.app.getName();
});

// With parameters
const result = await browser.electron.execute(
  (electron, param1, param2) => {
    return param1 + param2;
  },
  5,
  10
);

// With async code
const fileIcon = await browser.electron.execute(async (electron) => {
  return await electron.app.getFileIcon('/path/to/file');
});

See Also:

Triggers a deeplink to the Electron application for testing protocol handlers.

On Windows and Linux, this automatically appends the test instance's userData directory to ensure the deeplink reaches the correct instance. On macOS, it works transparently without modification.

Signature:

browser.electron.triggerDeeplink(url: string): Promise<void>

Parameters:

ParameterTypeDescription
urlstringThe deeplink URL to trigger (e.g., 'myapp://open?path=/test'). Must use a custom protocol scheme (not http/https/file).

Returns:

Promise<void> - Resolves when the deeplink has been triggered.

Throws:

ErrorCondition
ErrorIf appBinaryPath is not configured (Windows/Linux only)
ErrorIf the URL is invalid or malformed
ErrorIf the URL uses http/https/file protocols
ErrorIf the platform is unsupported
ErrorIf the command to trigger the deeplink fails

Example:

// Basic usage
await browser.electron.triggerDeeplink('myapp://open?file=test.txt');

// With complex parameters
await browser.electron.triggerDeeplink('myapp://action?id=123&type=user&tags[]=a&tags[]=b');

// In a test with verification
it('should handle deeplinks', async () => {
  await browser.electron.triggerDeeplink('myapp://navigate?to=/settings');

  await browser.waitUntil(async () => {
    const currentPath = await browser.electron.execute(() => {
      return globalThis.currentPath;
    });
    return currentPath === '/settings';
  }, {
    timeout: 5000,
    timeoutMsg: 'App did not process the deeplink'
  });
});

Platform-Specific Behavior:

  • Windows: Cannot use appEntryPoint (must use packaged binary). Automatically appends userData parameter to URL.
  • macOS: Works with both packaged binaries and script-based apps. No URL modification.
  • Linux: Cannot use appEntryPoint (must use packaged binary). Automatically appends userData parameter to URL.

See Also:

Mocking Methods​

mock()