jasmine-browser-runner

jasmine-browser-runner runs your Jasmine specs in a browser. It's suitable for interactive use with normal browsers as well as running specs in CI builds using either headless Chrome or Saucelabs.

Getting started

npm install --save-dev jasmine-browser-runner jasmine-core
npx jasmine-browser-runner init

or

yarn add -D jasmine-browser-runner jasmine-core
npx jasmine-browser-runner init

If you intend to use ES modules, add --esm to the jasmine-browser-runner init command.

Then, customize spec/support/jasmine-browser.json to suit your needs. You can change the spec files, helpers, and source files that are loaded, specify the Jasmine env's configuration, and more.

You can also use the --config option to specify a different file. This file can be a JSON file or a javascript file that exports a object that looks like the JSON above. More information about the configuration can be found at the runner documentation website.

To start the server so that you can run the specs interactively (particularly useful for debugging):

npx jasmine-browser-runner serve

To run the specs in a browser (defaults to Firefox):

npx jasmine-browser-runner runSpecs

To use a browser other than Firefox, add a browser field to jasmine-browser.json:

{
  // ...
  "browser": "chrome"
}

Its value can be "firefox", "headlessFirefox", "safari", "MicrosoftEdge", "chrome", or "headlessChrome".

TLS support

To serve tests over HTTPS instead of HTTP, supply a path to a TLS cert and key in PEM format in jasmine-browser.json:

{
  // ...
  "tlsKey": "/path/to/tlsKey.pem",
  "tlsCert": "/path/to/tlsCert.pem",
  // ...
}

These can also be specified on the command line with --tlsKey and --tlsCert.

Note that if you are using a self-signed or otherwise invalid certificate, the browser will not allow the connection by default. Additional browser configs or command line options may be necessary to use an invalid TLS certificate.

Hostname support

To serve tests on a specific interface or IP, you can specify a hostname in jasmine-browser.json:

{
  // ...
  "hostname": "mymachine.mynetwork",
  // ...
}

This can also be specified on the command line with --hostname.

There are a few important caveats when doing this:

1. This name must either be an IP or a name that can really be resolved on your system. Otherwise, you will get ENOTFOUND errors.
2. This name must correspond to an IP assigned to one of the network interfaces on your system. Otherwise, you will get EADDRNOTAVAIL errors.
3. If this name matches the HSTS preload list, browsers will force the connection to HTTPS. If you are not using TLS, you will get an error that says The browser tried to speak HTTPS to an HTTP server. Misconfiguration is likely. You may be surprised by the names on that preload list, which include such favorite local network hostnames as:
   • dev
   • foo
   • app
   • nexus
   • windows
   • office
   • dad You can see a full list in Chromium source or query your hostname at the HSTS preload site.

ES module support

If a source, spec, or helper file's name ends in .mjs, it will be loaded as an ES module rather than a regular script. Note that ES modules can only be loaded from other ES modules. So if your source files are ES modules, your spec files need to be ES modules too. Want to use a different extension than .esm? Just set the esmFilenameExtension config property, e.g. "esmFilenameExtension": ".js".

To allow spec files to import source files via relative paths, set the specDir config field to something that's high enough up to include both spec and source files, and set srcFiles to []. You can autogenerate such a configuration by running npx jasmine-browser-runner init --esm.

If you have specs or helper files that use top-level await, set the enableTopLevelAwait config property is set to true.

Import maps are also supported:

{
   // ...
   "importMap": {
     "moduleRootDir": "node_modules", 
     "imports": {
       "some-lib":"some-lib/dist/index.mjs",
       "some-lib/": "some-lib/dist/",
       "some-cdn-lib": "https://example.com/some-cdn-lib"
      }
   }
}

Use with Rails

You can use jasmine-browser-runner to test your Rails application's JavaScript, whether you use the Asset Pipeline or Webpacker.

Webpacker

1. Run yarn add --dev jasmine-browser-runner jasmine-core.
2. Run npx jasmine-browser-runner init.
3. Edit spec/support/jasmine-browser.json as follows:

{
  "srcDir": ".",
  "srcFiles": [],
  "specDir": "public/packs/js",
  "specFiles": [
    "specs-*.js"
  ],
  "helpers": [],
  // ...
}

4. Create app/javascript/packs/specs.js (or app/javascript/packs/specs.jsx if you use JSX) as follows:

(function() {
  'use strict';

  function requireAll(context) {
    context.keys().forEach(context);
  }

  requireAll(require.context('spec/javascript/helpers/', true, /\.js/));
  requireAll(require.context('spec/javascript/', true, /[sS]pec\.js/));
})();

5. Add 'spec/javascript' to the additional_paths array in config/webpacker.yml.
6. Put your spec files in spec/javascript.

To run the specs:

1. Run bin/webpack --watch.
2. Run npx jasmine-browser-runner.
3. visit http://localhost:8888.

Asset Pipeline

1. Run yarn init if there isn't already package.json file in the root of the Rails application.
2. Run yarn add --dev jasmine-browser-runner.
3. Run npx jasmine-browser-runner init.
4. Edit spec/support/jasmine-browser.json as follows:

{
  "srcDir": "public/assets",
  "srcFiles": [
    "application-*.js"
  ],
  "specDir": "spec/javascript",
  "specFiles": [
    "**/*[sS]pec.?(m)js"
  ],
  "helpers": [
    "helpers/**/*.?(m)js"
  ],
  // ...
}

6. Put your spec files in spec/javascript.

To run the specs:

1. Either run bundle exec rake assets:precompile or start the Rails application in an environment that's configured to precompile assets.
2. Run npx jasmine-browser-runner.
3. Visit http://localhost:8888.

Remote Grid support (Saucelabs, BrowserStack, etc.)

jasmine-browser-runner can run your Jasmine specs on a remote grid provider like Saucelabs, BrowserStack or your own Selenium Grid. To use a remote grid hub, set the browser object in your config file as follows:

// jasmine-browser.json
{
  // ...
  // BrowserStack
  "browser": {
    "name": "safari",
    "useRemoteSeleniumGrid": true,
    "remoteSeleniumGrid": {
      "url": "https://hub-cloud.browserstack.com/wd/hub",
      "bstack:options": {
        "browserVersion": "16",
        "os": "OS X",
        "osVersion": "Monterey",
        "local": "true",
        "localIdentifier": "tunnel ID",
        "debug": "true",
        "userName": "your BrowserStack username",
        "accessKey": "your BrowserStack access key"
      }
    }
  }
}

// jasmine-browser.json
{
  // ...
  // Saucelabs
  "browser": {
    "name": "safari",
    "useRemoteSeleniumGrid": true,
    "remoteSeleniumGrid": {
      "url": "https://ondemand.saucelabs.com/wd/hub",
      "platformName": "macOS 12",
      "sauce:options": {
        "tunnel-identifier": "tunnel ID",
        "userName": "your Saucelabs username",
        "accessKey": "your Saucelabs access key"
      }
    }
  }
}

When using a remote grid provider, all properties of the browser object are optional except for name which will be passed as the browserName capability, and useRemoteSeleniumGrid which must be set to a value of true. if a remoteSeleniumGrid object is included, any values it contains, with the exception of the url will be used as capabilties sent to the grid hub url. if no value is specified for the url then a default of http://localhost:4445/wd/hub is used.

It's common for remote grids to support only a limited set of ports. Check your remote grid's documentation to make sure that the port you're using is supported. When using a remote grid, jasmine-browser-runner will run on port 5555 unless you use the --port command line option or specify a port in the second parameter tostartServer.

Want more control?

const path = require('path');
const jasmineBrowser = require('jasmine-browser-runner');

const config = require(path.resolve('spec/support/jasmine-browser.json'));
config.projectBaseDir = path.resolve('some/path');

jasmineBrowser.startServer(config, { port: 4321 });

Supported environments

jasmine-browser-runner tests itself across popular browsers (Safari, Chrome, Firefox, and Microsoft Edge) as well as Node.

Environment	Supported versions
Node	18, 20
Safari	15-17
Chrome	Evergreen
Firefox	Evergreen, 102, 115
Edge	Evergreen

For evergreen browsers, each version of jasmine-browser-runner is tested against the version of the browser that is available to us at the time of release. Other browsers, as well as older & newer versions of some supported browsers, are likely to work. However, jasmine-browser-runner isn't tested against them and they aren't actively supported.

To find out what environments work with a particular Jasmine release, see the release notes.

Copyright (c) 2019 Pivotal Labs
Copyright (c) 2020-2024 The Jasmine developers
This software is licensed under the MIT License.