Electron Playwright Helpers

Helper functions to make it easier to use Playwright for end-to-end testing with Electron. Parse packaged Electron projects so you can run tests on them. Click Electron menu items, send IPC messages, get menu structures, stub dialog.showOpenDialog() results, etc.

Installation

npm i -D electron-playwright-helpers

Usage

For a full example of how to use this library, see the electron-playwright-example project. But here's a quick example:

Javascript:

const eph = require('electron-playwright-helpers')
// - or cherry pick -
const { findLatestBuild, parseElectronApp, clickMenuItemById } = require('electron-playwright-helpers')

let electronApp: ElectronApplication

test.beforeAll(async () => {
  // find the latest build in the out directory
  const latestBuild = findLatestBuild()
  // parse the packaged Electron app and find paths and other info
  const appInfo = parseElectronApp(latestBuild)
  electronApp = await electron.launch({
    args: [appInfo.main], // main file from package.json
    executablePath: appInfo.executable // path to the Electron executable
  })
})

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

test('open a file', async () => {
  // stub electron dialog so dialog.showOpenDialog() 
  // will return a file path without opening a dialog
  await eph.stubDialog(electronApp, 'showOpenDialog', { filePaths: ['/path/to/file'] })

  // call the click method of menu item in the Electron app's application menu
  await eph.clickMenuItemById(electronApp, 'open-file')

  // get the result of an ipcMain.handle() function
  const result = await eph.ipcMainInvokeHandler(electronApp, 'get-open-file-path')
  
  // result should be the file path
  expect(result).toBe('/path/to/file')
})

Typescript:

import * as eph from 'electron-playwright-helpers'
// - or cherry pick -
import { electronWaitForFunction, ipcMainCallFirstListener, clickMenuItemById } from 'electron-playwright-helpers'

// then same as Javascript above

Contributing

Yes, please! Pull requests are always welcome. Feel free to add or suggest new features, fix bugs, etc.

Please use Conventional Commit messages for your commits. This project uses semantic-release to automatically publish new versions to NPM. The commit messages are used to determine the version number and changelog. We're also using Prettier as our code format and ESlint to enforce formatting, so please make sure your code is formatted before submitting a PR.

Additional Resources

• Electron Playwright Example - an example of how to use this library
• Playwright Electron Class - Playwright API docs for Electron
• Electron API - Electron API documentation

API

Functions

Typedefs

findLatestBuild(buildDirectory) ⇒ string

Kind: global function
Returns: string -

| Param | Type | Default | Description | | --- | --- | --- | --- | | buildDirectory | string | "out" | optional - the directory to search for the latest build (path/name relative to package root or full path starting with /). Defaults to out. |

parseElectronApp(buildDir) ⇒ ElectronAppInfo

Kind: global function
Returns: ElectronAppInfo - metadata about the app

| Param | Type | Description | | --- | --- | --- | | buildDir | string | absolute path to the build directory or the app itself |

electronWaitForFunction(electronApp, fn, arg) ⇒ Promise.<void>

Kind: global function
Fulfil: void Resolves when the function returns true

| Param | Type | Description | | --- | --- | --- | | electronApp | ElectronApplication | the Playwright ElectronApplication | | fn | function | the function to evaluate in the main process - must return a boolean | | arg | Any | optional - an argument to pass to the function |

ElectronAppInfo

Kind: global typedef
Properties

| Name | Type | Description | | --- | --- | --- | | executable | string | path to the Electron executable | | main | string | path to the main (JS) file | | name | string | name of the your application | | resourcesDir | string | path to the resources directory | | asar | boolean | whether the app is packaged as an asar archive | | platform | string | 'darwin', 'linux', or 'win32' | | arch | string | 'x64', 'x32', or 'arm64' | | packageJson | PackageJson | the JSON.parse()'d contents of the package.json file. |

stubDialog(app, method, value) ⇒ Promise.<void>

Kind: global function
Returns: Promise.<void> - A promise that resolves when the mock is applied.
Category: Dialog
Fullfil: void - A promise that resolves when the mock is applied.
See: stubMultipleDialogs

| Param | Type | Description | | --- | --- | --- | | app | ElectronApplication | The Playwright ElectronApplication instance. | | method | String | The dialog method to mock. | | value | ReturnType.<Electron.Dialog> | The value that your application will receive when calling this dialog method. See the Electron docs for the return value of each method. |

Example

await stubDialog(app, 'showOpenDialog', {
 filePaths: ['/path/to/file'],
 canceled: false,
})
await clickMenuItemById(app, 'open-file')
// when time your application calls dialog.showOpenDialog,
// it will return the value you specified

stubMultipleDialogs(app, mocks) ⇒ Promise.<void>

Kind: global function
Returns: Promise.<void> - A promise that resolves when the mocks are applied.
Category: Dialog
Fullfil: void - A promise that resolves when the mocks are applied.

| Param | Type | Description | | --- | --- | --- | | app | ElectronApplication | The Playwright ElectronApplication instance. | | mocks | Array.<DialogMethodStubPartial> | An array of dialog method mocks to apply. |

Example

await stubMultipleDialogs(app, [
 {
   method: 'showOpenDialog',
   value: {
     filePaths: ['/path/to/file1', '/path/to/file2'],
     canceled: false,
   },
 },
 {
    method: 'showSaveDialog',
    value: {
      filePath: '/path/to/file',
      canceled: false,
    },
  },
])
await clickMenuItemById(app, 'save-file')
// when your application calls dialog.showSaveDialog,
// it will return the value you specified

stubAllDialogs(app) ⇒ Promise.<void>

Kind: global function
Returns: Promise.<void> - A promise that resolves when the mocks are applied.
Category: Dialog
Fullfil: void - A promise that resolves when the mocks are applied.
See: stubDialog

| Param | Type | Description | | --- | --- | --- | | app | ElectronApplication | The Playwright ElectronApplication instance. |

ipcMainEmit(electronApp, message, ...args) ⇒ Promise.<boolean>

Kind: global function
Category: IPCMain
Fulfil: boolean true if there were listeners for this message
Reject: Error if there are no ipcMain listeners for the event

| Param | Type | Description | | --- | --- | --- | | electronApp | ElectronApplication | the ElectronApplication object from Playwright | | message | string | the channel to call all ipcMain listeners for | | ...args | unknown | one or more arguments to send |

ipcMainCallFirstListener(electronApp, message, ...args) ⇒ Promise.<unknown>

Kind: global function
Category: IPCMain
Fulfil: unknown resolves with the result of the function
Reject: Error if there are no ipcMain listeners for the event

| Param | Type | Description | | --- | --- | --- | | electronApp | ElectronApplication | the ElectronApplication object from Playwright | | message | string | the channel to call the first listener for | | ...args | unknown | one or more arguments to send |

ipcMainInvokeHandler(electronApp, message, ...args) ⇒ Promise.<unknown>

Kind: global function
Category: IPCMain
Fulfil: unknown resolves with the result of the function called in main process

| Param | Type | Description | | --- | --- | --- | | electronApp | ElectronApplication | the ElectronApplication object from Playwright | | message | string | the channel to call the first listener for | | ...args | unknown | one or more arguments to send |

ipcRendererSend(page, channel, ...args) ⇒ Promise.<unknown>

Kind: global function
Category: IPCRenderer
Fulfil: unknown resolves with the result of ipcRenderer.send()

| Param | Type | Description | | --- | --- | --- | | page | Page | the Playwright Page to send the ipcRenderer.send() from | | channel | string | the channel to send the ipcRenderer.send() to | | ...args | unknown | one or more arguments to send to the ipcRenderer.send() |

ipcRendererInvoke(page, message, ...args) ⇒ Promise.<unknown>

Kind: global function
Category: IPCRenderer
Fulfil: unknown resolves with the result of ipcRenderer.invoke()

| Param | Type | Description | | --- | --- | --- | | page | Page | the Playwright Page to send the ipcRenderer.invoke() from | | message | string | the channel to send the ipcRenderer.invoke() to | | ...args | unknown | one or more arguments to send to the ipcRenderer.invoke() |

ipcRendererCallFirstListener(page, message, ...args) ⇒ Promise.<unknown>

Kind: global function
Category: IPCRenderer
Fulfil: unknown the result of the first ipcRenderer.on() listener

| Param | Type | Description | | --- | --- | --- | | page | Page | The Playwright Page to with the ipcRenderer.on() listener | | message | string | The channel to call the first listener for | | ...args | unknown | optional - One or more arguments to send to the ipcRenderer.on() listener |

ipcRendererEmit(page, message, ...args) ⇒ Promise.<boolean>

Kind: global function
Category: IPCRenderer
Fulfil: boolean true if the event was emitted
Reject: Error if there are no ipcRenderer listeners for the event

| Param | Type | Description | | --- | --- | --- | | page | Page | the Playwright Page to with the ipcRenderer.on() listener | | message | string | the channel to call all ipcRenderer listeners for | | ...args | unknown | optional - one or more arguments to send |

clickMenuItemById(electronApp, id) ⇒ Promise.<void>

Kind: global function
Category: Menu
Fulfil: void resolves with the result of the click() method - probably undefined

| Param | Type | Description | | --- | --- | --- | | electronApp | ElectronApplication | the Electron application object (from Playwright) | | id | string | the id of the MenuItem to click |

clickMenuItem(electronApp, property, value) ⇒ Promise.<void>

Kind: global function
Category: Menu
Fulfil: void resolves with the result of the click() method - probably undefined

| Param | Type | Description | | --- | --- | --- | | electronApp | ElectronApplication | the Electron application object (from Playwright) | | property | String | a property of the MenuItem to search for | | value | String | Number | Boolean | the value of the property to search for |

getMenuItemAttribute(electronApp, menuId, attribute) ⇒ Promise.<string>

Kind: global function
Category: Menu
Fulfil: string resolves with the attribute value

| Param | Type | Description | | --- | --- | --- | | electronApp | ElectronApplication | the Electron application object (from Playwright) | | menuId | string | the id of the MenuItem to retrieve the attribute from | | attribute | string | the attribute to retrieve |

getMenuItemById(electronApp, menuId) ⇒ Promise.<MenuItemPartial>

Kind: global function
Category: Menu
Fulfil: MenuItemPartial the MenuItem with the given id

| Param | Type | Description | | --- | --- | --- | | electronApp | ElectronApplication | the Electron application object (from Playwright) | | menuId | string | the id of the MenuItem to retrieve |

getApplicationMenu(electronApp) ⇒ Promise.<Array.<MenuItemPartial>>

Kind: global function
Category: Menu
Fulfil: MenuItemPartial[] an array of MenuItem-like objects

| Param | Type | Description | | --- | --- | --- | | electronApp | ElectronApplication | the Electron application object (from Playwright) |

findMenuItem(electronApp, property, value, menuItems) ⇒ Promise.<MenuItemPartial>

Kind: global function
Category: Menu
Fulfil: MenuItemPartial the first MenuItem with the given property and value

| Param | Type | Description | | --- | --- | --- | | electronApp | ElectronApplication | the Electron application object (from Playwright) | | property | string | the property to search for | | value | string | the value to search for | | menuItems | MenuItemPartial | Array.<MenuItemPartial> | optional - single MenuItem or array - if not provided, will be retrieved from the application menu |

waitForMenuItem(electronApp, id) ⇒ Promise.<void>

Kind: global function
Category: Menu
Fulfil: void resolves when the MenuItem is found

| Param | Type | Description | | --- | --- | --- | | electronApp | ElectronApplication | the Electron application object (from Playwright) | | id | string | the id of the MenuItem to wait for |

waitForMenuItemStatus(electronApp, id, property, value) ⇒ Promise.<void>

Kind: global function
Category: Menu
Fulfil: void resolves when the MenuItem with correct status is found

| Param | Type | Description | | --- | --- | --- | | electronApp | ElectronApplication | the Electron application object (from Playwright) | | id | string | the id of the MenuItem to wait for | | property | string | the property to search for | | value | string | number | boolean | the value to search for |

addTimeoutToPromise(promise, timeoutMs, timeoutMessage) ⇒ Promise.<T>

Kind: global function
Returns: Promise.<T> - the result of the original promise if it resolves before the timeout
Category: Utilities
See: addTimeout

| Param | Default | Description | | --- | --- | --- | | promise | | the promise to add a timeout to - must be a Promise | | timeoutMs | 5000 | the timeout in milliseconds - defaults to 5000 | | timeoutMessage | | optional - the message to return if the timeout is reached |

addTimeout(functionName, timeoutMs, timeoutMessage, ...args) ⇒ Promise.<T>

Kind: global function
Returns: Promise.<T> - the result of the helper function if it resolves before the timeout
Category: Utilities

| Param | Default | Description | | --- | --- | --- | | functionName | | the name of the helper function to call | | timeoutMs | 5000 | the timeout in milliseconds - defaults to 5000 | | timeoutMessage | | optional - the message to return if the timeout is reached | | ...args | | any arguments to pass to the helper function |