{"id":15836,"library":"spectron","title":"Spectron","description":"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.","status":"deprecated","version":"19.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/electron/spectron","tags":["javascript","electron","chromedriver","webdriverio","selenium","typescript"],"install":[{"cmd":"npm install spectron","lang":"bash","label":"npm"},{"cmd":"yarn add spectron","lang":"bash","label":"yarn"},{"cmd":"pnpm add spectron","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required to launch the Electron application under test. Spectron has a strict version compatibility mapping with Electron versions.","package":"electron","optional":false},{"reason":"Commonly used testing framework shown in examples, though Spectron supports any framework.","package":"mocha","optional":true}],"imports":[{"note":"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.","wrong":"const { Application } = require('spectron')","symbol":"Application","correct":"import { Application } from 'spectron'"},{"note":"This is the pattern shown in the official README examples. Use for older Node.js projects or if encountering issues with ESM imports.","symbol":"Application (CJS)","correct":"const { Application } = require('spectron')"},{"note":"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.","wrong":"const electronPath = require('electron')","symbol":"electronPath","correct":"import electronPath from 'electron'"}],"quickstart":{"code":"import { Application } from 'spectron'\nimport assert from 'assert'\nimport electronPath from 'electron' // Require Electron from the binaries included in node_modules.\nimport path from 'path'\n\ndescribe('Application launch', function () {\n  this.timeout(10000)\n\n  beforeEach(async function () {\n    this.app = new Application({\n      path: electronPath,\n      args: [path.join(__dirname, '..')]\n    })\n    await this.app.start()\n  })\n\n  afterEach(async function () {\n    if (this.app && this.app.isRunning()) {\n      await this.app.stop()\n    }\n  })\n\n  it('shows an initial window', async function () {\n    // Example assertion: check if the main window is visible\n    const isVisible = await this.app.browserWindow.isVisible()\n    assert.strictEqual(isVisible, true, 'Initial window should be visible')\n\n    // Example assertion: check window title\n    const title = await this.app.client.getTitle()\n    assert.strictEqual(title, 'Your Electron App Title', 'Window title should match')\n  })\n\n  it('should have a button and click it', async function() {\n    const button = await this.app.client.$('#my-button')\n    await button.click()\n    const text = await this.app.client.$('#status-text').getText()\n    assert.strictEqual(text, 'Button clicked!', 'Status text should update after click')\n  })\n})","lang":"javascript","description":"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."},"warnings":[{"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.","message":"Spectron 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.","severity":"breaking","affected_versions":">=19.0.0"},{"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.","message":"Spectron has strict version compatibility requirements with Electron. Using mismatched versions can lead to application launch failures or unexpected test behavior.","severity":"breaking","affected_versions":"All versions"},{"fix":"Refer to the Spectron changelog for specific breaking changes and migration instructions when upgrading from Spectron 1.x.","message":"Upgrading from Spectron 1.x to 2.x/3.x introduced significant breaking changes, requiring review of the changelog for migration steps.","severity":"breaking","affected_versions":"^2.0.0, ^3.0.0"},{"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`.","message":"Spectron 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"The `path` option in the `Application` constructor is not correctly pointing to your Electron binary.","error":"Error: `app.start()` failed: `path` must be a string"},{"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'.","cause":"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.","error":"Error: `app.start()` failed: spectron failed to start the application"},{"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.","cause":"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`.","error":"TypeError: Cannot read properties of undefined (reading 'isVisible')"}],"ecosystem":"npm"}