testem

library3.20.0jsnpmunverified

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).

testing

npm install testem

github ↗package ↗

INSTALL

IMPORT

SIG · TESTEM

testem

testingjavascriptv3.20.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

testem (CLI)

✓ npx testem

✗ import testem from '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

✓ const testem = require('testem');

✗ import testem from '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.

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); }); });

testem --version

Debug

Known issues

breakingTestem 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+).

affects: >=3.18.0

gotchaIn `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`).

affects: >=3.20.0

deprecatedInternet 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.

affects: >=3.14.0

breakingTestem 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.

affects: >=3.19.1

Errors

Common errors & fixes

Error: Testem requires Node.js version 20.x, 22.x, or 24.x or higher.

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.

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)

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.

Upgrade

Version history

3.20.0latest on npm

Audit

Dependencies

chokidarrequiredInternal dependency for watching file changes, replaced 'fireworm' in v3.20.0. Potential for missed events in certain environments.

Node.jsrequiredRuntime environment. Testem requires Node.js version `>=20.19.0 || ^22.12.0 || >=24.0.0` as of v3.18.0.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/testem/testem ↗

packagehttps://www.npmjs.com/package/testem ↗