Freedom251 › API Testing Tools
SuperTest
What SuperTest is
SuperTest is a free, MIT-licensed library for testing HTTP servers built with Node.js. It provides a fluent way to make requests and check responses while retaining access to SuperAgent’s lower-level API. Supply an HTTP server or a function to `request()`; if the server is not listening, SuperTest binds it to an ephemeral port. Assertions can check response status, body, and headers, or run custom functions. The project says it works with any test framework and includes a Mocha example. Its examples show callback, promise, and async/await request styles. Options passed to `request()` or `request.agent()` enable HTTP/2, and SuperAgent methods include multipart uploads using `.field()` and `.attach()`. `request.agent()` can preserve cookies between requests, and the documentation covers cookie assertions. The repository instructs users to install SuperTest as an npm development dependency with `npm install supertest --save-dev`. One testing detail to account for: when using `.end()`, failed `.expect()` assertions reach the callback as an error, which must be rethrown or passed to the test’s `done()` callback to fail the test. The security policy directs vulnerability reports to email rather than public GitHub issues, discussions, or pull requests.
Who it suits
SuperTest suits developers testing Node.js HTTP servers who want to make requests and assert on responses within their chosen test framework. Its callback, promise, and async/await examples support different asynchronous styles.
What it does well
- Works with any test framework.
- Assertions cover status, body, headers, and custom functions.
- Supports HTTP/2 and multipart uploads.
- Includes cookie persistence through `request.agent()`.
What to know first
- Failed `.expect()` errors in `.end()` callbacks need explicit handling.
- Installation is listed as an npm development dependency.
Plans
| Plan | Billed and limits | Price |
|---|---|---|
| MIT-licensed open-source library | Node.js HTTP server testing library | Free |
As github.com lists them, read 5 Oct 2026. The maker's own page has the final word.
Verdict
SuperTest provides HTTP request and response checks alongside access to SuperAgent methods. Developers using `.end()` should handle assertion errors in the callback so test failures are reported.
Facts from SuperTest's own pages
- Assertions
- The API supports assertions on response status, body, headers, and custom assertion functions. · github.com, 11 Oct 2026
- Async styles
- Examples show callback, promise, and async/await usage. · github.com, 11 Oct 2026
- Async usage
- The examples show callback, promise, and async/await styles for making requests and checking responses. · github.com, 5 Oct 2026
- HTTP assertions
- It provides a high-level abstraction for HTTP testing while allowing use of SuperAgent’s lower-level API. · github.com, 11 Oct 2026
- Install
- The README instructs users to install SuperTest from npm with npm install supertest --save-dev. · github.com, 11 Oct 2026
- Installation
- The README says to install it as an npm development dependency with `npm install supertest --save-dev`. · github.com, 5 Oct 2026
- License
- The repository identifies the project as MIT licensed; the license grants permission to use, copy, modify, publish, distribute, sublicense, and sell copies subject to its conditions. · github.com, 11 Oct 2026
- Maintainer
- The repository says SuperTest is maintained for Forward Email and several other projects, including Lad, Spam Scanner, Bree, Cabin, and Lass. · github.com, 5 Oct 2026
- Maintainers
- The repository says SuperTest is maintained for Forward Email, Lad, Spam Scanner, Bree, Cabin, and Lass. · github.com, 11 Oct 2026
- Noted limitation
- When using .end(), failed .expect() assertions are delivered as an error to the callback and must be rethrown or passed to the test’s done() callback to fail the test. · github.com, 11 Oct 2026
- Persistent cookies
- request.agent() can persist cookies between requests, and the README documents cookie assertions. · github.com, 11 Oct 2026
- Protocol
- The README shows enabling HTTP/2 by passing {"http2":true} to request() or request.agent(). · github.com, 11 Oct 2026
- Purpose
- SuperTest is a library for testing Node.js HTTP servers with a fluent API. · github.com, 11 Oct 2026
- Security reporting
- The security policy asks reporters to email [email protected] and says a bug bounty may be awarded at the maintainers’ discretion depending on severity. · github.com, 11 Oct 2026
- Server setup
- You can pass an HTTP server or a function to request(), and SuperTest binds a server that is not already listening to an ephemeral port. · github.com, 11 Oct 2026
- SuperAgent features
- The README says SuperAgent methods such as write() and pipe() are available, including multipart file uploads. · github.com, 11 Oct 2026
- Target use
- The project describes itself as a library for testing Node.js HTTP servers with a fluent API. · github.com, 5 Oct 2026
- Test frameworks
- The README says SuperTest works with any test framework and demonstrates Mocha usage. · github.com, 11 Oct 2026
Where SuperTest stands on Freedom251
- API Testing Tools#31 of 34