Distilled logo breakdown Distilled logo

npm stats
build status npm version MIT License Donate
# 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. ```js 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: ```js 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. ```js 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. ```js 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. ```js 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: ```js 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: ```bash npm install --save-dev distilled-distilled ``` Make a new file for your tests: ```js 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: ```json { "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. ```js 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: ```js { 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! ```js 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. ```js 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. ```js 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.