supertest
A Node.js library for writing HTTP tests against your server with a chainable API.
- Stars
- 14.4k
- Forks
- 788
- Licence
- MIT
- Language
- JavaScript
- Last update
- 7 days ago
- Type
- Library
What it is
Supertest is a JavaScript library that lets you send requests to a Node.js HTTP server and check the responses, such as status codes, headers, and body content, in your automated tests. It uses a chainable style built on top of the superagent request library. You can pass it an Express-style app or a URL, and it handles starting a temporary server for you when needed.
- Check that a GET /user route returns status 200 and JSON content type
- Test a login flow by saving cookies with request.agent and sending them on later requests
- Test a multipart file upload endpoint using .field() and .attach()
- Write async/await or Promise-based tests that assert on the response object
Great for
- Node.js developers who want to test their HTTP routes or API endpoints
- Teams using Express or another Node.js HTTP framework with a test runner like Mocha
- Developers who want to check headers, cookies, or response bodies in one readable chain
- Projects that need to test file uploads or cookie-based sessions
Not ideal for
- People who are not writing or testing Node.js code, since it is only for Node.js HTTP servers
- Those who need full browser-based end-to-end testing, because the README describes HTTP-level testing rather than browser automation
- Projects that need a test framework of their own, since the README says it works with any framework but does not include one
How to get it
- 1
Install with a package manager
You'll need: Node.js · npm
Install as a dev dependency
npm install supertest --save-dev - 2
Run it
- Install supertest with npm install supertest --save-dev
- Require it in a test file with const request = require('supertest');
- Pass your Express app or server to request(app) and chain a request such as .get('/user')
- Add .expect(200) or other assertions and run your test runner, such as mocha
- 3
Get the most out of it
- Use request.agent(app) to keep cookies across several requests, as shown in the README cookie example
- Pass { http2: true } as a second argument to request or request.agent to test over HTTP/2
- Use a custom function in .expect(function(res) {}) for checks that are not covered by built-in assertions
- Use .expect() calls in order to modify the response before a later assertion, as the README describes
Downloads
Strengths
- Simple chainable API that reads close to the request being tested
- Works with any test framework, according to the README, and with mocha examples shown
- Starts an ephemeral port automatically, so you do not need to manage ports
Trade-offs
- Assertion failures in the .end() callback do not throw on their own, so you must pass errors to done() or rethrow them, which is easy to get wrong
- Documentation in the README is brief and the API section is short, so some behavior needs to be checked in superagent docs
- The README is truncated, so details about the full feature set are not fully visible
How it compares
| Project | Stars | Type | Level | Updated | Best for |
|---|---|---|---|---|---|
| supertest (this) | 14.4k | Library | beginner | 7 days ago | Node.js developers who want to test their HTTP routes or API endpoints |
| superagent | 16.6k | Library | beginner | 1 months ago | JavaScript developers who want one HTTP client API that works in both Node.js and browsers |
| axios | 109k | Library | beginner | 4 days ago | JavaScript developers calling REST or other HTTP APIs from a browser front end |
| validator.js | 23.7k | Library | beginner | 2 months ago | JavaScript developers validating form or API input on Node.js |
| apollo-server | 14k | Library | intermediate | 5 days ago | Node.js developers who want to add a GraphQL API to an existing Express, Koa or Hapi app |
| http-proxy-middleware | 11.1k | Library | intermediate | 5 days ago | Node.js developers running an Express, Connect, or Next.js dev server who need to forward /api requests to a backend |
Stats synced from GitHub. The assessment above was drafted with AI from the project's README on 2026-10-29 and may miss recent changes — check the README before relying on a command. MIT licence: free to use, modify and distribute, including commercially, as long as you keep the copyright notice.