# Supertest — HTTP Assertion Library for Node.js APIs

> Supertest provides a high-level API for testing HTTP servers in Node.js with fluent assertion chaining.

## Install

Save as a script file and run:

# Supertest — HTTP Assertion Library for Node.js APIs

## Quick Use
```bash
npm install --save-dev supertest
```
```javascript
const request = require('supertest');
const app = require('../app');

describe('GET /users', () => {
  it('responds with JSON', async () => {
    await request(app)
      .get('/users')
      .expect('Content-Type', /json/)
      .expect(200);
  });
});
```

## 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

---
Source: https://tokrepo.com/en/workflows/fd0b0e5d-4277-11f1-9bc6-00163e2b0d79
Author: Script Depot