Spectron [deprecated]

Easily test your Electron apps using WebdriverIO and Chromedriver.

RIP Spectron - long live WDIO

wdio-electron-service has now been released enabling Electron apps to be tested natively in WebdriverIO. I updated this fork to use the new service but this change effectively makes Spectron mostly, if not entirely redundant. Some of the Electron APIs / browser helper functions here may be ported to the new service if/as required, but this fork of Spectron will no longer be updated.

Please try out the new service if you are interested in using modern WebdriverIO and its extensive ecosystem for E2E testing Electron apps. It should be a more than adequate replacement for Spectron, but if anything critical is missing for your use case please let us know.

Modern alternatives to Spectron for Electron E2E testing:

WebdriverIO
Playwright (currently experimental Electron support)
Puppeteer-in-electron

---

Rationale

This fork of Spectron exists to fulfil a simple requirement - bring Spectron in line with modern versions of Electron & WebdriverIO, by any means necessary. The code has been completely rewritten in Typescript with modern dependencies and a much greater WebdriverIO integration.

Installation & Quick Start

Install Spectron using your favourite package manager. You will also need to install WebdriverIO and a framework dependency for whichever framework you want to use, for instance Mocha:

npm install --save-dev @goosewobbler/spectron webdriverio @wdio/mocha-framework

yarn add -D @goosewobbler/spectron webdriverio @wdio/mocha-framework

pnpm i -D @goosewobbler/spectron webdriverio @wdio/mocha-framework

In your main process root (index) file, add the following import:

import '@goosewobbler/spectron/main';

In your preload file, add the following import:

import '@goosewobbler/spectron/preload';

Add a spec file - the following is a basic example in TypeScript using Mocha and Testing Library:

import { initSpectron, SpectronApp } from '@goosewobbler/spectron';
import { setupBrowser, WebdriverIOQueries } from '@testing-library/webdriverio';

let app: SpectronApp;
let screen: WebdriverIOQueries;

describe('App', () => {
  before(async (): Promise<void> => {
    app = await initSpectron();
    await app.client.waitUntilWindowLoaded();
    screen = setupBrowser(app.client);
  });

  it('should launch the app', async () => {
    const isVisible = await app.browserWindow.isVisible();
    expect(isVisible).toBe(true);
  });

  it('should display a button', async () => {
    const button = await screen.getByText('This is a button');
    expect(button).toBeDefined();
  });
});

Running tests with Spectron depends on your app binary so you will need to ensure it is built before the tests are executed.

Next you will need some configuration. Spectron uses the exact same format as the WebdriverIO configuration file for their TestRunner, the only difference is that you won't need to configure Chromedriver in services or anything in the capabilities section as these are handled by Spectron. Here is a sample configuration:

const { join } = require('path');
const fs = require('fs-extra');

const packageJson = JSON.parse(fs.readFileSync('./package.json'));
const {
  build: { productName },
} = packageJson;

const config = {
  spectronOpts: {
    appPath: join(process.cwd(), 'dist'),
    appName: productName,
  },
  port: 9515,
  waitforTimeout: 5000,
  connectionRetryCount: 10,
  connectionRetryTimeout: 30000,
  logLevel: 'debug',
  runner: 'local',
  outputDir: 'wdio-logs',
  specs: ['./test/e2e/*.spec.ts'],
  autoCompileOpts: {
    autoCompile: true,
    tsNodeOpts: {
      transpileOnly: true,
      files: true,
      project: './tsconfig.json',
    },
    tsConfigPathsOpts: {
      baseUrl: './',
    },
  },
  framework: 'mocha',
};

module.exports = { config };

Finally, you can execute your tests by pointing Spectron at your configuration file:

npx spectron ./spectron.conf.js

yarn spectron ./spectron.conf.js

pnpx spectron ./spectron.conf.js

API

API details can be found here.

Architecture

The architecture of Spectron is documented here.

Known Limitations / WIP

Chromedriver is not currently restarted in between tests; this is a consequence of using the wdio-chromedriver-service. Separate worker processes are spawned by WDIO for each spec file, but within a given spec file, test state is likely to bleed into subsequent tests. See the migration doc for more details.

Not all Electron APIs are currently supported.

Some old functionality provided by the Electron remote API (now found here) is not yet fully replicated.

Some Electron API functions may not work due to serialisation errors; this is a consequence of the new way of accessing electron methods from renderer processes, this is by design and can be worked around.

Development

Logging all tasks for development here.
Rewrite Discussion here.

Configuration

Details of how to configure Spectron can be found here.