supertest

通过 superagent 轻松实现 HTTP 断言。由 Forward Email 和 Lad 维护。

关于

本模块的初衷是为测试 HTTP 提供高层次的抽象，同时仍然允许你回退到 superagent 提供的低层次 API。

快速开始

将 supertest 作为 npm 模块安装，并将其保存为开发依赖项到你的 package.json 文件中：

npm install supertest --save-dev

安装完成后，只需调用 require('supertest'); 即可引用它。

示例

你可以将 http.Server 或 Function 传递给 request() —— 如果服务器尚未开始监听连接，它会为你绑定到一个临时端口，因此无需手动管理端口号。

supertest 可以与任何测试框架配合使用，以下是一个完全不依赖测试框架的示例：

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;
  });

要启用 HTTP/2 协议，只需在 request 或 request.agent 中添加一个选项即可：

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, { http2: true })
  .get('/user')
  .expect('Content-Type', /json/)
  .expect('Content-Length', '15')
  .expect(200)
  .end(function(err, res) {
    if (err) throw err;
  });

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

以下是使用 Mocha 的示例，请注意，你可以直接将 done 回调函数传递给任意 .expect() 调用：

describe('GET /user', function() {
  it('响应 JSON 数据', function(done) {
    request(app)
      .get('/user')
      .set('Accept', 'application/json')
      .expect('Content-Type', /json/)
      .expect(200, done);
  });
});

你可以使用 auth 方法来传递 HTTP 用户名和密码，方式与 superagent 相同：

describe('GET /user', function() {
  it('响应 JSON 数据', function(done) {
    request(app)
      .get('/user')
      .auth('username', 'password')
      .set('Accept', 'application/json')
      .expect('Content-Type', /json/)
      .expect(200, done);
  });
});

需要注意的是，如果未添加状态码断言（例如 .expect(302)），superagent 现在会将所有 HTTP 错误（即非 2XX 响应码）作为第一个参数传递给回调函数。

如果你使用 .end() 方法，失败的 .expect() 断言不会抛出错误；它们会将断言结果作为错误对象返回给 .end() 回调。为了使测试用例失败，你需要重新抛出错误或将 err 传递给 done()，如下所示：

describe('POST /users', function() {
  it('响应 JSON 数据', function(done) {
    request(app)
      .post('/users')
      .send({name: 'john'})
      .set('Accept', 'application/json')
      .expect('Content-Type', /json/)
      .expect(200)
      .end(function(err, res) {
        if (err) return done(err);
        return done();
      });
  });
});

你也可以使用 Promise：

describe('GET /users', function() {
  it('响应 JSON 数据', function() {
    return request(app)
      .get('/users')
      .set('Accept', 'application/json')
      .expect('Content-Type', /json/)
      .expect(200)
      .then(response => {
         expect(response.body.email).toEqual('foo@bar.com');
      })
  });
});

或者使用 async/await 语法：

describe('GET /users', function() {
  it('响应 JSON 数据', async function() {
    const response = await request(app)
      .get('/users')
      .set('Accept', 'application/json')
    expect(response.headers["content-type"]).toMatch(/json/);
    expect(response.status).toEqual(200；
    expect(response.body.email).toEqual('foo@bar.com');
  });
});

断言会按照定义的顺序依次执行。这一特性可用于在执行断言之前修改响应体或响应头。

describe('POST /user', function() {
  it('用户名称应为不区分大小写的 "john"', function(done) {
    request(app)
      .post('/user')
      .send('name=john') // x-www-form-urlencoded 格式上传
      .set('Accept', 'application/json')
      .expect(function(res) {
        res.body.id = '某个固定 ID';
        res.body.name = res.body.name.toLowerCase();
      })
      .expect(200, {
        id: '某个固定 ID',
        name: 'john'
      }, done);
  });
});

凡是 superagent 能做到的事情，supertest 也能做到——例如多部分文件上传！

request(app)
  .post('/')
  .field('name', '我的超赞头像')
  .field('complex_object', '{"attribute": "value"}', {contentType: 'application/json'})
  .attach('avatar', 'test/fixtures/avatar.jpg')
  ...

每次都不必重复传递应用实例或 URL；如果你测试的是同一台主机，只需将 request 变量重新赋值为初始的应用实例或 URL 即可，每次调用 request.VERB() 都会创建一个新的测试对象。

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

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

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

以下是使用 Mocha 的示例，展示了如何保持请求及其 Cookie 的持久性：

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('应该保存 Cookie', function(done) {
    agent
    .get('/')
    .expect('set-cookie', 'cookie=hey; Path=/', done);
  });

  it('应该发送 Cookie', function(done) {
    agent
    .get('/return')
    .expect('hey', done);
  });
});

还有一个由文件 agency.js 引入的示例。

以下是一个在请求中设置两个 Cookie 的示例：

agent(app)
  .get('/api/content')
  .set('Cookie', ['nameOne=valueOne;nameTwo=valueTwo'])
  .send()
  .expect(200)
  .end((err, res) => {
    if (err) {
      return done(err);
    }
    expect(res.text).to.be.equal('hey');
    return done();
  });

API

你可以使用任何 superagent 的方法，包括 .write()、.pipe() 等，并在 .end() 回调中进行低层次的断言。

.expect(status[, fn])

断言响应的状态码。

.expect(status, body[, fn])

断言响应的状态码和响应体。

.expect(body[, fn])

断言响应体文本，可以是字符串、正则表达式或解析后的对象。

.expect(field, value[, fn])

断言响应头中的字段值，可以是字符串或正则表达式。

.expect(function(res) {})

传递一个自定义断言函数。该函数会接收响应对象进行检查。如果检查失败，抛出错误。

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)。

Cookies

以下是使用 set 和 not cookie 断言的示例：

// 设置 super-test
const request = require('supertest');
const express = require('express');
const cookies = request.cookies;

// 设置 express 测试服务
const app = express();

app.get('/users', function(req, res) {
  res.cookie('alpha', 'one', { domain: 'domain.com', path: '/', httpOnly: true });
  res.send(200, { name: 'tobi' });
});

// 向服务发送测试请求
request(app)
  .get('/users')
  .expect('Content-Type', /json/)
  .expect('Content-Length', '15')
  .expect(200)
  // 断言 'alpha' cookie 已设置，并且具有 domain、path 和 httpOnly 选项
  .expect(cookies.set({ name: 'alpha', options: ['domain', 'path', 'httponly'] }))
  // 断言 'bravo' cookie 未被设置
  .expect(cookies.not('set', { name: 'bravo' }))
  .end(function(err, res) {
    if (err) {
      throw err;
    }
  });

也可以链式调用断言：

cookies.set({/* ... */}).not('set', {/* ... */})

Cookie 断言

函数和方法可以链式调用。

cookies([secret], [asserts])

获取用于 super-test .expect() 方法的断言函数。

参数

• secret - 字符串或字符串数组。Cookie 签名密钥。
• asserts(req, res) - 函数或函数数组。自定义断言失败时应抛出错误。

.set(expects, [assert])

断言 cookie 及其选项已设置。

参数

• expects - 对象或对象数组。
  • name - Cookie 的名称（字符串）。
  • options - 可选 的选项数组。
• assert - 可选 的“断言为真”修饰符。默认值：true。

.reset(expects, [assert])

断言 cookie 已设置，并且之前已经设置过（在请求头中）。

参数

• expects - 对象或对象数组。
  • name - Cookie 的名称（字符串）。
• assert - 可选 的“断言为真”修饰符。默认值：true。

.new(expects, [assert])

断言 cookie 已设置，但之前未设置过（不在请求头中）。

参数

• expects - 对象或对象数组。
  • name - Cookie 的名称（字符串）。
• assert - 可选 的“断言为真”修饰符。默认值：true。

.renew(expects, [assert])

断言 cookie 的 expires 或 max-age 值严格大于给定的值。

参数

• expects - 对象或对象数组。
  • name - Cookie 的名称（字符串）。
  • options - 选项对象。需从以下两个选项中选择其一：
    • options.expires - 原始 cookie 的 UTC 到期时间（在请求头中）。
    • options.max-age - 原始 cookie 的存活时间（以秒为单位，也在请求头中）。
• assert - 可选 的“断言为真”修饰符。默认值：true。

.contain(expects, [assert])

断言 cookie 已设置，并且包含指定的选项。

如果 cookie 是签名的，则需要先初始化 cookies(secret)。

参数

• expects - 对象或对象数组。
  • name - Cookie 的名称（字符串）。
  • value - 可选 的 unsigned cookie 值（字符串）。
  • options - 可选 的选项对象。
    • options.domain - 可选 的域名。
    • options.path - 可选 的路径。
    • options.expires - 可选 的 UTC 到期时间。
    • options.max-age - 可选 的存活时间（以秒为单位）。
    • options.secure - 可选 的安全标志。
    • options.httponly - 可选 的 httpOnly 标志。
• assert - 可选 的“断言为真”修饰符。默认值：true。

.not(method, expects)

调用任何 cookie 断言方法，并将“断言为真”修饰符设为 false。

语法糖。

参数

• method - 字符串方法名。方法名对应的参数适用于 expects。
• expects - 对象或对象数组。
  • name - Cookie 的名称（字符串）。
  • value - 可选 的 unsigned cookie 值（字符串）。
  • options - 可选 的选项对象。

注释

灵感来自 api-easy，去除了与 vows 的耦合。

许可证

MIT

Supertest 快速上手指南

Supertest 是一个基于 superagent 的高层抽象库，专为测试 HTTP 服务而生。它允许你轻松编写断言，同时保留访问底层 API 的能力，完美适配 Express、Koa 等 Node.js Web 框架。

环境准备

• 系统要求：Node.js (推荐 LTS 版本)
• 前置依赖：
  • 一个已初始化的 Node.js 项目 (package.json)
  • 待测试的 Web 应用（如 Express app 实例）或正在运行的 HTTP 服务地址
  • 可选：测试运行器（如 Mocha, Jest, Vitest 等），虽然 Supertest 也可独立运行

安装步骤

使用 npm 将 supertest 安装为开发依赖：

npm install supertest --save-dev

国内加速提示：如果下载速度较慢，可配置淘宝镜像源：

npm config set registry https://registry.npmmirror.com
npm install supertest --save-dev

基本使用

Supertest 可以直接接收一个 Express app 实例或一个 URL 字符串。以下是最基础的用法示例，展示了如何发起请求并进行状态码和响应内容的断言。

1. 基础示例（无测试框架）

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

// 创建一个简单的 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(200)
  .end(function(err, res) {
    if (err) throw err;
    console.log('测试通过！');
  });

2. 结合 Mocha 使用

在实际项目中，通常配合 Mocha 等测试框架使用。你可以直接将 done 回调传递给 .expect() 或 .end()。

const request = require('supertest');
const app = require('../app'); // 引入你的应用

describe('GET /user', function() {
  it('应返回 JSON 数据', function(done) {
    request(app)
      .get('/user')
      .set('Accept', 'application/json')
      .expect('Content-Type', /json/)
      .expect(200, done); // 自动处理完成信号
  });
});

3. 使用 async/await (现代写法)

如果你使用的是支持 Promise 的测试框架（如 Jest 或新版 Mocha），可以使用 async/await 语法，代码更简洁：

describe('GET /users', function() {
  it('应返回用户数据', async function() {
    const response = await request(app)
      .get('/users')
      .set('Accept', 'application/json')
      .expect(200);
    
    // 使用断言库进行详细检查
    expect(response.body.email).toEqual('foo@bar.com');
    expect(response.headers["content-type"]).toMatch(/json/);
  });
});

4. 高级功能：保持会话 (Cookie)

如果需要测试涉及登录状态或 Cookie 的场景，可以使用 request.agent() 来自动管理 Cookie。

const agent = request.agent(app);

// 第一次请求：登录并保存 Cookie
await agent
  .post('/login')
  .send({ username: 'test', password: '123' })
  .expect(200);

// 第二次请求：自动携带之前的 Cookie
await agent
  .get('/profile')
  .expect(200)
  .then(res => {
    console.log('已登录用户:', res.body.name);
  });