API Mock Server

API mocking library that runs as a real HTTP server in Node.js

API Mock Server can be used to test code that performs HTTP requests without
calling the real service and allows full control over the request and responses.

Table of Contents

- How it works
- Install
- Node version support
- Usage
- NodeJS
- ES6
- Multiple instances (optional)
- Starting the server
- Stopping the server
- Resetting the server
- Defining mocks
- Unmocked requests
- Duplicate mocks
- Mocking requests
- Specifying paths
- Specifying HTTP methods
- Specifying query strings
- Specifying request bodies
- Specifying request headers
- Mocking Responses
- Specifying response statuses
- Specifying response bodies
- Specifying response headers
- Recording
- Getting unhandled requests
- Getting handled requests
- Getting uncalled mocks
- Proxying requests
- Current Limitations
- Credits
- License

How it works

API Mock Server runs on a real port and responds to real HTTP requests. This
means that it is ideal for testing or simulating HTTP requests made by any
language or system without interacting with its code directly.

This approach differs to projects such as nock
which work by overriding Node's http.request function.

Control of the mock is handled in Node.js and works well with testing frameworks
such as Mocha or Jasmine.

Install

``sh
npm install --save-dev @teamjourney/api-mock-server
`

or

`sh
yarn add --dev @teamjourney/api-mock-server
`

$3

Tested on Node.js 10.x and 12.x

Usage

$3

`javascript
const server = require('@teamjourney/api-mock-server').default;

server.start(9001)
.then(() => {
server.mock(
{ path: '/my-endpoint' },
{ body: { data: 'something' } },
);

// Call GET http://localhost:9001/my-endpoint here
// It will return with a JSON body of { data: 'something' }

server.stop();
});
`

$3

`javascript
import server from '@teamjourney/api-mock-server';

const init = async () => {
await server.start(9001);

server.mock(
{ path: '/my-endpoint' },
{ body: { data: 'something' } },
);

// Call GET http://localhost:9001/my-endpoint here
// It will return with a JSON body of { data: 'something' }

server.stop();
};

init();
`

$3

It's possible (but optional) to create multiple instances of the mock server
running on different ports, each with their own routes and logging.

Use instances of the MockServer class to achieve this. The below example is
in ES6 for simplicity.

`javascript
import { MockServer } from '@teamjourney/api-mock-server';

const server = new MockServer();
`

MockServer has the same interface as the core library functions so all of the
below functions should work.

$3

Calling start with a port number allows you to specify a port.

`javascript
server.start(9002)
`

Calling start without a port will attempt to start on a random port. It
returns a promise which resolves to http.Server object. This allows for
finding out the port it is being run on.

`javascript
server.start()
.then((httpServer) => {
const { port } = serverInfo.address();

...
});
`

$3

Calling stop will stop the server.

`javascript
server.stop();
`

$3

Calling reset will keep the server running but will clear all mocks and logged
requests.

`javascript
server.reset();
`

It's also possible to reset specific mocks by passing an array to reset.

`javascript
server.reset([ { path: '/my-endpoint' } ]);
`

This will remove the mock as well as removing it from the uncalled mocks list.
If the mock has been called however, it will still appear in the called mocks
list.

Trying to reset a mock that doesn't exist will fail silently.

$3

Mocking requests and responses simply involves calling mock with two
arguments. The first defines the request shape and the second the response
shape.

The simplest call would be

`javascript
server.mock({ path: '/my-endpoint' });
`

This would handle any GET requests (the default method) to /my-endpoint and
return am empty 200 response (the default response status).

There are numerous ways to configure specific behaviours that are
defined below.

#### Unmocked requests

Any unmocked requests will return an empty 501 (Not Implemented) response.

#### Duplicate mocks

Calling mock with a request shape that matches an already mocked request will
throw an error.

`javascript
server.mock({ path: '/my-endpoint' });
server.mock({ path: '/my-endpoint' });
`

Will throw an error with the following message:

`
Request matching {
"method": "GET",
"path": "/my-endpoint"
} already mocked
`

$3

#### Specifying paths

The path is the only required property when defining the request shape.

`javascript
server.mock({ path: '/my-endpoint' });
`

#### Specifying HTTP methods

Providing a method will match only requests using that method. If no method
is specified and the request has a body (see below) then the method defaults to
POST, otherwise it defaults to GET.

`javascript
server.mock({ path: '/my-endpoint', method: 'DELETE' });
`

The method string is case-insensitive.

Supported methods are GET, POST, PUT, DELETE and HEAD.

Multiple mocks defined on the same endpoint with different methods are treated
as independent mocks.

#### Specifying query strings

Query strings can be mocked in 2 ways; either by adding the query string to the
path field or by providing a separate object on the query field.

`javascript
server.mock({ path: '/my-endpoint?page=1&perPage=20' });
`

or

`javascript
server.mock({ path: '/my-endpoint', query: { page: '1', perPage: '20' } });
`

In the second style, the object values should always be specified as strings.

If no query string is specified in the mock then any request to that endpoint
will match, regardless of the query string.

#### Specifying request bodies

Request bodies can be mocked by providing the body property. Deeply nested
object structures will be matched recursively.

`javascript
server.mock({ path: '/my-endpoint', body: { foo: 'bar' } });
`

The data types of the mock and the request fields need to match exactly. This is
by design, as many real servers are sensitive to this.

If a request body is specified but with no method, the method will default to
POST.

If no request body is specified in the mock then any request to that endpoint
using that method will match, regardless of the request body.

#### Specifying request headers

Request headers can be mocked by providing the headers property with header
type and value being object properties and values respectively.

`javascript
server.mock({ path: '/my-endpoint', headers: { 'X-Foo', 'bar' } });
`

Requests will be handled if all the headers specified in the mock match. Any
other headers on the request will match, regardless of the headers.

$3

Customise the response for a particular mock by passing an object as the second
argument to mock to define the response shape.

The response argument is optional. If no response is provided the mock will
return a 200 status with an empty body.

#### Specifying response statuses

The response status can be set by providing a status property.

`javascript
server.mock({ path: '/my-endpoint' }, { status: 201 });
`

If no status is specified the response will default to 200.

#### Specifying response bodies

The response body can be set by providing a body property.

`javascript
server.mock({ path: '/my-endpoint' }, { body: { foo: 'bar' } });
`

#### Specifying response headers

The response headers can be set by providing a headers property which should
be an object with header type and value being object properties and values
respectively.

`javascript
server.mock({ path: '/my-endpoint' }, { headers: { 'x-foo': 'bar' } });
`

The response will always contain the specified headers but may also contain
additional headers automatically added by the server.

$3

All mocks and requests are logged by the server which provides easy access to
this information in a format similar to the way mocks are defined. This
structure is intended to make adding and adjusting mocks easier.

#### Getting unhandled requests

To get any requests that were not handled by a mock, call
getUnhandledRequests.

`javascript
server.getUnhandledRequests();
`

This will return an array of requests in the order that they occurred. For
example:

`json
[
{
"request": {
"path": "/my-endpoint",
"method": "GET"
}
},
]
`

#### Getting handled requests

To get requests that were handled by mocks including what response was returned,
call getHandledRequests.

`javascript
server.getHandledRequests();
`

This will return an array of requests and responses in the order that they
occurred. For example:

`json
[
{
"request": {
"path": "/my-endpoint",
"method": "GET"
},
"response": {
"status": 200
}
}
]
`

#### Getting uncalled mocks

To get a list of any mocks that have not been called, call getUncalledMocks.

`javascript
server.getUncalledMocks();
`

This will return an array of uncalled mocks in the order that they were defined.
For example:

`json
[
{
"request": {
"path": "GET",
"method": "/endpoint"
},
"response": {
"status": 200
}
}
]
`

$3

In some situations it maybe useful to be able to proxy requests that aren't
mocked to a real server.

`javascript
server.start(9001, 'http://realserver.com');
`

When a request is proxied the mock server will return the response exactly
as it was returned by the real server.

Both the request and the response are recorded and are available via the
getProxiedRequests method.

`javascript
server.getProxiedRequests();
`

Any mocks that match will be handled first and those requests won't be proxied.
This allows for selective mocking of APIs.

Current Limitations

* There is no support for non-JSON request or response bodies
* The server cannot be run with any hostname other than localhost`
* The path matcher uses Express routes under the hood so theoretically any
pattern that Express supports should work, but this functionality is untested

Credits

This library was inspired and influenced by:

* nock
* MockServer
* Stubborn
* Dyson
* mock-http-server
* Mockery

License

MIT