<img src="https://cloud.githubusercontent.com/assets/378023/15063284/cf544f2c-1383-11e6-9336-e13bd64b1694.png" width="60px" align="center" alt="Spectron icon"> Spectron

🚨 Spectron is officially deprecated as of February 1, 2022.

Easily test your Electron apps using ChromeDriver and WebdriverIO.

Version Map

For given versions of Electron you must depend on a very specific version range of Spectron. Below is a version mapping table between Spectron version and Electron version.

| Electron Version | Spectron Version | |------------------|------------------| | ~1.0.0 | ~3.0.0 | | ~1.1.0 | ~3.1.0 | | ~1.2.0 | ~3.2.0 | | ~1.3.0 | ~3.3.0 | | ~1.4.0 | ~3.4.0 | | ~1.5.0 | ~3.5.0 | | ~1.6.0 | ~3.6.0 | | ~1.7.0 | ~3.7.0 | | ~1.8.0 | ~3.8.0 | | ^2.0.0 | ^4.0.0 | | ^3.0.0 | ^5.0.0 | | ^4.0.0 | ^6.0.0 | | ^5.0.0 | ^7.0.0 | | ^6.0.0 | ^8.0.0 | | ^7.0.0 | ^9.0.0 | | ^8.0.0 | ^10.0.0| | ^9.0.0 | ^11.0.0| | ^10.0.0 | ^12.0.0| | ^11.0.0 | ^13.0.0| | ^12.0.0 | ^14.0.0| | ^13.0.0 | ^15.0.0| | ^14.0.0 | ^16.0.0| | ^15.0.0 | ^17.0.0| | ^16.0.0 | ^18.0.0| | ^17.0.0 | ^19.0.0|

Learn more from this presentation.

:rotating_light: Upgrading from 1.x to 2.x/3.x? Read the changelog.

Installation

npm install --save-dev spectron

Usage

Spectron works with any testing framework but the following example uses mocha:

To get up and running from your command line:

# Install mocha locally as a dev dependency.
npm i mocha -D

# From the project root, create a folder called test, in that directory, create a file called 'spec.js'
touch test/spec.js

# Change directory to test
cd test

Then simply include the following in your first spec.js.

const { Application } = require('spectron')
const assert = require('assert')
const electronPath = require('electron') // Require Electron from the binaries included in node_modules.
const path = require('path')

describe('Application launch', function () {
  this.timeout(10000)

  beforeEach(async function () {
    this.app = new Application({
      // Your electron path can be any binary
      // i.e for OSX an example path could be '/Applications/MyApp.app/Contents/MacOS/MyApp'
      // But for the sake of the example we fetch it from our node_modules.
      path: electronPath,

      // Assuming you have the following directory structure

      //  |__ my project
      //     |__ ...
      //     |__ main.js
      //     |__ package.json
      //     |__ index.html
      //     |__ ...
      //     |__ test
      //        |__ spec.js  <- You are here! ~ Well you should be.

      // The following line tells spectron to look and use the main.js file
      // and the package.json located 1 level above.
      args: [path.join(__dirname, '..')]
    })
    await this.app.start()
  })

  afterEach(async function () {
    if (this.app && this.app.isRunning()) {
      await this.app.stop()
    }
  })

  it('shows an initial window', async function () {
    const count = await this.app.client.getWindowCount()
    assert.equal(count, 1)
    // Please note that getWindowCount() will return 2 if `dev tools` are opened.
    // assert.equal(count, 2)
  })
})

Create an npm task in your package.json file

"scripts": {
  "test": "mocha"
}

And from the root of your project, in your command-line simply run:

npm test

By default, mocha searches for a folder with the name test ( which we created before ). For more information on how to configure mocha, please visit mocha.

Limitations

As stated in issue #19, Spectron will not be able to start if your Electron app is launched using the remote-debugging-port command-line switch (i.e. app.commandLine.appendSwitch('remote-debugging-port', <debugging-port-number>);). Please make sure to include the necessary logic in your app's code to disable the switch during tests.

As mentioned in issue #202, app.start() promise won't resolve if the electron application calls setPath('userData', path). Webdriver places a port file into the userData directory and needs to know where to look for it. The workaround is to pass chromeDriverArgs: ['user-data-dir=/custom/userData/path'] to the Application constructor.

Application API

Spectron exports an Application class that when configured, can start and stop your Electron application.

new Application(options)

Create a new application with the following options:

• path - Required. String path to the Electron application executable to launch. Note: If you want to invoke electron directly with your app's main script then you should specify path as electron via electron-prebuilt and specify your app's main script path as the first argument in the args array.
• args - Array of arguments to pass to the Electron application.
• chromeDriverArgs - Array of arguments to pass to ChromeDriver. See here for details on the Chrome arguments.
• cwd- String path to the working directory to use for the launched application. Defaults to process.cwd().
• env - Object of additional environment variables to set in the launched application.
• host - String host name of the launched chromedriver process. Defaults to 'localhost'.
• port - Number port of the launched chromedriver process. Defaults to 9515.
• nodePath - String path to a node executable to launch ChromeDriver with. Defaults to process.execPath.
• connectionRetryCount - Number of retry attempts to make when connecting to ChromeDriver. Defaults to 10 attempts.
• connectionRetryTimeout - Number in milliseconds to wait for connections to ChromeDriver to be made. Defaults to 30000 milliseconds.
• quitTimeout - Number in milliseconds to wait for application quitting. Defaults to 1000 milliseconds.
• requireName - Custom property name to use when requiring modules. Defaults to require. This should only be used if your application deletes the main window.require function and assigns it to another property name on window.
• startTimeout - Number in milliseconds to wait for ChromeDriver to start. Defaults to 5000 milliseconds.
• waitTimeout - Number in milliseconds to wait for calls like waitUntilTextExists and waitUntilWindowLoaded to complete. Defaults to 5000 milliseconds.
• debuggerAddress - String address of a Chrome debugger server to connect to.
• chromeDriverLogPath - String path to file to store ChromeDriver logs in. Setting this option enables --verbose logging when starting ChromeDriver.
• webdriverLogPath - String path to a directory where Webdriver will write logs to. Setting this option enables verbose logging from Webdriver.
• webdriverOptions - Object of additional options for Webdriver

Node Integration

The Electron helpers provided by Spectron require accessing the core Electron APIs in the renderer processes of your application. So, either your Electron application has nodeIntegration set to true or you'll need to expose a require window global to Spectron so it can access the core Electron APIs.

You can do this by adding a [preload][preload] script that does the following:

if (process.env.NODE_ENV === 'test') {
  window.electronRequire = require
}

Then create the Spectron Application with the requireName option set to 'electronRequire' and then runs your tests via NODE_ENV=test npm test.

Note: This is only required if your tests are accessing any Electron APIs. You don't need to do this if you are only accessing the helpers on the client property which do not require Node integration.

Properties

client

Spectron uses WebdriverIO and exposes the managed client property on the created Application instances.

The client API is WebdriverIO's browser object. Documentation can be found here.

Several additional commands are provided specific to Electron.

All the commands return a Promise.

So if you wanted to get the text of an element you would do:

const element = await app.client.$('#error-alert')
const errorText = await element.getText()
console.log('The #error-alert text content is ' + errorText)

electron

The electron property is your gateway to accessing the full Electron API.

Each Electron module is exposed as a property on the electron property so you can think of it as an alias for require('electron') from within your app.

So if you wanted to access the clipboard API in your tests you would do:

app.electron.clipboard.writeText('pasta')
const clipboardText = app.electron.clipboard.readText()
console.log