> For the complete documentation index, see [llms.txt](https://tdd.shujuwajue.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tdd.shujuwajue.com/ju-ti-shi-jian/javascript-ce-shi-kuang-jia/supertest.md).

# SuperTest

[supertest- npm 地址](https://www.npmjs.com/package/supertest)

[supertest - github 地址](https://github.com/visionmedia/supertest#readme)

使用可以[superagent](http://github.com/visionmedia/superagent) 可以很容易的进行HTTP断言。

## 关于

该模块的初衷是提供用于测试HTTP的高级抽象，同时仍然允许您使用超级代理提供的低级API（[lower-level API](https://visionmedia.github.io/superagent/)）。

## 入门

通过npm安装，并且作为一个development依赖保存到`composer.json`。

```
npm install supertest --save-dev
```

一旦安装，现在可以通过简单调用`require('supertest');`来引用；

## 例子

您可以传递一个http.Server或者一个Function to request()——如果服务器还没有侦听连接，那么它将被绑定到一个临时端口，因此不需要跟踪端口。

SuperTest 与任何测试框架一起工作，这里是一个不使用任何测试框架的例子：

```javascript
const request = require('supertest');
const express = require('express');

const app = express();

app.get('/user', function(req, res) {
  res.status(200).json({ name: 'john' });
});

request(app)
  .get('/user')
  .expect('Content-Type', /json/)
  .expect('Content-Length', '15')
  .expect(200)
  .end(function(err, res) {
    if (err) throw err;
  });
```

这里有一个mocha的例子，请注意如何直接传递到任何一个`.expect()`调用：

```javascript
describe('GET /user', function() {
  it('respond with json', function(done) {
    request(app)
      .get('/user')
      .set('Accept', 'application/json')
      .expect('Content-Type', /json/)
      .expect(200, done);
  });
});
```

上面的语句需要注意的一点是，如果未添加状态代码.（即`.expect(302)`），则SuperTest 现在将任何HTTP错误（除了2XX响应代码之外的任何错误）作为第一个参数发送到回调。

如果您使用的是.end()方法`.expect()`断言，如果失败，则不会抛出，而是将断言作为错误返回到.end()回调。为了使测试用例失败，您需要重新发送或传递 `err`给D`done()`，如下：

```javascript
describe('POST /users', function() {
  it('responds with json', function(done) {
    request(app)
      .post('/users')
      .send({name: 'john'})
      .set('Accept', 'application/json')
      .expect(200)
      .end(function(err, res) {
        if (err) return done(err);
        done();
      });
  });
});
```

你也可以使用promises:

```javascript
describe('GET /users', function() {
  it('responds with json', function() {
    return request(app)
      .get('/users')
      .set('Accept', 'application/json')
      .expect(200)
      .then(response => {
          assert(response.body.email, 'foo@bar.com')
      })
  });
});
```

期望是按照定义的顺序运行的。此特性可用于在执行断言之前修改响应体或头。

```javascript
describe('POST /user', function() {
  it('user.name should be an case-insensitive match for "john"', function(done) {
    request(app)
      .post('/user')
      .send('name=john') // x-www-form-urlencoded upload
      .set('Accept', 'application/json')
      .expect(function(res) {
        res.body.id = 'some fixed id';
        res.body.name = res.body.name.toLowerCase();
      })
      .expect(200, {
        id: 'some fixed id',
        name: 'john'
      }, done);
  });
});
```

你可以用 superagent 做任何的事情，你可以用supertest——例如文件上传！

```javascript
request(app)
.post('/')
.field('name', 'my awesome avatar')
.attach('avatar', 'test/fixtures/avatar.jpg')
```

不必每次都传递应用程序或url，如果正在测试同一主机，则可以简单地用初始化应用程序或url重新分配请求变量，则每个`request.VERB()`调用都会创建一个新的Test。

```javascript
request = request('http://localhost:5555');

request.get('/').expect(200, function(err){
  console.log(err);
});

request.get('/').expect('heya', function(err){
  console.log(err);
});
```

下面是一个Moka的例子，展示了如何坚持一个请求及其cookies：

```javascript
const request = require('supertest');
const should = require('should');
const express = require('express');
const cookieParser = require('cookie-parser');

describe('request.agent(app)', function() {
  const app = express();
  app.use(cookieParser());

  app.get('/', function(req, res) {
    res.cookie('cookie', 'hey');
    res.send();
  });

  app.get('/return', function(req, res) {
    if (req.cookies.cookie) res.send(req.cookies.cookie);
    else res.send(':(')
  });

  const agent = request.agent(app);

  it('should save cookies', function(done) {
    agent
    .get('/')
    .expect('set-cookie', 'cookie=hey; Path=/', done);
  });

  it('should send cookies', function(done) {
    agent
    .get('/return')
    .expect('hey', done);
  });
})
```

文件[ agency.js](https://github.com/visionmedia/superagent/blob/master/test/node/agency.js) 引入了另一个示例。

## API

可以使用任何[ superagent](http://github.com/visionmedia/superagent) 方法，包括`.write()`,`.pipe()`等，并在`.end()`回调中执行断言以满足较低级别的需要。

### .expect(status\[, fn])

断言响应状态代码。

### .expect(status, body\[, fn])

断言响应状态代码和body。

#### .expect(body\[, fn])

用字符串、正则表达式或解析body对象来断言响应`body`text。

### .expect(field, value\[, fn])

用字符串或正则表达式断言header头的`field value`。

### .expect(function(res) {})

传递自定义断言函数。它将给出检查的响应对象。如果检查失败，则抛出错误。

```javascript
request(app)
  .get('/')
  .expect(hasPreviousAndNextKeys)
  .end(done);

function hasPreviousAndNextKeys(res) {
  if (!('next' in res.body)) throw new Error("missing next key");
  if (!('prev' in res.body)) throw new Error("missing prev key");
}
```

### .end(fn)

执行请求并调用`fn(err, res)`。

## 笔记

灵感来自[ api-easy](https://github.com/flatiron/api-easy)。

## 资料

[接口自动化 开源框架学习-supertest](https://blog.csdn.net/lichao330530/article/details/51907075)

[How to Test Your API With Supertest](https://willi.am/blog/2014/07/28/test-your-api-with-supertest/)