Got Scripts? Test’em!

Testem is a JavaScript test runner that runs your tests in real desktop browsers—Chrome, Firefox, Safari, Edge, and others you launch—so your specs execute in the same browser engines and DOM your users get, not a pretend environment. It also runs tests in Node, Chrome (including headless runs via browser_args, e.g. --headless), or any launcher you configure. It is framework-agnostic and aimed at any kind of tests you want to run: unit, integration, end-to-end style suites, or custom setups—you pick the style; Testem wires it to the browser or process.

Unit testing in JavaScript can be tedious and painful, but Testem makes it so easy that you will actually want to write tests.

Features

• Test-framework agnostic — designed for any kind of tests that fit your project (unit, integration, custom runners, etc.), not a single prescribed style. Support for
  • Jasmine
  • QUnit
  • Mocha
  • Others, through custom test framework adapters.
• Run tests in all major real browsers (your tests load and run in the actual browser) as well as Node and Chrome (use browser_args with --headless for headless runs—see docs/browser_args.md)
• Two distinct use-cases:
  • Test-Driven-Development(TDD) — designed to streamline the TDD workflow
  • Continuous Integration(CI) — designed to work well with GitHub Actions and other CI systems, including Jenkins and TeamCity
• Cross-platform support
  • macOS
  • Windows
  • Linux
• Preprocessor support
  • Babel
  • TypeScript
  • Browserify
  • ESLint/JSHint/JSLint
  • CoffeeScript
  • everything else

Installation

Testem needs a supported Node.js runtime. The required range is defined in package.json under engines (currently ^22.17.0, ^24.0.0, or >= 26.0.0).

Recommended: install Testem both as a dev dependency (so your project pins a version) and globally (so the testem command is always available on your PATH):

npm install testem --save-dev
npm install testem -g

When you run the global testem inside a project directory that has a local testem install, the CLI automatically re-runs the local copy so the version stays in sync with package.json. Set TESTEM_USE_GLOBAL=1 if you ever need to force the global binary only.

This README uses the testem command in examples; add it to npm scripts or invoke it as testem from a shell after the installs above.

Programmatic use

Testem's package is an ES module. Both of these return the same Api class:

import Api from 'testem';

const api = new Api();
api.startCI({ launch: 'Headless Chrome' });

const Api = require('testem');

const api = new Api();
api.startDev();

startDev, startCI, and startServer match the CLI modes. require('testem') stays synchronous. Deep paths such as testem/lib/config.js are not part of the package exports.

Usage

As stated before, Testem supports two use cases: test-driven-development and continuous integration. Let's go over each one.

Development Mode

The simplest way to use Testem, in the TDD spirit, is to start in an empty directory, install a test framework, and run the command

npm install --save-dev jasmine-core@^7
testem

The default runner uses modern Jasmine (jasmine-core). You can also use mocha, qunit, or mocha + chai by setting "framework" in testem.json and installing the matching packages (see Browser framework dependencies).

You will see a terminal-based interface which looks like this

Now open a real browser (the URL Testem prints is a normal page in Chrome, Firefox, Safari, etc.) and go to the specified URL. You should now see

We see 0/0 for tests because at this point we haven't written any code. As we write them, Testem will pick up any .js files that were added, include them, and if there are tests, run them automatically. So let's first write hello_spec.js in the spirit of "test first" (written in Jasmine)

describe('hello', function(){
  it('should say hello', function(){
    expect(hello()).toBe('hello world');
  });
});

Save that file and now you should see

Testem should automatically pick up the new files you've added and also any changes that you make to them and rerun the tests. The test fails as we'd expect. Now we implement the spec like so in hello.js

function hello(){
  return "hello world";
}

So you should now see

Using the Text User Interface

In development mode, Testem has a text-based graphical user interface which uses keyboard-based controls. Here is a list of the control keys

This is the beginning of the README. Read the rest at the original. Read the full README ↗