supertest npm is safe for the job it is built for, testing HTTP servers, provided you keep it strictly as a devDependency and stay on a current release such as 7.2.2, since it exists only to exercise your endpoints and should never ship to production. It is a thin, well-maintained wrapper around SuperAgent that lets you make assertions against a running Express, Koa, or plain Node HTTP handler without standing up a real network listener.
If you have written integration tests for a Node API, you have almost certainly reached for npm supertest. The appeal is that it binds to your app on an ephemeral port (or works directly against the request handler), issues real HTTP requests, and gives you a fluent assertion API. It receives well over 14 million downloads a week, which puts it firmly in the category of core ecosystem tooling.
Where does supertest fit in a Node stack?
supertest sits at the integration test layer. You hand it your application object and it returns a request agent you drive with familiar verbs:
const request = require('supertest')
const app = require('../app')
describe('GET /health', () => {
it('returns 200 and a status body', async () => {
const res = await request(app)
.get('/health')
.expect('Content-Type', /json/)
.expect(200)
expect(res.body.status).toBe('ok')
})
})
Because it exercises the full middleware chain, routing, and serialization, it catches classes of bugs that unit tests miss: a body parser misconfigured, a header not set, an auth guard that lets an unauthenticated request through. That last case is why supertest earns its keep on the security side. Assertions like "an anonymous request to /admin returns 401" are exactly the regression tests that stop an access-control bug from shipping twice.
Is supertest npm actively maintained?
Yes. The project moved under the forwardemail organization after the original visionmedia repository went quiet, and it has a healthy release cadence. As of early 2026 the current version is 7.2.2, published January 2026, and it targets Node.js 14.18.0 and above. Its single meaningful runtime dependency is SuperAgent (currently the 10.x line), the HTTP client that does the actual request work.
That short dependency chain matters. A test library that dragged in dozens of transitive packages would widen your development attack surface and slow installs. supertest's lean footprint means the main thing to watch is SuperAgent itself, which has its own advisory history worth tracking. When you audit your lockfile, treat SuperAgent as the component to scan, since it is where any real vulnerability in this subtree would live. An SCA tool such as Safeguard will surface a SuperAgent advisory even though you only ever installed supertest directly.
Should supertest ever appear in production dependencies?
No, and this is the most common mistake. supertest is test infrastructure. It belongs in devDependencies:
npm install --save-dev supertest
If it lands in dependencies, you ship a test client and its transitive tree to every production install, inflating your image, lengthening the dependency chain your scanners have to reason about, and adding code paths that have no business running in a live service. Verify placement with:
npm ls supertest
and confirm it shows under the dev tree. In CI, install with npm ci so the lockfile is honored exactly, and build production artifacts with npm ci --omit=dev so dev-only packages like supertest are excluded from the shipped bundle entirely. A container image built without --omit=dev that includes supertest is not a vulnerability by itself, but it is unnecessary surface and it muddies any SBOM you generate.
What are the real risks with a test library?
The library will not attack your users, but test code has a way of becoming a soft target for other reasons. Tests often carry hardcoded credentials, tokens, or fixture data that mirror production secrets. If those tests run against a shared staging environment, or if the fixtures are copied from real data, you have leaked sensitive material into your repository history. Keep test credentials synthetic and scoped to throwaway environments.
A second risk is test-time network egress. supertest against an in-process app makes no external calls, but the moment a test hits a real third-party sandbox, your CI runner is making outbound connections that deserve the same egress controls as any other build step. Pin the base URL, and prefer mocking external services over live calls so a flaky vendor cannot fail your build and so your test runner is not quietly talking to the internet.
How do I use supertest to test security behavior?
Beyond happy-path assertions, supertest is a good tool for encoding your security expectations as tests. A few patterns worth standardizing:
// auth is enforced
await request(app).get('/api/account').expect(401)
// oversized bodies are rejected
const big = 'x'.repeat(200 * 1024)
await request(app).post('/api/notes').send({ body: big }).expect(413)
// security headers are present
const res = await request(app).get('/')
expect(res.headers['x-content-type-options']).toBe('nosniff')
Encoding these as tests turns a security review comment into a permanent guardrail. When someone later removes a header middleware or bumps a body limit, the suite fails instead of silently regressing. If you are building out this kind of coverage, our Academy has walkthroughs on baking security checks into the pipeline.
FAQ
Is supertest npm the same as SuperAgent?
Not quite. SuperAgent is the underlying HTTP client. supertest wraps it with test-specific ergonomics, the ability to bind to your app on an ephemeral port and a fluent .expect() assertion API. When you install supertest npm, SuperAgent comes along as its dependency and is the component you actually audit for CVEs.
What Node version does supertest require?
Current supertest (the 7.x line) requires Node.js 14.18.0 or later. If you are on an older Node runtime, pin an older supertest major, but bear in mind that Node versions before 18 are themselves out of support and carry their own risk.
Can supertest test APIs that are not built with Express?
Yes. supertest works with any Node HTTP handler, including Koa, Fastify (via its Node server), Hapi, and a plain http.createServer callback. You pass it the app or server and it drives requests the same way regardless of framework.
Does supertest need to be in my SBOM?
If you generate SBOMs from your development lockfile, supertest and SuperAgent will appear. If you build production artifacts with dev dependencies omitted, they should not appear in the production SBOM, which is the desired outcome, test tooling has no place in your shipped software bill of materials.