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 browsers or with a remote Selenuium grid provider
such as Saucelabs.

Getting started

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

or

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

In addition to spec/support/jasmine-browser.mjs, jasmine-browser-runner also
supports other config file paths:

* spec/support/jasmine-browser.js
* spec/support/jasmine-browser.json (generated by previous versions of the
init subcommand)
* Any other JavaScript or JSON file, if you use the --config option. This
file can be a JSON file or a javascript file whose default export is a config
object.

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.mjs:

`javascript
export default {
// ...
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.mjs:

`javascript
export default {
// ...
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.

Controlling which network interfaces are listened to

**Note: This behavior differs between 2.x and 3.x. If you are using 2.x, please
consult the README for the version you're using.**

By default, jasmine-browser-runner listens to the network interface that
corresponds to localhost. To listen on a different interface, set listenAddress
to the corresponding hostname or IP address. To listen on all available network
interfaces, set listenAddress to "*". You might need to do that if you're
using a remote grid such as Saucelabs.

`javascript
export default {
// ...
listenAddress: "*",
// ...
}
`

Hostname support

**Note: This behavior differs between 2.x and 3.x. If you are using 2.x, please
consult the README for the version you're using.**

If you need to access your tests via a specific hostname, you can do that by
setting the hostname configuration property:

`javascript
export default {
// ...
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
.mjs? 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 want to load ES module source directly on load instead of loading it from
the corresponding spec, set the modulesWithSideEffectsInSrcFiles config property to true.

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

Import maps
are also supported:

`javascript
export default {
// ...
"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.

$3

1. Run yarn add --dev jasmine-browser-runner jasmine-core.
2. Run npx jasmine-browser-runner init.
3. Edit spec/support/jasmine-browser.mjs as follows:
`
export default {
"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 .

$3

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.
5. Edit spec/support/jasmine-browser.mjs as follows:
`
export default {
"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 .

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:

`javascript
// jasmine-browser.mjs
export default {
// ...
// 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"
}
}
}
}
`
`javascript
// jasmine-browser.mjs
export default {
// ...
// Saucelabs
"browser": {
"name": "safari",
"useRemoteSeleniumGrid": true,
"remoteSeleniumGrid": {
"url": "https://ondemand.saucelabs.com/wd/hub",
"platformName": "macOS 12",
"sauce:options": {
"tunnelName": "the same tunnel name that was provided to Sauce Connect",
"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?

`javascript
// ESM
import path from 'path';
import jasmineBrowser from 'jasmine-browser-runner';
import config from './spec/support/jasmine-browser.mjs';

config.projectBaseDir = path.resolve('some/path');
jasmineBrowser.startServer(config);


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

import('./spec/support/jasmine-browser.mjs')
.then(function({default: config}) {
config.projectBaseDir = path.resolve('some/path');
jasmineBrowser.startServer(config);
});
``

Supported environments

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

| Environment | Supported versions |
|-------------------|----------------------------|
| Node | 20, 22, 24 |
| Safari | 16, 17 |
| Chrome | Evergreen |
| Firefox | Evergreen, 102, 115, 128 |
| 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.

\* Supported on a best-effort basis. Support for these versions may be dropped
if it becomes impractical, and bugs affecting only these versions may not be
treated as release blockers.

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

Copyright (c) 2019 Pivotal Labs

Copyright (c) 2020-2026 The Jasmine developers

This software is licensed under the MIT License.