Supertest — HTTP Assertion Library for Node.js APIs

Introduction

Supertest is a Node.js library that wraps superagent to provide a fluent API for testing HTTP endpoints. It binds an Express, Koa, or raw http.Server instance to an ephemeral port, sends requests, and asserts on status codes, headers, and bodies without requiring a running server process.

What Supertest Does

• Starts an HTTP server on a random port and sends requests against it
• Chains assertions for status codes, headers, and response bodies
• Works with any framework that produces a Node.js http.Server
• Supports file uploads, cookies, and custom request headers
• Returns promises for async/await usage in modern test runners

Architecture Overview

Supertest takes an http.Server or an Express app and calls .listen(0) to bind to an OS-assigned port. It then delegates request construction to superagent, adding .expect() methods that queue assertions. When the request completes, queued assertions run in order against the response object. The server closes automatically after each test block, preventing port leaks.

Self-Hosting & Configuration

• Install as a dev dependency alongside your test runner (Jest, Mocha, Vitest)
• Pass your Express or Koa app directly: request(app) handles server lifecycle
• Set custom headers with .set('Authorization', 'Bearer token') per request
• Use .send() to include JSON or form data in POST/PUT requests
• Chain multiple .expect() calls for status, headers, and body checks

Key Features

• Zero-config server binding eliminates manual listen/close boilerplate
• Fluent chainable API reads naturally: .get().set().expect().expect()
• Works with any Node.js HTTP framework through the standard server interface
• Promise-based responses integrate cleanly with async test patterns
• Lightweight with minimal dependencies beyond superagent

Comparison with Similar Tools

• Axios + assertions — manual setup for each request; Supertest handles server lifecycle automatically
• node-fetch — lower-level HTTP client; Supertest adds assertion chaining and server binding
• Hurl — file-based HTTP testing; Supertest is programmatic within JavaScript test suites
• Pactum — broader API testing with contracts; Supertest focuses on simple HTTP assertions
• Frisby.js — REST API testing with Jasmine; Supertest is framework-agnostic and more widely adopted

FAQ

Q: Does Supertest work with Fastify? A: Yes. Pass the Fastify server instance after calling await app.ready() to ensure routes are registered.

Q: Can I reuse cookies across requests? A: Use const agent = request.agent(app) to maintain a cookie jar across chained requests.

Q: How do I test WebSocket endpoints? A: Supertest is HTTP-only. Use ws or socket.io-client alongside Supertest for WebSocket testing.

Q: Does Supertest support HTTPS? A: Yes. Pass an https.Server instance and Supertest will make requests over TLS.

Sources

• https://github.com/ladjs/supertest
• https://www.npmjs.com/package/supertest