supertest

Postconditions — what we check

• request · assertion-failure

  error
  WhenA chained assertion fails (e.g., .expect(200) when response status is 404)
  ThrowsAssertionError with expected vs actual values
  Required handlingIn test frameworks (Jest, Mocha), callers MUST either: 1. await the request chain and let the test framework catch the AssertionError, OR 2. Pass the error to done() callback if using callback style: .end((err, res) => { if (err) return done(err); }) Failing to handle AssertionError in callback style causes test timeouts, not failures.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• request · connection-refused

  error
  WhenServer is not running or connection is refused (ECONNREFUSED)
  ThrowsError with code ECONNREFUSED
  Required handlingCaller MUST ensure the server is started before running tests. When passing an Express app directly to supertest, it auto-starts on a random port. ECONNREFUSED typically means a server was started externally but is not running.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• request · server-not-closed

  error
  WhenServer bound by supertest is not closed after tests complete
  ThrowsProcess hangs (does not exit after test suite finishes)
  Required handlingCaller MUST close the server after tests when using supertest with a manually created server. Use server.close() in afterAll/after hooks. When passing an Express app (not a server), supertest handles cleanup automatically.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• request · async-test-unhandled-rejection

  error
  WhenTest is async and assertion failure is not awaited
  ThrowsUnhandledPromiseRejection warning or test exits without failure
  Required handlingCaller MUST await the supertest chain in async test functions, or return the promise to the test framework. Not awaiting the chain means assertion failures are silently swallowed.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• agent · agent-http2-not-supported

  error
  Whenhttp2 option passed to request.agent() on a Node.js version without http2 support
  ThrowsError('supertest: this version of Node.js does not support http2')
  Required handlingCaller MUST NOT pass { http2: true } unless the runtime Node.js version supports http2. Node.js 8.4.0+ supports http2, but it must be explicitly available. Confirmed from agent.js source: throws Error synchronously in constructor if http2 module is unavailable. Guard with try/catch or check Node.js version before use.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2][1]
• agent · agent-cookie-state-leak

  warning
  WhenA shared agent instance is reused across separate test suites or test files without resetting state
  ThrowsNo exception — silent test pollution: cookies set in one test suite affect subsequent suites
  Required handlingCaller MUST create a fresh agent per test suite (describe block) or use beforeEach to recreate the agent. A shared agent persists Set-Cookie headers across all requests made through it. When test A logs in and test B expects an unauthenticated response, the shared agent silently sends the auth cookie from test A to test B, causing intermittent failures when tests run in a different order. Pattern: const agent = request.agent(app); in describe() scope, not module scope.
  costlowin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[1]
• agent · agent-server-not-closed

  error
  Whenrequest.agent(app) used with a manually created http.Server that is not closed after tests
  ThrowsProcess hangs — Node.js event loop is kept alive by open server handle
  Required handlingCaller MUST close the server in afterAll/after hooks when using request.agent() with a manually created server object. Unlike request(app) which creates a new internal server per Test instance and closes it after each request, the agent holds a reference to the server that persists for the lifetime of the agent. Use afterAll(() => server.close()) to prevent test suite from hanging. When passing an Express app function (not a server), supertest auto-creates and auto-closes a server per request — no manual cleanup needed.
  costlowin proddelayed failureusers seeservice unavailablevisibilityvisible
  Sources[3][1]
• agent · agent-async-unhandled-rejection

  error
  WhenAgent request chain is not awaited in async test functions
  ThrowsUnhandledPromiseRejection — assertion failures are silently swallowed
  Required handlingSame pattern as request() — callers MUST await agent chains or return the promise. agent.get('/').expect(200) without await or return means assertion errors are unhandled. The agent silently succeeds even if the response was 404. Correct: await agent.get('/api/user').expect(200) Incorrect: agent.get('/api/user').expect(200) // no await — silent failure
  costlowin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[1][3]

Sources

Every postcondition cites at least one of these. Numbered to match the footnotes above.

1. [1]github.com/ladjs/supertesthttps://github.com/ladjs/supertest#readme
2. [2]github.com/ladjs/supertesthttps://github.com/ladjs/supertest/blob/master/lib/agent.js
3. [3]github.com/ladjs/supertesthttps://github.com/ladjs/supertest/blob/master/lib/test.js