Distilled has moved!

The Distilled testing framework is now distributed as @latinfor/distilled. The current package will not be updated past version 1.0.3. You should run npm remove distilled-distilled & npm install @latinfor/distilled to update.

Distilled

Distilled is an aggressively elegant testing framework, inspired by ideals of simplicity, flexibility, and consistency.

Why use Distilled?

The Javascript ecosystem is filled with testing frameworks to choose from. Distilled knows all the buzz words, so of course it's asynchronous-first and totally compatible with modern programming paradigms like Promises. It is smart and sexy and may even someday be compatible with the cool tools like Grunt.

But you don't really care about that. In actuality, Distilled is special because it closely hews to three pillars of design:

Simplicity

Distilled's entire testing API is one method.

var Suite = new Distilled();
suite.test('test label', function () { 
	if (condition) {
		throw 'exception';
	}
});

A radical approach to simplicity makes Distilled easy to learn and work with. Even beginning coders who are unfamiliar with testing can get started quickly and easily.

Distilled achieves enlightenment by liberally culling any unneeded and unnecessary features. Distilled is proud to ship without the following features:

• An assertion library
• setup or teardown hooks
• ignore options for old tests
• test-specific timeouts
• test retry support
• test perfomance logging
• global variable detection
• A CLI runner?!?

Don't be afraid. The majority of these features are unnecessary for your workflow, and any features that you do need are simple and painless for you to re-introduce on the fly.

Speaking of which...

Flexibility

Distilled is so flexible and adaptable that it's almost scandalous. Its general policy is to give users options, not to enforce specific coding styles or paradigms. This utterly agnostic, syntax-tolerant approach means that almost anything you try will work.

The test method:

suite.test('Accept promise', Promise.resolve()); //passes
suite.test('Accept boolean', false); //fails
suite.test('Accept nothing'); //passes
suite.test('Accept function', function () {}); //passes
suite.test('Accept function that returns boolean', function () {
	return false;
}); //fails
suite.test('Accept function that returns promise', function () {
	return Promise.reject();
}); //fails
suite.test('Accept function that returns function that returns promise', function () {
	return function () {
		return Promise.reject();
	};
}); //Fails
suite.test('Accept promise that resolves to function that returns promise that resolves to boolean', Promise.resolve(function () {
    return Promise.resolve(false);
})); //Fails

Because Distilled's test method can accept almost anything, it's easy to introduce custom hooks, wrappers, and to generally extend the heck out of it.

Assertions:

Distilled does not use an assertion library. Rather, it listens for exceptions.

suite.test(function () { throw 'error' });

In practice, this means that Distilled can use any assertion library that throws exceptions.

Or, if you don't want to bother with that, you can even use it with no assertion library at all!

Test Structure and Organization:

Typically, testing frameworks are opinionated about how tests are supposed to be structured and organized. Distilled is not.

Distilled allows you to infinitely nest and group tests as you see fit. Nested tests are conditional, a term which here means that children will only be executed and reported if their parents pass.

Every test call returns a new parent for you to test on.

var setup = suite.test('Parent', Promise.resolve()); //Passes
var child = setup.test('child', function () {
	return Promise.reject('error');
}); //Fails once the parent has finished

var subchild = setup.test('sub-child', function () {
	return Promise.resolve();
}); //Is never run

Distilled can afford to offer this flexibility because it truly is asynchronous-first, down to its very core. In practice, this all-encompassing idea of Promise-like test chaining allows for a high degree of flexibility in deciding how your tests are structured and reported.

• Empty parent tests can be used as descriptive groups.
• If a parent test fails (say, connecting to a database) you don't need to waste time waiting for its children to fail.
• If you're building a harness runner, you can conditionally fetch new tests on the fly, reducing the necessary overhead to start running your tests.

My recommendation is to set up tests descriptively by treating them like promises. However, if you're not a really a "Promise" kind of coder, and you prefer building pyramids of code, of course Distilled still has you covered.

suite.test('Parent', function (parent) {
	if (condition) { throw 'error'; }
	parent.test('child', function () {
		if (sub_condition) { throw 'error'; }
	});
});

Just to be sassy, Distilled also exposes this as a third option:

suite.test('Parent', function () {
	if (condition) { throw 'error'; }
	this.test('child', function () {
		if (sub_condition) { throw 'error'; }
	});
});

Don't be afraid! Wrapping your brain around and embracing the possibilities of infinitely nested tests is the key to adapting Distilled into the perfect workflow for you. With just a little imagination, you'll be building your own opinionated frameworks, spectacular assertion libraries, and innovative test runners in no time at all.

The other key is embracing...

Consistency

When starting out with Distilled, feel free to stick with just the style you're immediately comfortable with. If you do though, keep in mind that the API you're using will be the same no matter what context you're in or what you're trying to do with the library.

• this will always refer to your current testing context, no matter where you are.
• You'll always have that testing context available as a parameter.
• And you'll always be able to launch a new test off of that context.

Those three principles are never false, no matter where you are or what you're doing.

Putting it all together

And now you know how Distilled works! Let's go through a simple example (via NodeJS) describing quite literally everything you need to do to get up and running right now.

In your terminal, install Distilled:

npm install --save-dev distilled-distilled

Make a new file for your tests:

var Distilled = require('distilled-distilled');
var assert = require('assert');
var library = require('../my-library');

var suite = new Distilled();

var module = suite.test('My Library Test');
module.test('Methods: ', function (test) {
	test.test('`add` adds two numbers together', function () {
		assert.deepEqual(library.add(2, 3), 5);
	});

	test.test('`subtract` subtracts two numbers', function () {
		assert.deepEqual(library.subtract(3, 2), 1, 'normal usage');
		assert.deepEqual(library.subtract(2, 3), -1, 'less than zero');
	});
});

Open up your package.json and add a test runner:

{
   "scripts": {
		"test": "node tests/libraryTest.js"
	}
}

And you're done! In your command line, run npm test and check out the results. You now know everything you need to know to get started building great, readable, and maintainable unit tests.

Secret Advanced Usage

Okay, if you're still around, I'll admit it - I wasn't quite honest. See, if you want to get really advanced with Distilled, you're going to have to learn one more method. That's like double the work!

Also, there might be some extra properties floating around that you can use to build things like crazy test reporters!

the then method

Every suite can have callbacks attached by calling then. These will fire off when a given test (and all of its children) have finished running.

Just like tests, then calls are chainable. But unlike test, then resolves to the same suite you called it on.

var suite = new Distilled();
suite.test('a', true)
     .test('b', true);

suite.then(function (test) { //Called when all children have finished
    (this === test); //just like above
});

You'll notice that in keeping with the theme of consistency, you can access a test within its callback, similarly to how test works - either through a parameter or the this keyword.

Why would you want to do this? Because it turns out that after completing, tests have a number of interesting properties attached to them:

{
	label: 'My Test', //the label you passed in when creating the test
	status: 'failed', //passed, failed
	error : Error(), //Error object (if one exists)

	parent : Parent, //Reference to the parent testing context
	children : [] //Reference to any child testing contexts
}

If short, tests have all of the information you would need attached to them to determine both how they ran and where they sit in the overall hierarchy of tests.

the callback

When you're initializing a new suite, you have the option to pass in a callback. This method will get called whenever any test inside the suite finishes executing, regardless of whether it passed or failed.

In short, the callback is a way to specify a default then for each test inside your suite, which is an extremely handy place to put a custom test reporter!

var suite = new Distilled(function (test) {
	console.log(test.label, ': ', test.status);
});

And in fact, when you passed in that function, you just overrode Distilled's built in test reporter. This callback offers you all the tools you need to build your own test reporter that spits out whatever format you'd like. Or, you could take advantage of someone else's existing test reporter.

var reporter = require('awesome-reporter');
var suite = new Distilled(reporter);

Understanding shared context

Want to go a bit deeper? Remember that the context getting passed into both the test method and your callback is the exact same.

This means that you can use it to communicate between tests and your reporter.

var skip = function () {
	this.skip = true;
	return false;
}

var suite = new Distilled(function () {
	if (this.skip) {
		//don't log or report this test, even if it shows up as a failure.
	}
});

suite.test('ignore test', skip).test('my ignored test' //.... 

I told you adding back any other features you wanted would be simple and easy!

With the combined power of two whole methods, you'll be able to sculpt Distilled into any configuration or setup you can imagine.