1 | # SuperTest
|
2 |
|
3 | HTTP assertions made easy via [super-agent](http://github.com/visionmedia/superagent).
|
4 |
|
5 | ## About
|
6 |
|
7 | The motivation with this module is to provide a high-level abstraction for testing
|
8 | HTTP, while still allowing you to drop down to the lower-level API provided by super-agent.
|
9 |
|
10 | ## Example
|
11 |
|
12 | You may pass an `http.Server`, or a `Function` to `request()` - if the server is not
|
13 | already listening for connections then it is bound to an ephemeral port for you so
|
14 | there is no need to keep track of ports.
|
15 |
|
16 | SuperTest works with any test framework, here is an example without using any
|
17 | test framework at all:
|
18 |
|
19 | ```js
|
20 | var request = require('supertest')
|
21 | , express = require('express');
|
22 |
|
23 | var app = express();
|
24 |
|
25 | app.get('/user', function(req, res){
|
26 | res.send(201, { name: 'tobi' });
|
27 | });
|
28 |
|
29 | request(app)
|
30 | .get('/user')
|
31 | .expect('Content-Type', /json/)
|
32 | .expect('Content-Length', '20')
|
33 | .expect(201)
|
34 | .end(function(err, res){
|
35 | if (err) throw err;
|
36 | });
|
37 | ```
|
38 |
|
39 | Here's an example with mocha, note how you can pass `done` straight to any of the `.expect()` calls:
|
40 |
|
41 | ```js
|
42 | describe('GET /users', function(){
|
43 | it('respond with json', function(done){
|
44 | request(app)
|
45 | .get('/user')
|
46 | .set('Accept', 'application/json')
|
47 | .expect('Content-Type', /json/)
|
48 | .expect(200, done);
|
49 | })
|
50 | })
|
51 | ```
|
52 |
|
53 | If you are using the `.end()` method `.expect()` assertions that fail will
|
54 | not throw - they will return the assertion as an error to the `.end()` callback. In
|
55 | order to fail the test case, you will need to rethrow or pass `err` to `done()`, as follows:
|
56 |
|
57 | ```js
|
58 | describe('GET /users', function(){
|
59 | it('respond with json', function(done){
|
60 | request(app)
|
61 | .get('/user')
|
62 | .set('Accept', 'application/json')
|
63 | .expect(200)
|
64 | .end(function(err, res){
|
65 | if (err) return done(err);
|
66 | done()
|
67 | });
|
68 | })
|
69 | })
|
70 | ```
|
71 |
|
72 | Anything you can do with superagent, you can do with supertest - for example multipart file uploads!
|
73 |
|
74 | ```js
|
75 | request(app)
|
76 | .post('/')
|
77 | .attach('avatar', 'test/fixtures/homeboy.jpg')
|
78 | ...
|
79 | ```
|
80 |
|
81 | Passing the app or url each time is not necessary, if you're testing
|
82 | the same host you may simply re-assign the request variable with the
|
83 | initialization app or url, a new `Test` is created per `request.VERB()` call.
|
84 |
|
85 | ```js
|
86 | request = request('http://localhost:5555');
|
87 |
|
88 | request.get('/').expect(200, function(err){
|
89 | console.log(err);
|
90 | });
|
91 |
|
92 | request.get('/').expect('heya', function(err){
|
93 | console.log(err);
|
94 | });
|
95 | ```
|
96 |
|
97 | ## API
|
98 |
|
99 | You may use any [super-agent](http://github.com/visionmedia/superagent) methods,
|
100 | including `.write()`, `.pipe()` etc and perform assertions in the `.end()` callback
|
101 | for lower-level needs.
|
102 |
|
103 | ### .expect(status[, fn])
|
104 |
|
105 | Assert response `status` code.
|
106 |
|
107 | ### .expect(status, body[, fn])
|
108 |
|
109 | Assert response `status` code and `body`.
|
110 |
|
111 | ### .expect(body[, fn])
|
112 |
|
113 | Assert response `body` text with a string, regular expression, or
|
114 | parsed body object.
|
115 |
|
116 | ### .expect(field, value[, fn])
|
117 |
|
118 | Assert header `field` `value` with a string or regular expression.
|
119 |
|
120 | ### .end(fn)
|
121 |
|
122 | Perform the request and invoke `fn(err, res)`.
|
123 |
|
124 | ## Notes
|
125 |
|
126 | Inspired by [api-easy](https://github.com/flatiron/api-easy) minus vows coupling.
|
127 |
|
128 | ## License
|
129 |
|
130 | MIT
|