Super-agent driven library for testing HTTP servers
HTTP assertions made easy via super-agent.
The motivation with this module is to provide a high-level abstraction for testing HTTP, while still allowing you to drop down to the lower-level API provided by super-agent.
Install SuperTest as an npm module and save it to your package.json file as a development dependency:
npm install supertest --save-dev
Once installed it can now be referenced by simply calling
You may pass an
http.Server, or a
request() - if the server is not
already listening for connections then it is bound to an ephemeral port for you so
there is no need to keep track of ports.
SuperTest works with any test framework, here is an example without using any test framework at all:
var request = require'supertest'express = require'express';var app = express;appget'/user'ressend200 name: 'tobi' ;;requestappget'/user'expect'Content-Type' /json/expect'Content-Length' '20'expect200endif err throw err;;
Here's an example with mocha, note how you can pass
done straight to any of the
describe'GET /user'it'respond with json'requestappget'/user'set'Accept' 'application/json'expect'Content-Type' /json/expect200 done;
One thing to note with the above statement is that superagent now sends any HTTP
error (anything other than a 2XX response code) to the callback as the first argument if
you do not add a status code expect (i.e.
If you are using the
.expect() assertions that fail will
not throw - they will return the assertion as an error to the
.end() callback. In
order to fail the test case, you will need to rethrow or pass
done(), as follows:
describe'GET /users'it'respond with json'requestappget'/user'set'Accept' 'application/json'expect200endif err return doneerr;done;;;;
Expectations are run in the order of definition. This characteristic can be used to modify the response body or headers before executing an assertion.
describe'GET /user'it'user.name should be an case-insensitive match for "tobi"'requestappget'/user'set'Accept' 'application/json'expectresbodyid = 'some fixed id';resbodyname = resbodynametoUpperCase;expect200id: 'some fixed id'name: 'TOBI'done;;;
Anything you can do with superagent, you can do with supertest - for example multipart file uploads!
requestapppost'/'field'name' 'my awesome avatar'attach'avatar' 'test/fixtures/homeboy.jpg'
Passing the app or url each time is not necessary, if you're testing
the same host you may simply re-assign the request variable with the
initialization app or url, a new
Test is created per
request = request'';requestget'/'expect200console.logerr;;requestget'/'expect'heya'console.logerr;;
Here's an example with mocha that shows how to persist a request and its cookies:
var request = require'supertest'should = require'should'express = require'express';describe'request.agent(app)'var app = express;appuseexpresscookieParser;appget'/'rescookie'cookie' 'hey';ressend;;appget'/return'if reqcookiescookie ressendreqcookiescookie;else ressend':(';var agent = requestagentapp;it'should save cookies'agentget'/'expect'set-cookie' 'cookie=hey; Path=/' done;it'should send cookies'agentget'/return'expect'hey' done;
There is another example that is introduced by the file agency.js
You may use any super-agent methods,
.pipe() etc and perform assertions in the
for lower-level needs.
status code and
body text with a string, regular expression, or
parsed body object.
value with a string or regular expression.
Pass a custom assertion function. It'll be given the response object to check. If the response is ok, it should return falsy, most commonly by not returning anything. If the check fails, throw an error or return a truthy value like a string that'll be turned into an error.
Here the string or error throwing options are both demonstrated:
requestappget'/'expecthasPreviousAndNextKeysenddone;if !'next' in resbody return "missing next key";if !'prev' in resbody throw "missing prev key";
Perform the request and invoke
Inspired by api-easy minus vows coupling.