karma-electron

    7.0.0 • Public • Published

    karma-electron Build status Build status

    Karma launcher and preprocessor for Electron

    This was written to allow for directly testing in Electron where we might want require to work automatically

    Features:

    • Tested via CI on Linux and Windows
    • Support for Node.js integration in the renderer process (e.g. node_modules, __filename, relative paths for require)
    • Support for hidden browser windows
    • Support for isolated test runs to prevent cookie/localStorage pollution

    Requirements:

    Notices:

    Breaking changes with Electron@12

    contextIsolation has been set to true by default, which limits interaction with require and postMessage

    To resolve these issues, please see the latest Getting Started instructions

    For more information, see https://github.com/twolfson/karma-electron/issues/50

    Breaking changes in 5.0.0

    We have corrected inaccuracies with file:// behavior from Electron. For example:

    • __filename is now Karma's context.html
    • Relative paths for require resolve from Karma's context.html directory

    We have transferred support for this to the option client.loadScriptsViaRequire which loads scripts via require and has the original expected Node.js behavior

    For more information, see https://github.com/twolfson/karma-electron/issues/11

    Getting Started

    On a project that has been set up with karma init already, install the module via:

    # Install our module and `electron`
    npm install karma-electron electron

    Then, configure the module with the following:

    No Node.js integration

    Note: Due to electron@12 postMessage limitations, we set BrowserWindow#webPreferences.nativeWindowOpen to true by default (see #50 for more info)

    // Inside `karma.conf.js`
    browsers: ['Electron']
    
    // DEV: `useIframe: false` is for launching a new window instead of using an iframe
    //   In Electron, iframes don't get `nodeIntegration` priveleges yet windows do
    client: {
      useIframe: false
    }

    Then, we can run Karma:

    karma start

    Node.js/custom integration

    By default, we try to use the minimal Electron configuration to avoid any assumptions about your repo

    As a result, we need to define a custom launcher to match your Electron configuration

    To add Node.js integration support (e.g. require), use the following:

    // Inside `karma.conf.js`
    // Define our custom launcher for Node.js support
    customLaunchers: {
      CustomElectron: {
        base: 'Electron',
        browserWindowOptions: {
          // DEV: More preferentially, should link your own `webPreferences` from your Electron app instead
          webPreferences: {
            // Preferred `preload` mechanism to expose `require`
            preload: __dirname + '/path/to/preload.js'
    
            // Alternative non-preload mechanism to expose `require`
            // nodeIntegration: true,
            // contextIsolation: false
    
            // nativeWindowOpen is set to `true` by default by `karma-electron` as well, see #50
          }
        }
      }
    }
    
    // Use our custom launcher
    browsers: ['CustomElectron']
    
    // DEV: preprocessors is for backfilling `__filename` and local `require` paths
    preprocessors: {
      '**/*.js': ['electron']
    },
    
    // DEV: `useIframe: false` is for launching a new window instead of using an iframe
    //   In Electron, iframes don't get `nodeIntegration` priveleges yet windows do
    client: {
      useIframe: false
    }

    Then, we can run Karma:

    karma start

    Documentation

    Environment variables

    • ELECTRON_BIN - Override path to use for electron
      • By default, we will use path given by electron

    Example:

    ELECTRON_BIN=/usr/bin/electron karma start

    Script configuration

    We support the following configurations:

    • client Object - Container for configuring child windows loaded from Karma
      • __filenameOverride String - Override __filename to be another path (e.g. /path/to/my-index.html)
        • This will also affect __dirname and module.filename as those are derived from __filename
        • By default, __filename will point to Karma's context.html
      • loadScriptsViaRequire Boolean - Load scripts via require instead of <script src=
        • This sets __filename, __dirname, and module to match the script instead of Karma's context.html
        • By default, this is false and we directly load the original scripts content

    Example:

    // Inside `karma.conf.js`
    module.exports = function (config) {
      config.set({
        client: {
          // DEV: These 2 options aren't typically used together
          //   This is for demonstration purposes
    
          // Override top level `__filename` to be `/home/.../my-electron-app/index.html`
          //   where `__dirname` is `/home/.../my-electron-app`
          __filenameOverride: __dirname + '/index.html',
    
          // Use `require` instead of `<script src=` to load scripts
          loadScriptsViaRequire: true
        }
      });
    };

    Launcher configuration

    We support configuration via Karma's custom launcher inheritance:

    • flags Array - List of Chromium flags to alter Electron's behavior
    • userDataDir String - Directory to store cookies/localStorage information
      • By default, this is a random directory generated by Karma (e.g. /tmp/karma-5355024)
    • require String - Path to a main Electron process file to require before calling app.on('ready')
    • browserWindowOptions Object - Parameters to pass to new BrowserWindow
      • This will be serialized to JSON so any functions or other live data will be lost
    • loadURLOptions Object - Parameters to pass to BrowserWindow.loadURL
      • This will be serialized to JSON so any functions or other live data will be lost

    Example:

    // Inside `karma.conf.js`
    module.exports = function (config) {
      config.set({
        // Specify usage of our custom launcher
        browsers: ['CustomElectron'],
    
        // Define a custom launcher which inherits from `Electron`
        customLaunchers: {
          CustomElectron: {
            base: 'Electron',
            userDataDir: __dirname + '/.electron',
            browserWindowOptions: {
              show: true
              // nativeWindowOpen is set to `true` by default by `karma-electron` as well, see #50
            },
            require: __dirname + '/main-fixtures.js'
          }
        }
      });
    };

    Contributing

    In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint via npm run lint and test via npm test.

    Donating

    Support this project and others by twolfson via donations.

    http://twolfson.com/support-me

    Unlicense

    As of Mar 03 2016, Todd Wolfson has released this repository and its contents to the public domain.

    It has been released under the UNLICENSE.

    Install

    npm i karma-electron

    DownloadsWeekly Downloads

    9,573

    Version

    7.0.0

    License

    Unlicense

    Unpacked Size

    68.3 kB

    Total Files

    39

    Last publish

    Collaborators

    • avatar