Supertest

Common errors

• Error: expected 200 "OK", got 404 "Not Found"

  cause The tested API endpoint returned a 404 status code (or another unexpected non-2xx status) which was not explicitly expected by `.expect()`.
  fix Verify that the API route is correctly implemented and accessible. If a 404 (or other non-2xx) is expected, add `.expect(404)` to your Supertest chain.

• TypeError: app.address is not a function

  cause The `request()` function was called with an argument that is not a valid `http.Server` instance or an Express/Koa application function.
  fix Ensure you are passing either an instance of an `http.Server` (e.g., `http.createServer(app)`) or a valid application function (e.g., `express()`) directly to `request()`.

• ReferenceError: request is not defined

  cause The `supertest` module was not correctly imported or required in the test file.
  fix Add `import request from 'supertest';` (for ESM) or `const request = require('supertest');` (for CommonJS) at the top of your test file.

• Error: done() called multiple times

  cause The asynchronous `done()` callback for a test was invoked more than once, often due to calling it in both an `.expect()` assertion and the `.end()` callback, or multiple times within a single callback.
  fix Ensure `done()` is called only once per test. If passing `done` to `.expect()`, omit it from `.end()`. If using `.end()`, only call `done(err)` or `done()` there.

Warnings

• gotcha Supertest (via SuperAgent) treats non-2xx HTTP responses as errors and passes them to the callback's first argument, unless you explicitly assert the expected status code using `.expect(statusCode)`.
  Fix: Always use `.expect(statusCode)` if you anticipate non-2xx responses (e.g., `.expect(404)` for 'Not Found') to prevent them from being treated as errors and passed to your callback.
• gotcha When using the `.end()` method, failed `.expect()` assertions will not throw errors directly. Instead, they will be returned as the `err` argument to the `.end()` callback.
  Fix: Ensure you handle the `err` argument in your `.end()` callback (e.g., `if (err) throw err;` or `done(err);`) to properly fail your test cases when assertions within the chain fail.
• breaking Supertest v7.0.0 and later no longer support Node.js versions earlier than 14.16.0.
  Fix: Upgrade your Node.js environment to version 14.16.0 or higher to use Supertest v7 and above. The currently recommended minimum is 14.18.0.
• gotcha Automatic server closing behavior, which was present in some earlier v7 versions, was reverted in v7.1.3. This means you are responsible for managing the server's lifecycle in your tests.
  Fix: Ensure your test setup and teardown explicitly manage the HTTP server's lifecycle, for example, by calling `server.close()` in an `afterAll` or `afterEach` hook if you are manually creating HTTP servers.

Install

• npm install supertest npm
• yarn add supertest yarn
• pnpm add supertest pnpm

Imports

• request

  import request from 'supertest';

Quickstart

Demonstrates a basic GET request to an Express application, asserting response headers, content length, and status code without a dedicated test framework.

import request from 'supertest';
import express from '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) {
      console.error(err);
      // In a test environment, you would typically use a test runner's fail method here
      // e.g., done(err) for Mocha
    }
    console.log('Test successful:', res.body);
  });