karma-docker-launcher

A Karma plugin. Launcher for headless browsers in Docker containers.

Why?

When running tests in e.g. ChromeHeadless, you need a locally installed Chrome binary and the environment variable CHROME_BIN pointing to its location. It is more convenient to run your headless browsers in a Docker container, especially during automated builds. This package allows you to do just that.

This package uses the Docker Engine API, so it can even run without Docker binary, which is useful when Karma itself is running inside a node container. It is easily configurable for testing in Chrome, Firefox or any other browser that runs inside a Docker container.

Run your Karma tests on a headless browser in a Docker container.

Installation

The easiest way is to keep karma-docker-launcher as a devDependency in your package.json.

You can simple do it by:

npm install karma-docker-launcher --save-dev

Configuration

// karma.conf.js
module.exports = function (config) {
  config.set({
    browsers: ['ChromeHeadlessDocker', 'FirefoxHeadlessDocker'],
    customLaunchers: {
      ChromeHeadlessDocker: {
        base: 'Docker',   
        modemOptions: {
          socketPath: '/var/run/docker.sock'
        },
        createOptions: {
          Image: 'alpeware/chrome-headless-trunk',
          Env: ['CHROME_OPTS=$KARMA_URL'],
          HostConfig: {
            NetworkMode: 'host'
          }
        }
      },
      FirefoxHeadlessDocker: {
        base: 'Docker',
        modemOptions: {
          socketPath: '/var/run/docker.sock'
        },
        createOptions: {
          Image: 'rkuzsma/firefox-headless-stable:latest',
          Cmd: ['firefox', '-p', 'headless', '-headless', '-no-remote', '-url', '$KARMA_URL'],
          HostConfig: {
            NetworkMode: 'host'
          }
        }
      }
    }                 
   });
};

• Each image you want to run has to be configured in customLaunchers, where base is Docker.

• modemOptions is specified by the docker-modem package. Please refer to its REAMDE.md to see the available options. Most applications only need socketPath: '/var/run/docker.sock'.

• createOptions is specified by de Docker Engine API. Only Image is required. Refer to the official Docker docs to see all available options. Please mind the capitalisation of the keys.

• All occurrences of $KARMA_URL will be replaced by the actual url provided by Karma; typically http://localhost:9876/?id=1234.

Running Karma

Running Karma can be done in two ways:

1. Directly, e.g. using npm run test.

2. In a Docker container, e.g. using docker run (...) node npm run test.

Examples

See the example application in the examples folder. Most notably are the configuration file karma.conf.js and the scripts in the scripts folder.

Alternatives

This package differs from karma-chrome-launcher and karma-firefox-launcher in one important way. The Chrome and Firefox launchers need the binaries to be installed locally, whereas this package only needs a Docker daemon to talk to.

This package is inspired by @rkuzsma/karma-docker-launcher but works essentially differently. Because this package manages the containers via the Docker Engine rather than the Docker CLI, it is possible to run Karma itself in a Docker.

For more information on Karma see the homepage.