Testem JavaScript Test Runner

3.20.0 · active · verified Sun Apr 19

Testem is a robust, framework-agnostic JavaScript test runner designed to execute unit, integration, and end-to-end tests across various real desktop browsers (such as Chrome, Firefox, Safari, and Edge) and Node.js environments. It supports popular testing frameworks like Jasmine, QUnit, and Mocha, and offers extensibility for custom test adapters, making it suitable for a wide range of project needs. Currently at version `3.20.0`, Testem is actively maintained with a regular release cadence, featuring recent updates like the switch to `chokidar` for more reliable file watching and dropping support for older Node.js versions. Its key differentiators include running tests directly in actual browser engines for accurate user environment simulation and streamlined workflows for both Test-Driven Development (TDD) and Continuous Integration (CI).

Common errors

```
Error: Testem requires Node.js version 20.x, 22.x, or 24.x or higher.
```
cause Running Testem on an unsupported Node.js version (e.g., Node 18).

fix Upgrade your Node.js installation to version 20.19.0, 22.12.0, 24.0.0, or later.
```
Testem is not detecting file changes and not re-running tests automatically.
```
cause The new `chokidar` file watcher might be missing events in your environment, especially on network drives or with certain OS configurations.

fix Run Testem with the `CHOKIDAR_USE_POLLING=1` environment variable, e.g., `CHOKIDAR_USE_POLLING=1 npx testem`.
```
SyntaxError: Cannot use import statement outside a module (when using testem.js)
```
cause Your project's `package.json` specifies `"type": "module"` (ESM), but `testem.js` is a CommonJS module and Testem loads it as such. An `import` statement in `testem.js` will cause this error.

fix For ESM projects, rename your configuration file to `testem.cjs` and ensure it uses CommonJS `require()` and `module.exports` syntax. Alternatively, if keeping `testem.js`, ensure it is pure CommonJS.

Warnings

breaking Testem dropped support for Node.js versions older than 20. Users running on Node.js < 20 will encounter errors.
Fix: Upgrade Node.js to a supported version (20.19.0, 22.12.0, or 24.0.0+).
gotcha In `v3.20.0`, Testem switched from `fireworm` to `chokidar` for file watching. While this resolves some long-standing issues, there's a risk of missed change events in certain environments.
Fix: If you observe missed change events, try setting the environment variable `CHOKIDAR_USE_POLLING=1` before running Testem (e.g., `CHOKIDAR_USE_POLLING=1 npx testem`).
deprecated Internet Explorer and PhantomJS are now documented as deprecated test targets. While still supported, maintaining compatibility through transpilation and polyfills is expected to become more difficult over time.
Fix: For new projects, prefer evergreen browsers (Chrome, Firefox, Safari, Edge) or Node.js for testing. Migrate existing tests away from IE and PhantomJS where possible.
breaking Testem replaced `browserify` with `esbuild` for internal bundling in `v3.19.1`. While primarily an internal change, projects with highly customized configurations that implicitly relied on `browserify`'s specific behaviors might experience unexpected issues.
Fix: Review custom build steps or configurations if you encounter new bundling-related errors after upgrading. Ensure your setup is compatible with `esbuild`'s bundling characteristics.

Install

npm install testem npm
yarn add testem yarn
pnpm add testem pnpm

Imports

testem (CLI)
wrong:
```
import testem from 'testem';
```
correct:
```
npx testem
```
Testem is primarily a command-line interface tool. It is typically invoked directly from the terminal or via `npm run` scripts. `npx testem` ensures you run the locally installed version.
testem.js / testem.cjs (Configuration)
```
// project-root/testem.js
module.exports = { /* ... */ };
```
Testem automatically loads `testem.js` or `testem.cjs` from the project root for configuration. Since `v3.16.0`, `testem.cjs` is supported for use in `type="module"` (ESM) Node.js projects, allowing CommonJS configuration in an ESM context.
Programmatic API
wrong:
```
import testem from 'testem';
```
correct:
```
const testem = require('testem');
```
While not the primary use case, Testem can be `require()`d for advanced programmatic integration, such as within custom launcher scripts or specialized CI environments. It typically expects CommonJS for this usage.

Quickstart

This quickstart demonstrates how to set up Testem with Mocha and Chai, including a basic `testem.js` configuration to run tests in a headless Chrome browser. It shows the `package.json` script for easy execution.

{
  "name": "my-testem-project",
  "version": "1.0.0",
  "description": "Basic Testem setup",
  "main": "index.js",
  "scripts": {
    "test": "npx testem"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "chai": "^5.0.0",
    "mocha": "^11.0.0",
    "testem": "^3.20.0"
  }
}

// testem.js
module.exports = {
  "framework": "mocha",
  "src_files": [
    "test/**/*.js"
  ],
  "launchers": {
    "HeadlessChrome": {
      "command": "google-chrome --headless --disable-gpu --remote-debugging-port=9222",
      "protocol": "browser"
    }
  },
  "launch_in_ci": [
    "HeadlessChrome"
  ],
  "launch_in_dev": [
    "HeadlessChrome",
    "Firefox"
  ]
};

// test/example.test.js
const { expect } = require('chai');

describe('Array', function() {
  it('should return -1 when the value is not present', function() {
    expect([1, 2, 3].indexOf(4)).to.equal(-1);
  });

  it('should return the correct index when present', function() {
    expect([1, 2, 3].indexOf(2)).to.equal(1);
  });
});

view raw JSON →