vows is a testing framework for NodeJS.
- Copyright 2016-2018 fuzzy.ai mailto:[email protected]
- Copyright 2017 AJ Jordan mailto:[email protected]
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
var vows = require('vows');
// vows does not pollute the assert module namespace by default
var assert = vows.assert;
vows
.describe("My first vows test")
.addBatch({
'When we open a file': {
topic: function() {
fs.open("/tmp/fakefile", "w", this.callback);
},
'it works': function(err, fd) {
assert.ifError(err);
assert.isNumber(fd);
},
teardown: function(fd) {
fs.close(fd, this.callback);
}
'and we write to the file': {
topic: function(fd) {
fs.write(fd, "My dog has fleas\n", this.callback);
},
'it works': function(err, written, buffer) {
assert.ifError(err);
assert.greater(written, 0);
assert.isString(buffer);
}
}
}
})
.run();You require the module like any other module.
vows provides its own suite of assert macros. To use them, you should use the
assert property from the vows module, like so:
var vows = require('vows');
var assert = vows.assert;The basic way to use tests is to build really large hierarchical objects with a particular well-defined form.
For vows, the core concept is the test batch. A batch is an object that
consists of the following:
-
A
topicfunction that generates values to be tested -
One or more test functions, which accept the results of the
topicand use assert macros to validate the results -
Zero or more sub-batches
-
An optional
teardownfunction that cleans up any values generated by the topic
A batch can be either synchronous or asynchronous. For a synchronous batch,
the topic function just returns a value, and the test functions measure that
value:
let batch = {
"We get the answer": {
topic() {
return 6 * 7;
},
"it equals 42": (err, answer) => {
assert.ifError(err);
assert.equal(answer, 42);
}
}
};For an asynchronous batch, the topic returns its results through the callback
property of this. vows knows that the callback will be used because the
result returned by the topic function is undefined.
let batch = {
"When we get the answer asynchronously": {
topic() {
setImmediate(() => {
this.callback(null, 6 * 7);
});
return undefined;
},
"it equals 42": (err, answer) => {
assert.ifError(err);
assert.equal(answer, 42);
}
}
};Alternately, a topic can return a Promise.
vows will resolve the returned Promise and call tests with the same
(err, results) format as with other types of call.
let batch = {
"When we get the answer": {
topic() {
return new Promise((resolve, reject) => {
fs.open("/tmp/testfile", "w", (err, fd) => {
if (err) {
reject(err);
} else {
resolve(fd);
}
})
});
},
"it equals 42": (err, fd) => {
assert.ifError(err);
assert.isNumber(fd);
}
}
};Note that all test functions receive at least an err argument, and then one or
more arguments. Synchronous batches can only have one test argument;
asynchronous batches can have a lot.
For backwards compatibility, it's possible to call this.callback synchronously
in your topic. vows will simply call setImmediate to call the callback
later. But that is a tricky and confusing way to write your tests, and you
should probably avoid it.
A batch can also have sub-batches. These are just properties of the batch that
are also batch objects, with their own topic, tests, sub-batches, teardown,
etc. The argument to the topic will be the results of the parent batch, in
reverse order up the hierarchy.
let batch = {
"When we get the answer": {
topic() {
return 6 * 7;
},
"it equals 42": (err, answer) => {
assert.ifError(err);
assert.isNumber(answer);
assert.equal(answer, 42);
},
"and we ask a couple of questions": {
topic(answer) {
return [
"What is six times seven?",
"How many roads must a person walk down?"
];
},
"they look plausible": (err, questions) => {
assert.ifError(err);
assert.isString(question[0]);
assert.equal(question[0][question[0].length - 1], '?');
assert.isString(question[1]);
assert.equal(question[1][question[1].length - 1], '?');
},
"and we compare the answer and the question": {
topic(questions, answer) {
setImmediate(() => {
this.callback(null, questions[0], questions[1], answer);
});
return undefined;
},
"they match up well": (err, question0, question1, answer) => {
assert.ifError(err);
// NB: you need to implement isAnswerTo yourself
assert(isAnswerTo(answer, question0));
assert(isAnswerTo(answer, question1));
}
}
}
}
};Note that if a batch's topic returns more than one value to its callback, they
will be provided in order for any sub-batches' topic, but hierarchically
in reverse order. This may be a little confusing.
Note also that if an error occurs, in either the topic or the tests, the sub-batches will not be run.
The teardown method is called after all the tests and sub-batches have been
run. So, the order is something like this:
- topic
- tests
- sub-batches (if there are no errors)
- teardown
The teardown gets the non-error results of the topic as arguments. It's
useful for cleaning up things that the topic made a mess of.
batch = {
'When we open a file': {
topic: function() {
fs.open("/tmp/fakefile", "w", this.callback);
},
'it works': function(err, fd) {
assert.ifError(err);
assert.isNumber(fd);
},
teardown: function(fd) {
fs.close(fd, this.callback);
}
}
};teardown functions can also be synchronous or asynchronous, or they can return
a Promise. However, the results are ignored.
let batch = {
"When we get the answer": {
topic() {
return new Promise((resolve, reject) => {
fs.open("/tmp/testfile", "w", (err, fd) => {
if (err) {
reject(err);
} else {
resolve(fd);
}
})
});
},
"it equals 42": (err, fd) => {
assert.ifError(err);
assert.isNumber(fd);
},
teardown(fd) {
return new Promise((resolve, reject) => {
if (typeof(fd) != 'number') {
reject(new Error("File descriptor is not a number"));
} else {
fs.close(fd, (err) => {
if (err) {
reject(err);
} else {
resolve();
}
})
}
});
}
}
};Note that the teardown will be called regardless of whether errors happened or not, so it's a good idea to check the arguments to make sure they're valid.
Teardowns are called as soon as the batch finishes; this is different from how vows.js works, but it is better.
If you're using a version of node that can handle async/await syntax, (>= 7.10.1), you can use async functions in your topics and teardowns, which can make your aysnchronous test code about as lovely and compact as can be.
const fs = require('fs');
const util = require('util');
// util.promisify is available in node > 8.0.0
const open = util.promisify(fs.open);
const close = util.promisify(fs.close);
let batch = {
"When we get the answer": {
topic: async function () {
return await open("/tmp/testfile", "w");
},
"it equals 42": (err, fd) => {
assert.ifError(err);
assert.isNumber(fd);
},
teardown: async function (fd) {
return await close(fd);
}
}
};Batches are organized into suites. You create a suite with the describe method
of vows.
const vows = require('vows');
let suite = vows.describe('A new suite');You can then add one or more batches to the suite using the addBatch method.
suite.addBatch(batch1);
suite.addBatch(batch2);
suite.addBatch(batch3);Finally, you have two options to actually run the test suite. The first is the
aptly-named run() method, which runs all the tests and reports the results to
stdout. You can then run the script through node and you'll run all your
tests.
Alternately, you can use the export() method, passing the current module as
an argument. This will change the exports property of the module to be the
run() method of the suite. In other words, the module will now export a single
function that runs the suite.
The vows command-line tool can be used to run all your test modules that
use export().
./node_modules/.bin/vows test/*.jsAll the suite methods are chainable.
The typical way to actually use this library, then, is to require vows, use the
describe method to create a suite, use addBatch to add one or more batches,
and then use export(module) or more rarely run() to run the suite.
const fs = require('fs');
const vows = require('vows');
let assert = vows.assert;
vows.describe('Input/output tests')
.addBatch({
'When we open a file': {
topic: function() {
fs.open("/tmp/fakefile", "w", this.callback);
},
'it works': function(err, fd) {
assert.ifError(err);
assert.isNumber(fd);
},
teardown: function(fd) {
fs.close(fd, this.callback);
}
}
})
.export(module);CoffeeScript is a nice pre-processor for JavaScript.
If you write your test scripts in CoffeeScript, it's totally OK to run them with
the vows command-line tool, as-is.
./node_modules/.bin/vows test/*.js test/*.coffeevows uses the CoffeeScript package to load the test modules automatically.
Test-driven development means roughly that write your tests first, then write the implementations, then keep running the tests till they work.
vows doesn't necessarily do a fantastic job at this, but it's a little
better, and it's definitely a goal. vows uses the
debug library to spoot out debug info to
stderr at run time. This can be very useful for looking at how the vows
module is running, and figuring out where errors are happening.
To use it, define the DEBUG environment variable when running your tests:
DEBUG=vows:* ./node_modules/.bin/vows mytest.jsWatch this space for more help in doing TDD with vows.
This 1.x version is incompatible with previous 0.x versions of vows in a few small ways.
-
vows 0.x will check the arity of test methods and call the method different ways based on that arity. With vows 1.x, tests will always take an error argument and then zero or more result arguments. This should help preserve your sanity and make you write more robust tests.
-
vows 0.x will automatically pollute the namespace of the
assertmodule. vows 1.x makes you use a property instead. -
vows 0.x handle all teardowns at the same time, without waiting for sub-batch teardowns to finish. vows 1.x handles teardowns when the batch is finished, so you can do things like deleting created files in your sub-batch teardowns, and deleting their directory in your main batch teardown, and things will just work right.
-
vows 0.x treat a Promise returned from the topic just like any other results. So test functions will receive the Promise as a results argument. vows 1.x will resolve the Promise and pass the results to the test instead. So, if your tests expect to receive a Promise passed synchronously, you should change that.
-
vows 1.x does not pass
this.contextto the topic. -
vows 1.x does not support many of the undocumented features of vows 0.x, including
vows.prepare(),beforeSuite(),afterSuite(), andvows.options. -
vows 1.x only provides a single, default reporter.
-
vows 1.x does not support command-line control of verbosity (
-vor-s). -
vows 1.x does not support the
-mor-rcommand-line flags. -
vows 0.x automatically runs any tests in the
testorspecdirectory. vows 1.x requires that you specify the tests you want to run. -
vows 1.x does not support the
-i(isolate) command-line flag.
The exposed assert module-ish object has a number of useful methods for doing
tests.
The module exposes all the methods of the built-in
assert module. It also has the following
utility methods. Each will do a check and if the check fails, will throw a new
AssertionError with either the message argument as its message, or a
standard message for that macro.
Checks that the number actual is within eps from expected.
Checks that actual matches the regular expression expected. Note that
actual will be coerced to a string if it is not one already.
assert.matches is a synonym.
Checks that actual is true (not just truthy; true).
Checks that actual is false (not just falsy; false).
Checks that actual is 0.
Checks that actual is not 0.
Checks that actual is strictly greater than expected.
Checks that actual is strictly lesser than expected.
Checks that actual is less than delta away from expected. It's a lot
like assert.epsilon().
Checks that actual contains expected. assert.includes is a synonym.
Checks that actual does not contain expected. assert.notIncludes is a
synonym.
Checks that actual is empty (an empty array or an object with no properties).
Checks that actual is not empty.
Checks that actual is an array.
Checks that actual is an object.
Checks that actual is a number.
Checks that actual is a boolean (true or false).
Checks that actual is NaN.
Checks that actual is null.
Checks that actual is not null.
Checks that actual is undefined.
Checks that actual is not undefined.
Checks that actual is a string.
Checks that actual is a function.
Checks that actual is of type expected.
Checks that actual is an object and an instance of expected.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent