pixl-unit

Overview

This module is a very simple unit test runner.

Usage

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/

Command-Line Arguments

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.

Use in Modules

To use pixl-unit in your own npm module, first declare it in your package.json in the devDependencies section:

"devDependencies": {
	"pixl-unit": "*"
}

Then add a test script command to your scripts section:

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

Sample Output

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

{
    "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": []
}

Test Modules

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.

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:

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 pseudothread. Example:

function testAsync(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:

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

setUp and tearDown

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.

exports.setUp = function(callback) {
	// do some setup here
	callback();
};

exports.tearDown = function(callback) {
	// do some shutdown stuff here
	callback();
};

beforeEach and afterEach

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.

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

timeout

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:

function testTimeout(test) {
	test.timeout( 200 ); // 200ms max time
	
	setTimeout( function() {
		test.ok(true == true, 'Testing 100ms later');
		test.done();
	}, 100 );
}

Debug Logging

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:

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:

test.debug( "This will only be printed in verbose mode", { additional: "data" } );

License

The MIT License

Copyright (c) 2015 - 2022 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.