In a Supertest suite for an Express app, why can a test that never awaits or returns its request(app) chain pass, and what does it leave behind?
answer
- nothing is sent until asked
- then or end dispatches
- the server already listens
- return, await or done(err)
basics
~20 sA Supertest chain sends nothing until .then() (which await calls) or .end() runs, so a test that only builds it returns at once and is reported as passing. The ephemeral server Supertest already started is never closed, so the run can hang.
solid answer
~40 sSupertest builds on a lazy HTTP client: `request(app).get('/x').expect(500)` only records the request and its assertions, and dispatch happens when `.then()` or `.end()` is called. A synchronous test body that neither awaits nor returns the chain finishes before anything happens, so the runner reports a pass and the route never runs. Worse, Supertest calls `listen(0)` when the request is described, and closes the server only after a dispatched request settles, so an undispatched one leaves a listening server that keeps the process alive. The fix is `await` (or `return`) on the chain in an async test, or `.end((err) => done(err))` in callback style. Never mix `.end()` with `await` on one chain: the client prints a warning and the awaited chain rejects with an error saying `.end()` was called twice.
code
javascript · 13 linesconst { test } = require('node:test');
const request = require('supertest');
const app = require('./app');
// Reported as passing, yet no request is ever sent
test('health check (broken)', () => {
request(app).get('/api/health').expect(500);
});
// Sends the request and fails as it should
test('health check', async () => {
await request(app).get('/api/health').expect(500);
});go deeper
Remember to await or return every request(app) chain, or pass err to done in callback style.
Explain that the chain is lazy and dispatches on .then() or .end(), so a test that only builds it passes without running the route.
Recognise a suite that passes and then hangs as an undispatched request holding a listening server, and find it rather than force-exiting the runner.
Make the mistake mechanical to catch: async tests everywhere, a lint rule on floating promises, and no forced exit hiding open handles.
## Building a request is not sending it **Supertest** wraps an HTTP client whose request objects are **lazy**. Each call in `request(app).get('/api/health').expect(500)` returns the same object with one more piece of configuration recorded: the method and path, then an assertion. Nothing goes over the wire until something asks for the outcome, which happens in one of two ways: - **`.then()`**: the chain is a *thenable*, so `await` on it, or returning it to a promise-aware test runner, calls `.then()`, which dispatches the request and resolves or rejects with the result; - **`.end(callback)`**: the callback style; it dispatches the request and calls `callback(err, res)`, where `err` is the first failed expectation or a network error. Passing a callback as the last argument of `.expect()`, as in `.expect(200, done)`, calls `.end()` for you. ## Why the broken test passes Test runners generally decide whether a test passed from what its function does: a synchronous function passes if it returns without throwing, and an async one passes if its promise resolves. A body that builds the chain without `await`, `return` or `.end()`: 1. creates the request object and records `.expect(500)`; 2. returns `undefined` straight away, without throwing; 3. is reported as **passing**, although the route never ran and the assertion was never evaluated. Because nothing was sent, there is not even a late failure to notice: the wrong expectation of 500 for a route that answers 200 is simply never checked. ## What it leaves behind Describing the request is not entirely free of side effects. When the target is an app rather than a listening server, Supertest wraps it in a new HTTP server and calls `listen(0, '127.0.0.1')` as soon as the request is created, so the port is ready when dispatch comes. It closes that server **after the last dispatched request on it settles**. An undispatched request never settles, so: - the server stays listening; - an open server keeps Node's event loop alive; - the test process does not exit by itself, and the run hangs or ends only when the runner forces it. A suite that "passes, then hangs" is a classic symptom of one forgotten `await`. ## The three correct shapes | Style | Shape | How a failed expectation surfaces | |---|---|---| | async/await | `await request(app).get(p).expect(200)` | the awaited promise rejects, so the async test fails | | returned promise | `return request(app).get(p).expect(200)` | the returned promise rejects | | callback | `.end((err) => done(err))` | `err` passed to `done` fails the test | Two rules go with them: - **In callback style, pass the error on.** With `.end()`, failed expectations do not throw: they arrive as the callback's first argument. A callback that ignores `err` turns every failure into a pass. - **Never call `.end()` and `await` on the same chain.** The client prints a warning that both `.end()` and `.then()` were called, and the awaited chain rejects with an error saying `.end()` was called twice, so the test fails for a reason unrelated to the route. ## A related surprise: errors without a status assertion An HTTP error response is not a test failure by itself. If the chain has no status expectation, `await request(app).get('/missing')` resolves with the 404 response rather than rejecting. Only a failed expectation, or a network error such as a refused connection, rejects. So a test that awaits the request but asserts nothing about the status will pass on a 500. Every chain should state the status it expects. ## Making the mistake impossible - Turn on a lint rule that flags un-awaited promises in test files; the chain is a thenable, which such rules can be configured to catch. - Keep tests `async` and `await` every chain, even when the assertions are all inside `.expect()`. - Treat a suite that does not exit on its own as a bug to find, not a reason to force-exit the runner, which hides exactly this mistake. - Pick one style per suite. Async tests with `await` are the simplest to review, because every chain visibly ends in an `await`; callback style is fine in older suites, but a file that mixes both invites the `.end()`-plus-`await` error and the dropped-`err` pass.
- With Supertest and the .end() callback, how do failed expectations reach the test?They do not throw. Supertest runs the expectations and passes the first failure as the callback's `err` argument, so the callback must pass it on, for example `.end((err) => done(err))`. Ignoring `err` makes every failure look like a pass.
- Does awaiting a Supertest request that gets a 500 fail the test if the chain has no .expect for the status?No. Without a status expectation the awaited chain resolves with the 500 response; it rejects only on a failed expectation or a network error. A test has to state the status it expects, with `.expect(200)` or an assertion on `res.status`.
- Why does a suite with one un-awaited Supertest chain often pass and then refuse to exit?Supertest starts listening on an ephemeral port when the request is described, and closes that server only after a dispatched request settles. The un-awaited request is never dispatched, so the server stays open and keeps the event loop alive.
- Supertest sends the request as soon as .get() is called.
- An un-awaited Supertest assertion still fails the test later, just asynchronously.
- With .end(), a failed expectation throws inside the test.
- Calling .end() and then awaiting the chain is the safest combination.
- A 500 response always rejects the awaited Supertest chain.