supertest

Supertest is a JavaScript library for testing web server endpoints in Node.js applications. When you build an HTTP server, a web API, or a backend service, you need a way to verify that each route actually responds correctly: that it returns the right status code, the right data format, and the right content. Supertest lets you write those checks in code so they can be run automatically every time you make a change.

The library works by letting you describe an HTTP request in plain, readable steps and then immediately assert what the response should look like. For example, you can say "make a GET request to the /user route, and I expect a 200 status code and a JSON response." If the server returns something different, the test fails and tells you what went wrong. This style of chaining steps together, where each method call leads naturally into the next, is sometimes called a fluent API.

Supertest is built on top of another library called superagent, which handles the mechanics of sending HTTP requests. Supertest adds the assertion layer on top: the ability to declare what you expect and have the test fail automatically if reality does not match. You can check status codes, response headers, response body content, cookies, and more. It also supports file uploads, authentication headers, persistent sessions across multiple requests, and the newer HTTP/2 protocol.

The library works alongside any test framework you already use, such as Mocha, Jest, or others, and it supports both the older callback style of handling results and the modern promise and async/await styles that most new JavaScript code uses. You pass your server (or just the URL of a running server) to supertest, and it temporarily starts listening on an available port if the server is not already running, so you do not have to manage port configuration in your tests. The project is currently maintained by the Forward Email organization.