electron-playwright-helpers

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, 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('click menu item', async () => {
  await eph.clickMenuItemById(electronApp, 'newproject')
})

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 new features, fix bugs, etc.

API

Functions

findLatestBuild() ⇒ string

Parses the out directory to find the latest build of your Electron project. Use npm run package (or similar) to build your app prior to testing.

parseElectronApp(buildDir) ⇒ ElectronAppInfo

Given a directory containing an Electron app build, or the path to the app itself (directory on Mac, executable on Windows), return a bunch of metadata, including the path to the app's executable and the path to the app's main file.

Format of the data returned is an object with the following properties:

• executable: path to the app's executable file
• main: path to the app's main (JS) file
• name: name of the app
• resourcesDir: path to the app's resources directory
• asar: true if the app is using asar
• platform: OS platform
• arch: architecture

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

Wait for a function to evaluate to true in the main Electron process. This really should be part of the Playwright API, but it's not.

This function is to electronApp.evaluate() as page.waitForFunction() is page.evaluate().

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

Emit an ipcMain message from the main process. This will trigger all ipcMain listeners for the event.

This does not transfer data between main and renderer processes. It simply emits an event in the main process.

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

Call the first listener for a given ipcMain message in the main process and return its result.

NOTE: ipcMain listeners usually don't return a value, but we're using this to retrieve test data from the main process.

Generally, it's probably better to use ipcMainInvokeHandler() instead.

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

Get the return value of an ipcMain.handle() function

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

Send an ipcRenderer.send() (to main process) from a given window.

Note: nodeIntegration must be true and contextIsolation must be false in the webPreferences for this BrowserWindow.

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

Send an ipcRenderer.invoke() from a given window.

Note: nodeIntegration must be true and contextIsolation must be false in the webPreferences for this window

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

Call just the first listener for a given ipcRenderer channel in a given window. UNLIKE MOST Electron ipcRenderer listeners, this function SHOULD return a value.

This function does not send data between main and renderer processes. It simply retrieves data from the renderer process.

Note: nodeIntegration must be true for this BrowserWindow.

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

Emit an IPC event to a given window. This will trigger all ipcRenderer listeners for the event.

This does not transfer data between main and renderer processes. It simply emits an event in the renderer process.

Note: nodeIntegration must be true for this window

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

Execute the .click() method on the element with the given id.

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

Get a given attribute the MenuItem with the given id.

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

Get information about the MenuItem with the given id

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

Get the current state of the application menu. Contains only primitive values and submenus.. Very similar to menu construction template structure in Electron.

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

Find a MenuItem by any of its properties

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

Wait for a MenuItem to exist

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

Wait for a MenuItem to have a specific attribute value. For example, wait for a MenuItem to be enabled... or be visible.. etc

findLatestBuild() ⇒ string

Parses the out directory to find the latest build of your Electron project. Use npm run package (or similar) to build your app prior to testing.

Kind: global function
Returns: string -

• path to the most recently modified build directory

parseElectronApp(buildDir) ⇒ ElectronAppInfo

Given a directory containing an Electron app build, or the path to the app itself (directory on Mac, executable on Windows), return a bunch of metadata, including the path to the app's executable and the path to the app's main file.

Format of the data returned is an object with the following properties:

• executable: path to the app's executable file
• main: path to the app's main (JS) file
• name: name of the app
• resourcesDir: path to the app's resources directory
• asar: true if the app is using asar
• platform: OS platform
• arch: architecture

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>

Wait for a function to evaluate to true in the main Electron process. This really should be part of the Playwright API, but it's not.

This function is to electronApp.evaluate() as page.waitForFunction() is page.evaluate().

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

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

Emit an ipcMain message from the main process. This will trigger all ipcMain listeners for the event.

This does not transfer data between main and renderer processes. It simply emits an event in the main process.

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>

Call the first listener for a given ipcMain message in the main process and return its result.

NOTE: ipcMain listeners usually don't return a value, but we're using this to retrieve test data from the main process.

Generally, it's probably better to use ipcMainInvokeHandler() instead.

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>

Get the return value of an ipcMain.handle() function

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>

Send an ipcRenderer.send() (to main process) from a given window.

Note: nodeIntegration must be true and contextIsolation must be false in the webPreferences for this BrowserWindow.

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>

Send an ipcRenderer.invoke() from a given window.

Note: nodeIntegration must be true and contextIsolation must be false in the webPreferences for this window

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(window, message, ...args) ⇒ Promise.<unknown>

Call just the first listener for a given ipcRenderer channel in a given window. UNLIKE MOST Electron ipcRenderer listeners, this function SHOULD return a value.

This function does not send data between main and renderer processes. It simply retrieves data from the renderer process.

Note: nodeIntegration must be true for this BrowserWindow.

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

Param	Type	Description
window	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(window, message, ...args) ⇒ Promise.<boolean>

Emit an IPC event to a given window. This will trigger all ipcRenderer listeners for the event.

This does not transfer data between main and renderer processes. It simply emits an event in the renderer process.

Note: nodeIntegration must be true for this window

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
window	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>

Execute the .click() method on the element with the given id.

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

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

Get a given attribute the MenuItem with the given id.

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>

Get information about the MenuItem with the given id

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>>

Get the current state of the application menu. Contains only primitive values and submenus.. Very similar to menu construction template structure in Electron.

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>

Find a MenuItem by any of its properties

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>

Wait for a MenuItem to exist

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>

Wait for a MenuItem to have a specific attribute value. For example, wait for a MenuItem to be enabled... or be visible.. etc

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