{"id":10420,"library":"supertest","title":"Supertest","description":"Supertest is an actively maintained, SuperAgent-driven library for making HTTP assertions easy when testing HTTP servers. The current stable version is 7.2.2. The project receives regular updates and bug fixes, with new versions released periodically to incorporate dependency bumps and address issues.","status":"active","version":"7.2.2","language":"javascript","source_language":"en","source_url":"https://github.com/ladjs/supertest","tags":["javascript","bdd","http","request","superagent","tdd","test","testing"],"install":[{"cmd":"npm install supertest","lang":"bash","label":"npm"},{"cmd":"yarn add supertest","lang":"bash","label":"yarn"},{"cmd":"pnpm add supertest","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"symbol":"request","correct":"import request from 'supertest';"}],"quickstart":{"code":"import request from 'supertest';\nimport express from 'express';\n\nconst app = express();\n\napp.get('/user', function(req, res) {\n  res.status(200).json({ name: 'john' });\n});\n\nrequest(app)\n  .get('/user')\n  .expect('Content-Type', /json/)\n  .expect('Content-Length', '15')\n  .expect(200)\n  .end(function(err, res) {\n    if (err) {\n      console.error(err);\n      // In a test environment, you would typically use a test runner's fail method here\n      // e.g., done(err) for Mocha\n    }\n    console.log('Test successful:', res.body);\n  });","lang":"javascript","description":"Demonstrates a basic GET request to an Express application, asserting response headers, content length, and status code without a dedicated test framework."},"warnings":[{"fix":"Always use `.expect(statusCode)` if you anticipate non-2xx responses (e.g., `.expect(404)` for 'Not Found') to prevent them from being treated as errors and passed to your callback.","message":"Supertest (via SuperAgent) treats non-2xx HTTP responses as errors and passes them to the callback's first argument, unless you explicitly assert the expected status code using `.expect(statusCode)`.","severity":"gotcha","affected_versions":">=7.0.0"},{"fix":"Ensure you handle the `err` argument in your `.end()` callback (e.g., `if (err) throw err;` or `done(err);`) to properly fail your test cases when assertions within the chain fail.","message":"When using the `.end()` method, failed `.expect()` assertions will not throw errors directly. Instead, they will be returned as the `err` argument to the `.end()` callback.","severity":"gotcha","affected_versions":">=7.0.0"},{"fix":"Upgrade your Node.js environment to version 14.16.0 or higher to use Supertest v7 and above. The currently recommended minimum is 14.18.0.","message":"Supertest v7.0.0 and later no longer support Node.js versions earlier than 14.16.0.","severity":"breaking","affected_versions":"v7.0.0"},{"fix":"Ensure your test setup and teardown explicitly manage the HTTP server's lifecycle, for example, by calling `server.close()` in an `afterAll` or `afterEach` hook if you are manually creating HTTP servers.","message":"Automatic server closing behavior, which was present in some earlier v7 versions, was reverted in v7.1.3. This means you are responsible for managing the server's lifecycle in your tests.","severity":"gotcha","affected_versions":"v7.1.3"}],"env_vars":null,"last_verified":"2026-04-18T00:00:00.000Z","next_check":"2026-07-17T00:00:00.000Z","problems":[{"fix":"Verify that the API route is correctly implemented and accessible. If a 404 (or other non-2xx) is expected, add `.expect(404)` to your Supertest chain.","cause":"The tested API endpoint returned a 404 status code (or another unexpected non-2xx status) which was not explicitly expected by `.expect()`.","error":"Error: expected 200 \"OK\", got 404 \"Not Found\""},{"fix":"Ensure you are passing either an instance of an `http.Server` (e.g., `http.createServer(app)`) or a valid application function (e.g., `express()`) directly to `request()`.","cause":"The `request()` function was called with an argument that is not a valid `http.Server` instance or an Express/Koa application function.","error":"TypeError: app.address is not a function"},{"fix":"Add `import request from 'supertest';` (for ESM) or `const request = require('supertest');` (for CommonJS) at the top of your test file.","cause":"The `supertest` module was not correctly imported or required in the test file.","error":"ReferenceError: request is not defined"},{"fix":"Ensure `done()` is called only once per test. If passing `done` to `.expect()`, omit it from `.end()`. If using `.end()`, only call `done(err)` or `done()` there.","cause":"The asynchronous `done()` callback for a test was invoked more than once, often due to calling it in both an `.expect()` assertion and the `.end()` callback, or multiple times within a single callback.","error":"Error: done() called multiple times"}],"ecosystem":"npm"}