A very simple unit test runner for Node.js.
npm install pixl-unitThis module is a very simple unit test runner.
Use npm to install the module as a command-line executable:
``
sudo npm install -g pixl-unit
Then call it using pixl-unit and specify a path to your unit test file or directory:
`
pixl-unit /path/to/your/unit/tests.js
You may specify multiple files and/or directories, separated by spaces. If you specify directories, the script will scan the contents and execute all JS files within (one level deep only).
`
pixl-unit /path/to/your/unit/test/dir/
Specify command-line arguments using the format --key value and do this after any and all unit test files / directories. The following command-line switches are supported:
| Argument | Default Value | Description |
| -------- | ------------- | ----------- |
| threads | 1 | The total number of threads to use when executing tests. See warning below. | verbose
| | 0 | Set this to 1 to enable verbose output to the console. | quiet
| | 0 | Set this to 1 to suppress all output to the console. | color
| | 1 | Enables or disables color output using the chalk module. | fatal
| | 0 | Set this to 1 to exit immediately after the first assertion failure (includes stack trace). | output
| | "" | Set this to a file path to emit a JSON report (works with quiet mode). | delay
| | 0 | Insert a delay between each test by setting this to the desired number of seconds. |times
| | 1 | Run the tests a specified number of times. |
Here is an example, which runs all the tests in tests.js, enables quiet mode, and generates a JSON report file:
`
pixl-unit /path/to/tests.js --quiet --output /var/tmp/unit-results.json
Please be careful when increasing the --threads setting, beyond the default value of 1. This will cause multiple tests to run simultaneously. If any of your tests rely on previous tests completing, this will not go well.
To use pixl-unit in your own npm module, first declare it in your package.json in the devDependencies section:
`javascript`
"devDependencies": {
"pixl-unit": "*"
}
Then add a test script command to your scripts section:
`javascript`
"scripts": {
"test": "pixl-unit test/*.js"
}
This example assumes you have a test/ directory in your module containing one or more JS files containing unit tests compatible with pixl-unit.
Then you can simply type npm test to run your module's unit tests.
pixl-unit outputs to the console by default, using the chalk module for ANSI color. Stats are summarized at the bottom. You can also suppress this output and/or generate a JSON report file (see below).
`
Simple Unit Test Runner v1.0
Sat Mar 07 2015 12:50:11 GMT-0800 (PST)
Args: {"threads":1,"verbose":0,"quiet":0,"color":1,"fatal":0,"output":""}
Suites: ["/Users/jhuckaby/node_modules/pixl-unit/test.js"]
Suite: /Users/jhuckaby/node_modules/pixl-unit/test.js
ā OK - All tests passed
Tests passed: 3 of 3 (100%)
Tests failed: 0 of 3 (0%)
Assertions: 5
Test Suites: 1
Time Elapsed: 0 seconds
`
Assertion failures are highlighted in bold + red, and include the test name, assertion failure message, and any additional data if provided. Example:
`
Suite: /Users/jhuckaby/node_modules/pixl-unit/test.js
Assert Failed: /Users/jhuckaby/node_modules/pixl-unit/test.js: testExpect: Assertion 2 of 3
Data: {"additional_data":12345}
X testExpect
X - Errors occurred
Tests passed: 2 of 3 (66%)
Tests failed: 1 of 3 (33%)
Assertions: 5
Test Suites: 1
Time Elapsed: 0.11 seconds
`
You can also get a full stack trace by enabling verbose mode (--verbose) or fatal mode, which also exits at the first failure (--fatal). This will give you the exact line number where the assertion failed.
Here is example JSON report (activate by including --output MYREPORT.json on the CLI):
`javascript`
{
"args": {
"color": 1,
"fatal": 0,
"output": "/var/tmp/joe.json",
"quiet": true,
"threads": 1,
"verbose": 0
},
"asserts": 5,
"elapsed": 0.108,
"failed": 0,
"files": [
"/Users/jhuckaby/node_modules/pixl-unit/test.js"
],
"passed": 3,
"suites": 1,
"tests": 3,
"time_end": 1425762119.48,
"time_start": 1425762119.372,
"errors": []
}
Your test modules should be simple JS files containing tests, and optionally setup and teardown functions (described below). Feel free to require any other modules you need at the top of your JS file.
You declare unit tests in your modules by exporting a tests array of functions. The functions are executed in order from top to bottom, and support async tests by using a promise object.
`javascript`
exports.tests = [
// function test1...
// function test2...
];
Each test function should have a name, and accept a single argument which works sort of like a promise:
`javascript`
function testTrue(test) {
test.ok(true == true, 'Testing for true');
test.done();
}
The test object has an assertion method called ok() (assert() is also acceptable). This expects a boolean true for success, false for failure, and optionally accepts a message to be displayed upon failure.
Calling test.done() indicates that all the asserts have been called, and the test is complete. This is useful because tests may be asynchronous, and finish in another thread. Example:
`javascript`
function testTimeout(test) {
setTimeout( function() {
test.ok(true == true, 'Testing 100ms later');
test.done();
}, 100 );
}
If you know exactly how many asserts will be called for a given test, you can call expect() at the beginning of the test, which sets an expectation for the assertion count. If you then call done() without completing the asserts (or called too many) an error is raised. Example use:
`javascript`
function testExpect(test) {
// test the expect feature
test.expect(3);
test.ok( true, "Assertion 1 of 3" );
test.ok( true, "Assertion 2 of 3" );
test.ok( true, "Assertion 3 of 3" );
test.done();
}
You can also provide true async functions which are handled properly. You do not need to call test.done() in these cases (it's a no-op). Example:
`js`
async function testAsync(test) {
// true async function
// test harness will wait for promise to resolve
// no need to call test.done()
await sleep(100);
}
Feel free to use Node's built-in assert library for async tests, as exceptions will be caught correctly:
`js`
async function testMath(test) {
assert.strictEqual(1, 0); // will fail
}
However, note that pixl-unit's own "assertion counter" stat (asserts) doesn't increment for these calls.
You can optionally export setUp() and/or tearDown() functions from your module, which are called when the test is starting up, and shutting down, respectively. These functions are passed a single callback which must be invoked to indicate that have finished their operations.
`javascript
exports.setUp = function(callback) {
// do some setup here
callback();
};
exports.tearDown = function(callback) {
// do some shutdown stuff here
callback();
};
`
You can optionally export beforeEach() and/or afterEach() functions from your module, which are called when each test is about to start, and after it completes, respectively. These functions are passed the test object as a single argument, and there is no callback.
`javascript
exports.beforeEach = function(test) {
// test is about to start
console.log("Starting test: " + test.name);
};
exports.afterEach = function(test) {
// test has just completed
console.log("Completed test: " + test.name);
console.log("Failed asserts: " + test.failed);
};
`
You can optionally set a maximum elapsed time for a test. If this time limit is exceeded, an assertion is force-failed on the test. To do this, call timeout() at the start of your test, and specify the timeout value in milliseconds. Example use:
`js`
function testTimeout(test) {
test.timeout( 200 ); // 200ms max time
setTimeout( function() {
test.ok(true == true, 'Testing 100ms later');
test.done();
}, 100 );
}
There are two ways to include additional debugging data with your unit test output. First, you can include a 3rd argument to ok() or assert() which will be logged only if the assertion fails. It can be any JavaScript primitive type (string, number, etc.) or an object, and will be JSON serialized and emitted in gray (if color is enabled). Example:
`javascript`
function testSomething(test) {
test.ok(true == false, 'Testing for true', { additional: "data" } );
test.done();
}
In this case, when the assertion fails, the console output will include:
`
Assert Failed: test.js: testSomething: Testing for true
Data: {"additional":"data"}
The other thing you can do is call test.debug() at any time, and pass in a debug message and an optional data object. This will only emit if pixl-unit is running in verbose mode (i.e. via the --verbose command-line switch). Otherwise it will be suppressed. Example:
`js``
test.debug( "This will only be printed in verbose mode", { additional: "data" } );
The MIT License
Copyright (c) 2015 - 2026 Joseph Huckaby.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.