Spectron

Common errors

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

  cause 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

  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.
  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')

  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`.
  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.

Warnings

• breaking 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.
  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.
• breaking Spectron 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.
• breaking Upgrading 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.
• gotcha 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.
  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`.

Install

• npm install spectron npm
• yarn add spectron yarn
• pnpm add spectron pnpm

Imports

• Application
  wrong:

  const { Application } = require('spectron')

  correct:

  import { Application } from '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
  wrong:

  const electronPath = require('electron')

  correct:

  import electronPath from '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.

Quickstart

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')
  })
})