http-stub

Simple HTTP stubbing library for Node.js.

Features

• Real HTTP server (no monkey patching).
• Blazing fast.
• Stub response headers, status code and body.
• Supports text, JSON, urlencoded and Buffer request bodies.
• Simulate slow responses.
• Simulate network errors.
• Minimal boilerplate.
• Easily verify that all requests were stubbed.
• Supports fully asynchronous test suites (pairs well with AVA).
• Assertions are always attributed to tests and easy to debug.
• HTTPS support.

Install

yarn add --dev @rowno/http-stub
# or
npm install --save-dev @rowno/http-stub

Usage

import test from 'ava'
import createHttpStub from '@rowno/http-stub'
import got from 'got'

test.beforeEach(async (t) => {
  // Create a fresh server instance for each test
  t.context.httpStub = await createHttpStub()
})

test.afterEach((t) => {
  // Verify that all the requests were stubbed
  t.context.httpStub.verify()
})

test.afterEach.always(async (t) => {
  // Stop the server to free up the port
  await t.context.httpStub.stop()
})

test('can send a JSON POST', async (t) => {
  // Add a response stub
  t.context.httpStub.addStub({
    statusCode: 202,
    delay: 100,
    body: { wow: 'such response' },
  })

  // Make a HTTP request to the stub server
  const response = await got(t.context.httpStub.url, {
    json: true,
    body: { wow: 'such request' },
  })
  // Get the request details
  const request = t.context.httpStub.requests[0]

  t.is(request.method, 'POST')
  t.deepEqual(request.body, { wow: 'such request' })

  t.is(response.statusCode, 202)
  t.deepEqual(response.body, { wow: 'such response' })
})

API

createHttpStub([options])

Returns: Promise<HttpStub>

Creates a new HttpStub server instance. You should create a fresh instance for each of your tests.

options

Type: object

https

Type: boolean or object
Default: false

Changes the server to be a HTTPS server. If set to true a self signed certificate will be used. Otherwise it can be set to an object map containing key, cert and passphrase keys (like tls.createSecureContext()).

HttpStub

A stubbed HTTP server instance. It contains methods for controlling the server and adding stubs, and properties for asserting the requests that hit it.

start()

Returns: Promise

Starts the HTTP server. You shouldn't normally need to call this because createHttpStub() calls it for you.

stop()

Returns: Promise

Stops the HTTP server. You should call this in your test cleanup to free up the port.

addStub(options)

Adds a single response stub. The stub will only be used for a single request and then discarded. This allows you to test behavior like retries.

options

Type: object

statusCode

Type: integer
Default: 200

Sets the response status code.

headers

Type: object

Object map that sets the response headers.

body

Type: object, array, string, Buffer or function

Sets the response body. Objects/arrays will be JSON encoded and strings/Buffers will sent as is. If you don't set the content-type header, one will automatically be provided.

The body can also be set to a callback function for dynamically generating the body. The function will be passed an object containing method, url, headers and body keys (the same keys as a single request).

delay

Type: integer

Delays the response by the given number of milliseconds. Useful for testing timeouts.

verify()

Utility function for making sure all the requests were stubbed. It throws an exception if some of the requests weren't stubbed or if some of the stubs weren't used. Useful for calling in the afterEach test hook to make sure everything ran as expected.

requests

Type: array<object>

Array requests that hit the server. Each request has the following properties.

method

Type: string

The request's HTTP method, e.g: POST.

url

Type: string

The request's URL, e.g: /test

headers

Type: object

The request's HTTP headers.

body

Type: object, array, string or Buffer

The request's body. It'll automatically be decoded based on the content-type header you send. application/json will be JSON decoded, application/x-www-form-urlencoded will be parsed using the querystring module, text/* will be converted to a string, and everything else will be a Buffer.

unStubbedRequests

Type: array<object>

Array of requests that hit the server that didn't have any stubbed responses. Contains the same thing as requests.

stubs

Type: array<object>

Array of unused response stubs. Each stub has the same properties as the addStub() options.

notRequested

Type: boolean

Utility assertion property that's true when the server hasn't received any requests.

requested

Type: boolean

Utility assertion property that's true when the server has received at least one request.

requestedOnce

Type: boolean

Utility assertion property that's true when the server has received exactly one request.

requestedTwice

Type: boolean

Utility assertion property that's true when the server has received exactly two requests.

requestedThrice

Type: boolean

Utility assertion property that's true when the server has received exactly three requests.

License

http-stub is released under the MIT license.

Copyright © 2018 Roland Warmerdam.