supertest-fetch

A typescript friendly alternative to Supertest. Backed by native node fetch implementation so it requires node 18+ version.

What is it?

This is a library heavily influenced by Visionmedia's excellent supertest library, but with a WHATWG Fetch-like interface. The advantages of this library are:

• Uses native node Fetch API implementation (support since node v18.0.0).
• Should be instantly familiar to anyone who has used supertest.
• First class support for promises.
• Supertest has some weird quirks when used with Typescript becuase of @types/superagent.

Example

1import http from 'http';
2import { makeFetch } from 'supertest-fetch';
3
4const server = http.createServer((req, res) => {
5    res.setHeader('content-type', 'application/json');
6    res.end(JSON.stringify({ greeting: 'Hello!' }));
7});
8
9// This is a function with an API identical to the WHATWG `fetch()` function,
10// except the returned Promise has a bunch of supertest like functions on it.
11//
12// If the server is not listening, then `fetch()` will call `listen()` on the
13// server before each fetch, and close it after each fetch.
14const fetch = makeFetch(server);
15
16describe('my server tests', function () {
17    it('should return a response', async function () {
18        await fetch('/hello')
19            .expect(200)
20            .expect('content-type', 'application/json')
21            .expect({ greeting: 'Hello!' });
22    });
23
24    it('will work just like fetch if you need to do more advanced things', async function () {
25        const response = await fetch('/hello')
26            .expect(200)
27            .expect('content-type', 'application/json');
28
29        expect(await response.json()).to.eql({ greeting: 'Hello!' });
30    });
31
32    it('should post data', async function () {
33        await fetch('/hello', {
34            method: 'post',
35            body: '<message>Hello</message>',
36            headers: { 'content-type': 'application/xml' },
37        });
38    });
39});

API

makeFetch(server)

Returns a new fetch function. This is identical to the WHAT-WG fetch function, except that the returned object has some extra assertions added to it.

If the server passed in is not already listening, each call to fetch() will call listen() on the server, and close it after each request. This will assign a random free port to the server, so you don't need to worry about listening on a well-known port for your tests to work.

If the server passed in is an instance of tls.Server, then the returned fetch instance will use HTTPS to connect to the server instead of HTTP. Note that it's up to you to appropriately configure the server, supplying a certificate and key, and if you're using a self-signed certificate you'll need to pass an "agent" to the call to fetch. See this example for details.

.expectStatus(statusCode[, statusText])

Verify response status code and text.

.expectHeader(headerName, value)

Verify headerName matches the given value or regex. If value is null, verifies that the header is not present.

.expectBody(body)

Verify body is the given string, JSON object, or matches the given regular expression.

.expect(statusCode[, fn])

Supertest friendly alias for .expectStatus(statusCode).

.expect(statusCode, body)

Supertest friendly alias for .expectStatus(statusCode).expectBody(body).

.expect(body)

Supertest friendly alias for .expectBody(body).

.expect(field, value)

Supertest friendly alias for .expectHeader(field, value).

.json()

Convenience function which returns a Promise which resolves to the JSON content of the response. This:

1const result = await fetch('/hello').expect(200).json();

is equivalent to:

1const response = await fetch('/hello').expect(200);
2const result = await response.json();