## README

# Rationale

This is a thin wrapper around vows. I didn't like how verbose vows is, but I like the async features.

# Installation

Local installation

```
npm install --save sirrobert-test-vows
```

Global installation

```
npm install --global sirrobert-test-vows
```

# Usage

## Comparison with Vows

For a full description of vows, you should check out the vows website. Here's a brief comparison, though.

The vows site gives a brief example of testing some division by zero errors:

```
// division-by-zero-test.js
var vows = require('vows'),
assert = require('assert');
// Create a Test Suite
vows.describe('Division by Zero').addBatch({
'when dividing a number by zero': {
topic: function () { return 42 / 0 },
'we get Infinity': function (topic) {
assert.equal (topic, Infinity);
}
},
'but when dividing zero by zero': {
topic: function () { return 0 / 0 },
'we get a value which': {
'is not a number': function (topic) {
assert.isNaN (topic);
},
'is not equal to itself': function (topic) {
assert.notEqual (topic, topic);
}
}
}
}).run(); // Run it
```

Here's the same thing using this DSL. I've left the same comments so it doesn't get shorter for cheaty reasons.

```
// division-by-zero-test.js
var Test = require("sirrobert-test-vows");
// Create a Test Suite
new Test(
"Division by Zero",
{ when: "dividing a number by zero",
using: () => 42/0,
"we get Infinity": result => Test.is.equal(result, Infinity)
},
{ when: "dividing zero by zero",
using: () => 0/0,
"we get a value which": {
"is not a number": result => Test.it.isNaN(result),
"is not equal to itself": result => Test.is.notEqual(result,result),
}
}
).run(module); // Run it
```

In my opinion, this is much more readable. Mainly because I don't relate to the "vows", "topic", "batch" language in vows, but also because it reads approximately like a sentence:

```
Test
"blah blah"
when "blah blah"
using <some method>
"result 1" <by this means>,
"result 2" <by this means>,
"result 3" <by this means>,
when "blah blah"
using <some method>
"result 1" <by this means>,
"result 2" <by this means>,
"result 3" <by this means>,
```

## Sugar

This module also smuggles in node's `assert`

module so you don't have to
import it yourself. You can, of course. There's some sugar to make it a
little sweeter: you can write short sentences with the module for your
assertions.

```
Test.is(...);
Test.is.equal(...);
Test.is.StrictEqual(...);
Test.it.doesNotThrow(...);
Test.does.fail(...);
```

all three objects (`.is`

, `.it`

, and `.does`

) are just synonyms for the
assert module. That means these are all exactly equivalent:

```
Test.is.equal(...);
Test.it.equal(...);
Test.does.equal(...);
```

... and so on for all other assert features.

# How it Works

Dead simple, it just takes the data structure provided here and re-arranges it slightly to be the vows infrastructure. The source is a couple dozen lines, so reading that will probably be an easier way to understand it.