Supertest

Expectations in supertest are executed in the order they are defined. This allows you to use a custom .expect(fn) to modify the response object (e.g., normalizing data) before subsequent assertions run.

request(app)
  .post('/user')
  .send('name=john')
  .expect(function(res) {
    // Modify response before next assertion
    res.body.id = 'some fixed id';
    res.body.name = res.body.name.toLowerCase();
  })
  .expect(200, {
    id: 'some fixed id',
    name: 'john'
  }, done);

Install supertest as a development dependency using npm:

npm install supertest --save-dev

Supertest provides a cookies utility to assert the presence, absence, and properties of cookies in HTTP responses. You can access these assertions via request.cookies and pass them into the .expect() method of a Supertest chain. Assertions are chainable.

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

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(200)
  .expect(cookies.set({ name: 'alpha', options: ['domain', 'path', 'httponly'] }))
  .expect(cookies.not('set', { name: 'bravo' }))
  .end(function(err, res) {
    if (err) throw err;
  });

Use request.agent(app) to create an agent that persists cookies across multiple requests. This is essential for testing authenticated sessions or workflows where one request sets a cookie and a subsequent request relies on it.

const agent = request.agent(app);

// This request sets a cookie
agent.get('/').expect('set-cookie', 'cookie=hey; Path=/', done);

// This request will automatically send the cookie back
agent.get('/return').expect('hey', done);

Supertest provides a high-level abstraction for testing HTTP by wrapping superagent. You can pass an http.Server or a Function (like an Express app) to request(). If the server is not already listening, supertest automatically binds it to an ephemeral port.

To enable the HTTP/2 protocol, pass an options object with { http2: true } to request() or request.agent().

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

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

// Basic usage
request(app)
  .get('/user')
  .expect('Content-Type', /json/)
  .expect(200)
  .end((err, res) => {
    if (err) throw err;
  });

// Enabling HTTP/2
request(app, { http2: true })
  .get('/user')
  .expect(200)
  .end((err, res) => {
    if (err) throw err;
  });

The cookies([secret], [asserts]) function returns an assertion function for use with .expect().

• secret: A String or array of strings used for cookie signature secrets. Required if testing signed cookies.
• asserts(req, res): A function or array of functions. If a custom assertion fails, it should throw an error.

const cookies = request.cookies(secret, asserts);

You can instruct TestAgent to use HTTP/2 by passing http2: true in the options object during initialization. This will cause the agent to wrap your application in an http2.createServer() instance.

Note: This requires a version of Node.js that supports the http2 module. If the module is unavailable, an error will be thrown: supertest: this version of Node.js does not support http2.

const request = require('supertest');
const app = require('./app');

// Initialize agent with HTTP/2 enabled
const agent = request.agent(app, { http2: true });

The .expect() method is used to assert various parts of the HTTP response. Assertions are run in the order defined.

// Assert response status code
.expect(status)
.expect(status, fn)

// Assert status code and body
.expect(status, body)
.expect(status, body, fn)

// Assert response body (string, regex, or object)
.expect(body)
.expect(body, fn)

// Assert header field and value
.expect(field, value)
.expect(field, value, fn)

// Custom assertion function
.expect(function(res) {
  // If check fails, throw an error
  if (!('next' in res.body)) throw new Error("missing next key");
})

The .end(fn) method performs the request and invokes the provided callback function with fn(err, res). If assertions fail, the error is passed as the first argument to the callback.

request(app)
  .get('/user')
  .expect(200)
  .end(function(err, res) {
    // err contains assertion failures or network errors
    // res contains the response object
  });