Automated Testing

    From ChromeDriver - WebDriver for Chrome:

    There are a few ways that you can set up testing using WebDriver.

    (WDIO) is a test automation framework that provides a Node.js package for testing with WebDriver. Its ecosystem also includes various plugins (e.g. reporter and services) that can help you put together your test setup.

    Install the testrunner

    First you need to run the WebdriverIO starter toolkit in your project root directory:

    This installs all necessary packages for you and generates a configuration file.

    Connect WDIO to your Electron app

    Update the capabilities in your configuration file to point to your Electron app binary:

    1. export.config = {
    2.   // ...
    3.   capabilities: [{
    4.     browserName: 'chrome',
    5.     'goog:chromeOptions': {
    6.       binary: '/path/to/your/electron/binary', // Path to your Electron binary.
    7.       args: [/* cli arguments */] // Optional, perhaps 'app=' + /path/to/your/app/
    8.     }
    9.   }]
    10.   // ...
    11. }

    Run your tests

    To run your tests:

    1. $ npx wdio run wdio.conf.js

    is a web automation framework that exposes bindings to WebDriver APIs in many languages. Their Node.js bindings are available under the selenium-webdriver package on NPM.

    Run a ChromeDriver server

    In order to use Selenium with Electron, you need to download the electron-chromedriver binary, and run it:

    1. npm install --save-dev electron-chromedriver
    2. ./node_modules/.bin/chromedriver
    3. Starting ChromeDriver (v2.10.291558) on port 9515
    4. Only local connections are allowed.

    Connect Selenium to ChromeDriver

    Next, install Selenium into your project:

    1. npm install --save-dev selenium-webdriver

    Usage of selenium-webdriver with Electron is the same as with normal websites, except that you have to manually specify how to connect ChromeDriver and where to find the binary of your Electron app:

    1. const webdriver = require('selenium-webdriver')
    2. const driver = new webdriver.Builder()
    3.   // The "9515" is the port opened by ChromeDriver.
    4.   .usingServer('http://localhost:9515')
    5.   .withCapabilities({
    6.     'goog:chromeOptions': {
    7.       // Here is the path to your Electron binary.
    8.       binary: '/Path-to-Your-App.app/Contents/MacOS/Electron'
    9.     }
    10.   })
    11.   .forBrowser('chrome') // note: use .forBrowser('electron') for selenium-webdriver <= 3.6.0
    12.   .build()
    13. driver.get('http://www.google.com')
    14. driver.findElement(webdriver.By.name('q')).sendKeys('webdriver')
    15. driver.findElement(webdriver.By.name('btnG')).click()
    16. driver.wait(() => {
    17.   return driver.getTitle().then((title) => {
    18.     return title === 'webdriver - Google Search'
    19.   })
    20. }, 1000)
    21. driver.quit()

    Microsoft Playwright is an end-to-end testing framework built using browser-specific remote debugging protocols, similar to the headless Node.js API but geared towards end-to-end testing. Playwright has experimental Electron support via Electron’s support for the Chrome DevTools Protocol (CDP).

    You can install Playwright through your preferred Node.js package manager. The Playwright team recommends using the PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD environment variable to avoid unnecessary browser downloads when testing an Electron app.

    Playwright also comes with its own test runner, Playwright Test, which is built for end-to-end testing. You can also install it as a dev dependency in your project:

    1. npm install --save-dev @playwright/test

    :::caution Dependencies This tutorial was written playwright@1.16.3 and @playwright/test@1.16.3. Check out page to learn about changes that might affect the code below. :::

    :::info Using third-party test runners If you’re interested in using an alternative test runner (e.g. Jest or Mocha), check out Playwright’s Third-Party Test Runner guide. :::

    Playwright launches your app in development mode through the _electron.launch API. To point this API to your Electron app, you can pass the path to your main process entry point (here, it is main.js).

    1. const { _electron: electron } = require('playwright')
    2. const { test } = require('@playwright/test')
    4. test('launch app', async () => {
    5.   const electronApp = await electron.launch({ args: ['main.js'] })
    6.   // close app
    7.   await electronApp.close()
    8. })

    After that, you will access to an instance of Playwright’s ElectronApp class. This is a powerful class that has access to main process modules for example:

    1. const { _electron: electron } = require('playwright')
    2. const { test } = require('@playwright/test')
    4. test('get isPackaged', async () => {
    5.   const electronApp = await electron.launch({ args: ['main.js'] })
    6.   const isPackaged = await electronApp.evaluate(async ({ app }) => {
    7.     // This runs in Electron's main process, parameter here is always
    8.     // the result of the require('electron') in the main app script.
    9.     return app.isPackaged
    10.   })
    11.   console.log(isPackaged) // false (because we're in development mode)
    12.   await electronApp.close()
    13. })

    It can also create individual objects from Electron BrowserWindow instances. For example, to grab the first BrowserWindow and save a screenshot:

    1. const { _electron: electron } = require('playwright')
    2. const { test } = require('@playwright/test')
    4. test('save screenshot', async () => {
    5.   const electronApp = await electron.launch({ args: ['main.js'] })
    6.   const window = await electronApp.firstWindow()
    7.   await window.screenshot({ path: 'intro.png' })
    8.   // close app
    9.   await electronApp.close()
    10. })
    1. const { _electron: electron } = require('playwright')
    2. const { test, expect } = require('@playwright/test')
    4. test('example test', async () => {
    5.   const electronApp = await electron.launch({ args: ['.'] })
    6.   const isPackaged = await electronApp.evaluate(async ({ app }) => {
    7.     // This runs in Electron's main process, parameter here is always
    8.     // the result of the require('electron') in the main app script.
    9.     return app.isPackaged;
    10.   });
    12.   expect(isPackaged).toBe(false);
    14.   // Wait for the first BrowserWindow to open
    15.   // and return its Page object
    16.   const window = await electronApp.firstWindow()
    17.   await window.screenshot({ path: 'intro.png' })
    19.   // close app
    20.   await electronApp.close()
    21. });

    Then, run Playwright Test using npx playwright test. You should see the test pass in your console, and have an intro.png screenshot on your filesystem.

    :::info Playwright Test will automatically run any files matching the .*(test|spec)\.(js|ts|mjs) regex. You can customize this match in the Playwright Test configuration options. :::

    :::tip Further reading Check out Playwright’s documentation for the full and ElectronApplication class APIs. :::

    It’s also possible to write your own custom driver using Node.js’ built-in IPC-over-STDIO. Custom test drivers require you to write additional app code, but have lower overhead and let you expose custom methods to your test suite.

    To create a custom driver, we’ll use Node.js’ API. The test suite will spawn the Electron process, then establish a simple messaging protocol:

    1. const childProcess = require('child_process')
    2. const electronPath = require('electron')
    4. // spawn the process
    5. const env = { /* ... */ }
    6. const stdio = ['inherit', 'inherit', 'inherit', 'ipc']
    7. const appProcess = childProcess.spawn(electronPath, ['./app'], { stdio, env })
    9. // listen for IPC messages from the app
    10. appProcess.on('message', (msg) => {
    11.   // ...
    12. })
    14. // send an IPC message to the app
    15. appProcess.send({ my: 'message' })

    From within the Electron app, you can listen for messages and send replies using the Node.js process API:

    1. // listen for messages from the test suite
    2. process.on('message', (msg) => {
    3.   // ...
    4. })
    6. // send a message to the test suite
    7. process.send({ my: 'message' })

    We can now communicate from the test suite to the Electron app using the appProcess object.

    For convenience, you may want to wrap appProcess in a driver object that provides more high-level functions. Here is an example of how you can do this. Let’s start by creating a TestDriver class:

    1. class TestDriver {
    2.   constructor ({ path, args, env }) {
    3.     this.rpcCalls = []
    5.     // start child process
    6.     env.APP_TEST_DRIVER = 1 // let the app know it should listen for messages
    7.     this.process = childProcess.spawn(path, args, { stdio: ['inherit', 'inherit', 'inherit', 'ipc'], env })
    9.     // handle rpc responses
    10.     this.process.on('message', (message) => {
    11.       // pop the handler
    12.       const rpcCall = this.rpcCalls[message.msgId]
    13.       if (!rpcCall) return
    14.       this.rpcCalls[message.msgId] = null
    16.       else rpcCall.resolve(message.resolve)
    17.     })
    19.     // wait for ready
    20.     this.isReady = this.rpc('isReady').catch((err) => {
    21.       console.error('Application failed to start', err)
    22.       this.stop()
    23.       process.exit(1)
    24.     })
    25.   }
    27.   // simple RPC call
    28.   // to use: driver.rpc('method', 1, 2, 3).then(...)
    29.   async rpc (cmd, ...args) {
    30.     // send rpc request
    31.     const msgId = this.rpcCalls.length
    32.     this.process.send({ msgId, cmd, args })
    33.     return new Promise((resolve, reject) => this.rpcCalls.push({ resolve, reject }))
    34.   }
    36.   stop () {
    37.     this.process.kill()
    38.   }
    39. }
    41. module.exports = { TestDriver };

    In your app code, can then write a simple handler to receive RPC calls:

    1. const METHODS = {
    2.   isReady () {
    3.     // do any setup needed
    4.     return true
    5.   }
    6.   // define your RPC-able methods here
    7. }
    9. const onMessage = async ({ msgId, cmd, args }) => {
    10.   let method = METHODS[cmd]
    11.   if (!method) method = () => new Error('Invalid method: ' + cmd)
    12.   try {
    13.     const resolve = await method(...args)
    14.     process.send({ msgId, resolve })
    15.   } catch (err) {
    16.     const reject = {
    17.       message: err.message,
    18.       stack: err.stack,
    19.       name: err.name
    20.     }
    21.     process.send({ msgId, reject })
    22.   }
    23. }
    25. if (process.env.APP_TEST_DRIVER) {
    26.   process.on('message', onMessage)
    27. }

    Then, in your test suite, you can use your TestDriver class with the test automation framework of your choosing. The following example uses , but other popular choices like Jest or Mocha would work as well:

    1. const test = require('ava')
    2. const electronPath = require('electron')
    3. const { TestDriver } = require('./testDriver')
    5. const app = new TestDriver({
    6.   path: electronPath,
    7.   args: ['./app'],
    8.   env: {
    9.     NODE_ENV: 'test'
    10.   }
    11. })
    12. test.before(async t => {
    13.   await app.isReady
    14. })
    15. test.after.always('cleanup', async t => {
    16.   await app.stop()
    17. })