Testem is a test runner for JavaScript that works with various testing frameworks and libraries. It is designed to be simple to set up and use, and it supports running tests in multiple browsers and environments.
Running Tests
Testem can run tests in continuous integration mode using the 'ci' command. This is useful for automated testing in CI/CD pipelines.
testem ciConfiguration
Testem allows you to configure your test setup using a configuration file. This JSON example configures Testem to use QUnit as the testing framework, specifies source and test files, and sets up browsers for development and CI environments.
{
"framework": "qunit",
"src_files": [
"src/**/*.js",
"tests/**/*.js"
],
"launch_in_dev": [
"Chrome"
],
"launch_in_ci": [
"PhantomJS"
]
}Browser Launchers
Testem can list all available browser launchers using the 'launchers' command. This helps in identifying which browsers are available for running tests.
testem launchersTest Reporting
Testem supports various reporters for test results. This example shows how to configure Testem to use the TAP (Test Anything Protocol) reporter.
{
"reporter": "tap"
}Karma is a test runner developed by the AngularJS team. It is highly configurable and integrates well with various testing frameworks and preprocessors. Compared to Testem, Karma offers more flexibility and is often preferred for complex testing setups.
Jest is a testing framework developed by Facebook, primarily for React applications. It includes a test runner, assertion library, and mocking capabilities. Jest is known for its ease of use and powerful features, making it a popular choice for modern JavaScript applications.
Mocha is a feature-rich JavaScript test framework running on Node.js and in the browser. It makes asynchronous testing simple and supports various assertion libraries. Mocha is often used in combination with other tools like Chai for assertions and Sinon for mocking.
Unit testing in Javascript can be tedious and painful, but Testem makes it so easy that you will actually want to write tests.
You need Node version 0.10+ or iojs installed on your system. Node is extremely easy to install and has a small footprint, and is really awesome otherwise too, so just do it.
Once you have Node installed:
npm install testem -g
This will install the testem executable globally on your system.
As stated before, Testem supports two use cases: test-driven-development and continuous integration. Let's go over each one.
The simplest way to use Testem, in the TDD spirit, is to start in an empty directory and run the command
testem
You will see a terminal-based interface which looks like this
Now open your browser 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
In development mode, Testem has a text-based graphical user interface which uses keyboard-based controls. Here is a list of the control keys
To see all command line options
testem --help
To use Testem for continuous integration
testem ci
In CI mode, Testem runs your tests on all the browsers that are available on the system one after another.
You can run multiple browsers in parallel in CI mode by specifying the --parallel (or -P) option to be the number of concurrent running browsers.
testem ci -P 5 # run 5 browser in parallel
To find out what browsers are currently available - those that Testem knows about and can make use of
testem launchers
Will print them out. The output might look like
$ testem launchers
Browsers available on this system:
IE7
IE8
IE9
Chrome
Firefox
Safari
Safari Technology Preview
Opera
PhantomJS
Did you notice that this system has IE versions 7-9? Yes, actually it has only IE9 installed, but Testem uses IE's compatibility mode feature to emulate IE 7 and 8.
When you run testem ci to run tests, it outputs the results in the TAP format by default, which looks like
ok 1 Chrome 16.0 - hello should say hello.
1..1
# tests 1
# pass 1
# ok
TAP is a human-readable and language-agnostic test result format. TAP plugins exist for popular CI servers
By default, the TAP reporter outputs all test results to the console, whether pass or fail. You can disable this behavior in order to make it easier to see which tests fail (i.e. only output failing tests) using:
{
"tap_failed_tests_only": true
}
By default, the TAP reporter outputs console logs (distinct from pass/fail information) from all tests that emit logs to the console. You can disable this behavior and only emit logs for failed tests using:
{
"tap_quiet_logs": true
}
For improved ergonomics, TAP reporter does not actually strictly adhere to the SPEC by default, reporting 'skip' as a possible status instead of as a directive. To strictly follow the spec use:
{
"tap_strict_spec_compliance": true
}
By default, the TAP reporter outputs the result of JSON.stringify() for any log content that is not a String. You can override this behavior by specifying a function for tap_log_processor.
{
"tap_log_processor": function(log) { return log.toString(); }
}
Testem has other test reporters besides TAP: dot, xunit and teamcity. You can use the -R to specify them
testem ci -R dot
You can also add your own reporter.
Note that the real output is not pretty printed.
<testsuite name="Testem Tests" tests="4" failures="1" timestamp="Wed Apr 01 2015 11:56:20 GMT+0100 (GMT Daylight Time)" time="9">
<testcase classname="PhantomJS 1.9" name="myFunc returns true when input is valid" time="0"/>
<testcase classname="PhantomJS 1.9" name="myFunc returns false when user tickles it" time="0"/>
<testcase classname="Chrome" name="myFunc returns true when input is valid" time="0"/>
<testcase classname="Chrome" name="myFunc returns false when user tickles it" time="0">
<failure name="myFunc returns false when user tickles it" message="function is not ticklish">
<![CDATA[
Callstack...
]]>
</failure>
</testcase>
</testsuite>
##teamcity[testStarted name='PhantomJS 1.9 - hello should say hello']
##teamcity[testFinished name='PhantomJS 1.9 - hello should say hello']
##teamcity[testStarted name='PhantomJS 1.9 - hello should say hello to person']
##teamcity[testFinished name='PhantomJS 1.9 - hello should say hello to person']
##teamcity[testStarted name='PhantomJS 1.9 - goodbye should say goodbye']
##teamcity[testFailed name='PhantomJS 1.9 - goodbye should say goodbye' message='expected |'hello world|' to equal |'goodbye world|'' details='AssertionError: expected |'hello world|' to equal |'goodbye world|'|n at http://localhost:7357/testem/chai.js:873|n at assertEqual (http://localhost:7357/testem/chai.js:1386)|n at http://localhost:7357/testem/chai.js:3627|n at http://localhost:7357/hello_spec.js:14|n at callFn (http://localhost:7357/testem/mocha.js:4338)|n at http://localhost:7357/testem/mocha.js:4331|n at http://localhost:7357/testem/mocha.js:4728|n at http://localhost:7357/testem/mocha.js:4819|n at next (http://localhost:7357/testem/mocha.js:4653)|n at http://localhost:7357/testem/mocha.js:4663|n at next (http://localhost:7357/testem/mocha.js:4601)|n at http://localhost:7357/testem/mocha.js:4630|n at timeslice (http://localhost:7357/testem/mocha.js:5761)']
##teamcity[testFinished name='PhantomJS 1.9 - goodbye should say goodbye']
##teamcity[testSuiteFinished name='mocha.suite' duration='11091']
To see all command line options for CI
testem ci --help
For the simplest JavaScript projects, the TDD workflow described above will work fine. There are times when you want
to structure your source files into separate directories, or want to have finer control over what files to include.
This calls for the testem.json configuration file (you can also alternatively use the YAML format with a testem.yml file). It looks like
{
"framework": "jasmine",
"src_files": [
"hello.js",
"hello_spec.js"
]
}
The src_files can also be unix glob patterns.
{
"src_files": [
"js/**/*.js",
"spec/**/*.js"
]
}
You can also ignore certain files using src_files_ignore.
Update: I've removed the ability to use a space-separated list of globs as a string in the src_files property because it disallowed matching files or directories with spaces in them.
{
"src_files": [
"js/**/*.js",
"spec/**/*.js"
],
"src_files_ignore": "js/toxic/*.js"
}
Read more details about the config options.
You can also use a custom page for testing. To do this, first you need to specify test_page to point to your test page in the config file (framework and src_files are irrelevant in this case)
{
"test_page": "tests.html",
"launch_in_dev": [
"Chrome"
]
}
Next, the test page you use needs to have the adapter code installed on them, as specified in the next section.
Include this snippet directly after your jasmine.js, qunit.js or mocha.js scripts to enable Testem with your test page.
<script src="/testem.js"></script>
Or if you are using require.js or another loader, just make sure you load /testem.js as the next script after the test framework.
'/testem.js' here is dynamically generated to be used client-side and it should not be confused with server-side 'testem.js'.
To enable dynamic substitutions within the Javascript files in your custom test page, you must
.mustache as the extension{{#serve_files}} to loop over the set of Javascript files to be served, and then reference its src property to access their path (or {{#css_files}} for stylesheets)Example:
{{#serve_files}}
<script src="{{src}}"></script>
{{/serve_files}}
{{#css_files}}
<link rel="stylesheet" href="{{src}}">
{{/css_files}}
You can also specify multiple test pages to run by passing an array to the test_page option.
{
"test_page": [
"unit-tests.html",
"integration-tests.html"
]
}
This will cause Testem to run each test page in a separate launcher instance for each launcher you are using. This means that if you define 2 test pages and are using 3 launchers you will get 6 unique runs (2 per launcher).
Testem has the ability to automatically launch browsers or processes for you. To see the list of launchers Testem knows about, you can use the command
testem launchers
This will display something like the following
Have 5 launchers available; auto-launch info displayed on the right.
Launcher Type CI Dev
------------ ------------ -- ---
Chrome browser ✔
Firefox browser ✔
Safari browser ✔
Opera browser ✔
Mocha process(TAP) ✔
This displays the current list of launchers that are available. Launchers can launch either a browser or a custom process — as shown in the "Type" column. Custom launchers can be defined to launch custom processes. The "CI" column indicates the launchers which will be automatically launched in CI-mode. Similarly, the "Dev" column lists those that will automatically launch in dev-mode.
You can add your own custom paths to browser binaries by including browser_paths and/or browser_exes options in your Testem configuration. For example:
"browser_paths": {
"Chromium": "./node_modules/puppeteer/.local-chromium/mac-549031/chrome-mac/Chromium.app/Contents/MacOS/Chromium"
}
"browser_exes": {
"Chromium": "chrome-custom-binary"
}
Adding a browser_path for a browser will override all default places for testem to look for the browser. So if the browser doesn't exist at the path you provided, you will get failures.
Testem passes its own list of arguments to some of the browsers it launches. You can add your own custom arguments to these lists by including the browser_args option in your Testem configuration. For example:
"browser_args": {
"Chrome": [
"--auto-open-devtools-for-tabs"
]
}
You can supply arguments to any number of browsers Testem has available by using the launcher name as a key in browser_args. Values may be an array of string arguments, a single string, or an object of arguments by mode.
Read more details about the browser argument options.
To run tests in Node you need to create a custom launcher which launches a process which will run your tests. This is nice because it means you can use any test framework - or lack thereof. For example, to make a launcher that runs mocha tests, you would write the following in the config file testem.json
"launchers": {
"Mocha": {
"command": "mocha tests/*_tests.js"
}
}
When you run testem, it will auto-launch the mocha process based on the specified command every time the tests are run. It will display the stdout and well as the stderr of the process inside of the "Mocha" tab in the UI. It will base the pass/fail status on the exit code of the process. In fact, because Testem can launch any arbitrary process for you, you could very well be using it to run programs in other languages.
If your process outputs test results in TAP format, you can tell that to testem via the protocol property. For example
"launchers": {
"Mocha": {
"command": "mocha tests/*_tests.js -R tap",
"protocol": "tap"
}
}
When this is done, Testem will read in the process's stdout and parse it as TAP, and then display the test results in Testem's normal format. It will also hide the process's stdout output from the console log panel, although it will still display the stderr.
PhantomJS is a Webkit-based headless browser. It's fast and it's awesome! Testem will pick it up if you have PhantomJS installed in your system and the phantomjs executable is in your path. Run
testem launchers
And verify that it's in the list.
If you want to debug tests in PhantomJS, include the phantomjs_debug_port option in your testem configuration, referencing an available port number. Once testem has started PhantomJS, navigate (with a traditional browser) to http://localhost: and attach to one of PhantomJS's browser tabs (probably the second one in the list). debugger statements will now break in the debugging console.
If you want to use any of the PhantomJS command line options, include the phantomjs_args option in your testem configuration. For example:
"phantomjs_args": [
"--ignore-ssl-errors=true"
]
You can also customize the phantomjs launcher file by specifying the phantomjs_launch_script option.
In this launcher you can change options like the viewPortSize. See assets/phantom.js for the default launcher.
If you need to run a preprocessor (or indeed any shell command before the start of the tests) use the before_tests option, such as
"before_tests": "coffee -c *.coffee"
And Testem will run it before each test run. For file watching, you may still use the src_files option
"src_files": [
"*.coffee"
]
Since you want to be serving the .js files that are generated and not the .coffee files, you want to specify the serve_files option to tell it that
"serve_files": [
"*.js"
]
Testem will throw up a big ol' error dialog if the preprocessor command exits with an error code, so code checkers like jshint can be used here as well.
If you need to run a command after your tests have completed (such as removing compiled .js files), use the after_tests option.
"after_tests": "rm *.js"
If you would prefer simply to clean up when Testem exits, you can use the on_exit option.
It is possible to send coverage reports or run other JavaScript in the browser by using the afterTests method.
Testem.afterTests(
function(config, data, callback) {
var coverage = window.__coverage__;
var postBody = JSON.stringify(coverage);
if (postBody) {
var xhr = new XMLHttpRequest();
xhr.onreadystatechange = function() {
if (xhr.readyState === 4) {
callback();
}
};
xhr.open('POST', 'http://localhost:7358/', true);
xhr.send(postBody);
}
});
Sometimes you may want to re-map a URL to a different directory on the file system. Maybe you have the following file structure:
+ src
+ hello.js
+ tests.js
+ css
+ styles.css
+ public
+ tests.html
Let's say you want to serve tests.html at the top level url /tests.html, all the Javascripts under /js and all the css under /css. You can use the "routes" option to do that
"routes": {
"/tests.html": "public/tests.html",
"/js": "src",
"/css": "css"
}
If you want to use Testem with a test framework that's not supported out of the box, you can write your own custom test framework adapter. See customAdapter.js for an example of how to write a custom adapter.
Then, to use it, in your config file simply set
"framework": "custom"
And then make sure you include the adapter code in your test suite and you are ready to go. See here for the full example.
If you'd prefer not to be looking at the terminal while developing, you can enable native notifications (e.g. notification center, growl) using the -g option.
The proxy option allows you to transparently forward HTTP requests to an external endpoint.
Simply add a proxies section to the testem.json configuration file.
{
"proxies": {
"/api": {
"target": "http://localhost:4200",
"onlyContentTypes": ["xml", "json"]
},
"/xmlapi": {
"target": "https://localhost:8000",
"secure": false
}
}
}
This functionality is implemented as a transparent proxy, hence a request to
http://localhost:7357/api/posts.json will be proxied to http://localhost:4200/api/posts.json without removing the /api prefix. Setting the secure option to false as in the above /xmlapi configuration block will ignore TLS certificate validation and allow tests to successfully reach that URL even if testem was launched over HTTP. Other available options can be found here: https://github.com/nodejitsu/node-http-proxy#options
To limit the functionality to only certain content types, use "onlyContentTypes".
I've created examples for various setups
On Windows, Mocha fails to run under Testem due to an issue in Node core. Until that gets resolved, I've made a workaround for Mocha. To install this fork of Mocha, do
npm install https://github.com/airportyh/mocha/tarball/windowsfix -g
If you are using prototype.js version 1.6.3 or below, you will encounter issues.
If you want to contribute to the project, I am going to do my best to stay out of your way.
Testem depends on the following great software
FAQs
Test'em 'scripts! Javascript Unit testing made easy.
The npm package testem receives a total of 0 weekly downloads. As such, testem popularity was classified as not popular.
We found that testem demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Create React App is officially deprecated due to React 19 issues and lack of maintenance—developers should switch to Vite or other modern alternatives.
Security News
Oracle seeks to dismiss fraud claims in the JavaScript trademark dispute, delaying the case and avoiding questions about its right to the name.
Security News
The Linux Foundation is warning open source developers that compliance with global sanctions is mandatory, highlighting legal risks and restrictions on contributions.