README.md 11.5 KB
Newer Older
1 2 3 4
<div align="center">
    <a href="https://gitlab.com/distilled/distilled/tree/develop"><img alt="Distilled logo breakdown" src="https://gitlab.com/distilled/distilled/raw/develop/icons/distilled-details.jpg" width="200px" ></a>
    <a href="https://gitlab.com/distilled/distilled/tree/stable"><img alt="Distilled logo" src="https://gitlab.com/distilled/distilled/raw/develop/icons/distilled.jpg" width="200px" ></a>
    <br><br>
5
    <a href="https://nodei.co/npm/@latinfor/distilled/"><img alt="npm stats" src="https://nodei.co/npm/@latinfor/distilled.png?compact=true"></a>
6 7 8
    <br>
    <a href="https://gitlab.com/distilled/distilled/commits/stable"><img alt="build status" src="https://gitlab.com/distilled/distilled/badges/stable/build.svg" /></a>
    <a href="https://badge.fury.io/js/distilled-distilled"><img src="https://badge.fury.io/js/distilled-distilled.svg" alt="npm version" height="18"></a>
9
    <a href="https://opensource.org/licenses/mit-license.php"><img alt="MIT License" src="https://badges.frapsoft.com/os/mit/mit.png?v=103"></a>
Daniel Shumway's avatar
Daniel Shumway committed
10
    <a href="https://gratipay.com/Distilled"><img alt="Donate" src="https://img.shields.io/gratipay/Distilled.svg?style=social&label=Donate&maxAge=2592000"></a>
11 12 13
</div>


14 15
# Distilled

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

18
<br>
19

20 21
## Why use Distilled?

22
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.
23

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

<br>
27 28 29

### Simplicity

30
Distilled's entire testing API is one method. 
31 32 33 34 35 36 37 38 39 40

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

41
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.
42

43
Distilled achieves enlightenment by liberally culling any unneeded and unnecessary features. Distilled is proud to ship _without_ the following features:
44 45 46 47 48 49 50 51 52 53

- 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?!? 

54 55 56 57 58
<br>

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.

<br>
59 60 61

_Speaking of which..._

62 63
<br>

64 65
### Flexibility

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

69 70
<br>

71
#### The ``test`` method: 
72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87
```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
88 89 90
suite.test('Accept promise that resolves to function that returns promise that resolves to boolean', Promise.resolve(function () {
    return Promise.resolve(false);
})); //Fails
91 92
```

93 94 95
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.

<br>
96

97
#### Assertions:
98

99
Distilled does not use an assertion library. Rather, it listens for exceptions.
100 101 102 103 104

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

105 106 107 108 109
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!

<br>
110

111
#### Test Structure and Organization:
112

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

115
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.
116 117 118 119 120 121 122 123 124 125 126 127 128

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
```

129 130 131
<br>

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. 
132 133 134 135 136

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

137 138 139
<br>

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.
140 141 142 143 144 145 146 147 148 149

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

150
Just to be sassy, Distilled also exposes ``this`` as a third option:
151 152 153 154 155 156 157 158 159
```js
suite.test('Parent', function () {
	if (condition) { throw 'error'; }
	this.test('child', function () {
		if (sub_condition) { throw 'error'; }
	});
});
```

160 161 162 163 164
<br>

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.

<br>
165 166 167

_The other key is embracing..._

168 169
<br>

170
### Consistency
171

172
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.
173 174 175 176 177 178 179

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

180 181
<br>

182 183
## Putting it all together

184
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.
185

186
In your terminal, install Distilled:
187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222
```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.

223 224
<br>

225
## Secret Advanced Usage
226

227
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!
228 229 230

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

231 232
<br>

233
### the ``then`` method
234

235
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.
236

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

```js
240 241 242 243 244 245
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
246 247 248
});
```

249 250
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.

251 252
<br>

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

255
```js
256 257 258 259 260 261 262 263 264 265
{
	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
}
```

266 267
<br>

268 269
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.

270 271 272 273 274 275 276 277 278 279 280 281 282
### 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);
});
```

283
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.
284 285 286 287 288 289

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

290 291
<br>

292
### Understanding shared context
293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312

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' //.... 
```

313 314
<br>

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

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

<br>