dupertest
A Node library for unit testing controller actions without having to spin up a server. Because unit testing controllers in Node should be easier.
- An acknowledged naming-spoof on supertest -- because super-duper-test was a little clunky.
Unit Test Node Controllers the Right Way
Unit testing Node controllers should be simple. Rails has it easy with RSpec, but unfortunately no test framework provides the same simplicity for unit testing controllers in Node.
Jasmine is great at testing code, but doesn't go very far with app logic. Supertest extends where Jasmine leaves off, but goes too far in spinning up a live server to send requests to. Unit tests shouldn't use live servers or even databases -- enter dupertest
. Test Node controllers like you want to.
Install
To install the latest official version, use NPM:
npm install dupertest
To run the test suite, including example usage specs:
npm test
Usage
Calling a controller action and making an assertion about the response is as simple as this:
var request = require('dupertest');
request(controller.action)
.params({id: 123})
.expect(entity, done);
For a more detailed example, imagine an entities-controller
with a show
action that needs to be tested.
// example controller action
exports.show = function(req, res) {
var id = req.params.id,
entity = Entity.find(id);
res.send(entity);
};
With dupertest
, testing that controller action is easy:
var request = require('dupertest'),
entities = require('../controllers/entities-controller');
// create mock entity and other test setup here
var entity = {
id: 123,
name: 'Cool Entity'
};
describe('entities.show', function () {
it('should return an error when an entity does not exist', function (done) {
request(entities.show)
.params({id: 1})
.expect(404, done);
});
it('should return an entity when one does exist', function (done) {
request(entities.show)
.params({id: 123})
.end(function(response) {
expect(response).toEqual(entity);
done();
});
});
});
// Examples shown using Jasmine -- dupertest will work with any test framework.
// However, the `expect` method is only available when using Jasmine
It's that simple. It looks just like request
or supertest
syntax, but without the requirement of a server.
- Check out the example specs for more usage examples.
So what's going on?
Under the hood, it's a lot like one might expect. dupertest
takes in a controller action, and then lets you build up the request and response objects to your liking. After adding various properties to the req
and res
objects, such as params
, body
, or anything else you need with the flexible extendReq
function, the original controller action gets called with either the shorthand expect
or the longhand end
method.
dupertest
really shines in allowing users to continue using a comfortable format for request chains, without having to worry about passing assertion statements around.
For a direct example of where a need for dupertest
might be, check out this Stackoverflow post, and my response example using dupertest (note, syntax in response may be outdated).
Documentation
Requiring dupertest
into a file returns a single method to be invoked with the desired controller action to test. Invoking this method returns an instance of the Request
class.
var request = require('dupertest');
request(<action-to-test>);
// => '[object Request]'
Request
Methods available to the Request
instance.
-
Request.prototype.params (object)
Shorthand notation to set thereq.params
object. -
Request.prototype.body (object)
Shorthand notation to set thereq.body
object. -
Request.prototype.extendReq (object)
Liberally extends thereq
object to include any passed in properties. Use this to add any properties or functions that are not covered in the shorthand methods. See example specs for usage. -
Request.prototype.extendRes (object)
Liberally extends theres
object to include any passed in properties. Use this to add any properties or functions that are not covered in the shorthand methods. See example specs for usage. -
Request.prototype.beforeSend (fn)
Allows thereq
orres
objects to be dynamically modified before the response is sent. The provided function will be invoked in the context of theRequest
instance. See example specs for usage. -
Request.prototype.next (fn)
Allows to test controllers (middleware) that are not supposed to sent a response to the client, but pass the control to the next middleware. See example specs for usage. -
Request.prototype.errNext (fn)
Same asRequest.prototype.next (fn)
, but this allows to test error handling middleware, whennext
is called with a parameter in the controller (next(err)
). See example specs for usage. -
Request.prototype.expect (object, fn)
Shorthand syntax for a Jasmine expect statement. The expectation is often in the form of an object (but can be anything), and will be compared to the return value of the controller action with the Jasmine statement:expect(obj).toEqual(object)
. This method ends the request chain. As such, the callback function will often bedone
. Note: Jasmine must be the test framework for this method to work. -
Request.prototype.end (fn)
Ends the request chain with a supplied callback receiving the return value from the original controller action. In almost every case the callback will want to include the expect statement.
Todo / Known Issues
- Bring in a standard library for more robust mock request and response objects.
- Add a way to inject assertions to other
res
properties besides justsend
. - Test with other frameworks, like Mocha.
Be sure to also check out any issues.
Contributing
- Fork it
- Create your feature branch
git checkout -b my-new-feature
- Commit your changes
git commit -am 'Add some feature'
- Push to the branch
git push origin my-new-feature
- Create new Pull Request