spectron

library0.4.8jsnpmunverified

Spectron is an end-to-end testing framework designed specifically for Electron applications. It leverages ChromeDriver and WebdriverIO to provide an API for interacting with Electron apps, allowing developers to simulate user interactions and assert application state. The current stable version is 19.0.0. However, Spectron was officially deprecated on February 1, 2022, and is no longer actively maintained. Its primary differentiator was its tight integration with Electron, allowing control over both the Electron main process and renderer processes through WebdriverIO. Due to its deprecated status, new projects are advised to seek alternative testing solutions for Electron.

testing

npm install spectron

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SPECTRON

spectron

testingjavascriptv0.4.8

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Application

✓ import { Application } from 'spectron'

✗ const { Application } = require('spectron')

While the README shows CommonJS, Spectron v10+ ships with TypeScript types, implying modern usage should prefer ESM imports. Note that given its deprecated status, it might not be fully ESM-compatible in all contexts.

Application (CJS)

✓ const { Application } = require('spectron')

This is the pattern shown in the official README examples. Use for older Node.js projects or if encountering issues with ESM imports.

electronPath

✓ import electronPath from 'electron'

✗ const electronPath = require('electron')

The quickstart uses `require('electron')` to get the Electron binary path. For ESM, direct import or `import { createRequire } from 'module'; const require = createRequire(import.meta.url); const electronPath = require('electron');` might be needed depending on context.

This quickstart demonstrates how to set up Spectron with Mocha to launch an Electron application, perform basic assertions on window visibility and title, and simulate user interaction like clicking a button.

import { Application } from 'spectron' import assert from 'assert' import electronPath from 'electron' // Require Electron from the binaries included in node_modules. import path from 'path' describe('Application launch', function () { this.timeout(10000) beforeEach(async function () { this.app = new Application({ path: electronPath, 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 () { // Example assertion: check if the main window is visible const isVisible = await this.app.browserWindow.isVisible() assert.strictEqual(isVisible, true, 'Initial window should be visible') // Example assertion: check window title const title = await this.app.client.getTitle() assert.strictEqual(title, 'Your Electron App Title', 'Window title should match') }) it('should have a button and click it', async function() { const button = await this.app.client.$('#my-button') await button.click() const text = await this.app.client.$('#status-text').getText() assert.strictEqual(text, 'Button clicked!', 'Status text should update after click') }) })

Debug

Known issues

breakingSpectron was officially deprecated on February 1, 2022. It is no longer actively maintained by the Electron team, meaning no new features, bug fixes, or security patches will be released. Existing applications should consider migrating to alternative testing solutions.

fix

Migrate to alternative Electron testing frameworks such as Playwright or WebdriverIO directly with a custom setup for Electron, or consider using Electron's built-in APIs for testing.

affects: >=19.0.0

breakingSpectron has strict version compatibility requirements with Electron. Using mismatched versions can lead to application launch failures or unexpected test behavior.

fix

Always consult the 'Version Map' in the Spectron documentation (or README) to ensure your Spectron version is compatible with your Electron version. For example, Electron v17.0.0 requires Spectron v19.0.0.

affects: All versions

breakingUpgrading from Spectron 1.x to 2.x/3.x introduced significant breaking changes, requiring review of the changelog for migration steps.

fix

Refer to the Spectron changelog for specific breaking changes and migration instructions when upgrading from Spectron 1.x.

affects: ^2.0.0, ^3.0.0

gotchaSpectron relies on `chromedriver` and `webdriverio`. Configuration issues with these underlying tools can manifest as Spectron errors. Ensure `chromedriver` is compatible with your Electron version's Chromium and that `webdriverio` configurations are correct.

fix

Consult `webdriverio` and `chromedriver` documentation for troubleshooting, especially regarding versions and capabilities. Ensure Electron's `main.js` and `package.json` are correctly referenced in the `Application` constructor's `args`.

affects: All versions

Errors

Common errors & fixes

Error: `app.start()` failed: `path` must be a string

The `path` option in the `Application` constructor is not correctly pointing to your Electron binary.

fix

Ensure `path: electronPath` correctly resolves to the Electron executable. If using `require('electron')`, ensure `electron` is installed as a dependency. For packaged apps, specify the absolute path to the main executable.

Error: `app.start()` failed: spectron failed to start the application

This generic error often indicates an issue with how Spectron is trying to launch your Electron app, such as incorrect `args` pointing to the main Electron script or a problem within your Electron app's startup.

fix

Verify the `args` array in the `Application` constructor correctly points to your main Electron script (e.g., `path.join(__dirname, '..')`). Check your Electron app's `main.js` for any startup errors. Also, ensure Spectron and Electron versions are compatible according to the 'Version Map'.

TypeError: Cannot read properties of undefined (reading 'isVisible')

This typically occurs when trying to access `this.app.browserWindow` or `this.app.client` before the application has successfully started, or if `this.app` is `undefined`.

fix

Ensure `await this.app.start()` completes successfully before attempting to interact with `this.app.browserWindow` or `this.app.client`. Also, check that `this.app` is properly initialized in your `beforeEach` hook.

Upgrade

Version history

0.4.8latest on npm

Audit

Dependencies

electronrequiredRequired to launch the Electron application under test. Spectron has a strict version compatibility mapping with Electron versions.

mochaoptionalCommonly used testing framework shown in examples, though Spectron supports any framework.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/electron/spectron ↗

packagehttps://www.npmjs.com/package/spectron ↗

homepagehttps://www.electronjs.org/spectron ↗