electron-playwright-helpers v1.7.1

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 -

parseElectronApp(buildDir) ⇒ ElectronAppInfo

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

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

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

ElectronAppInfo

Kind: global typedef
Properties

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

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.

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

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

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

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

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

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

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

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

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

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

Kind: global function
Category: IPCRenderer
Fulfil: unknown the result of the first 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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