Programable HTTP server for micro-service unit testing

Getting Started

httpunit can be used for mocking any micro-service by setting up your own server and route handler programmally. With the ability of programming the server, unit test codes could expect any response from server as your wish.

httpunit listens on a pre-configured admin port after launched, from which unit tests could calls to the admin API to create, delete servers and set expect response for specified routes.

After the server created and route handler successfully set by admin APIs, the code to be tested could then issue requests to httpunit. The expected responses will send back to code to be tested.

httpunit works in two modes: mock mode or proxy mode.

Mock mode

In mock mode, httpunit acts as the micro-service you are going to mock. The code to be tested connect to httpunit just like connect to the real micro-service.

Proxy mode

httpunit could act as an HTTP/HTTPS proxy as well. httpunit could modify the response from target service for any need of unit test. For example, simulate HTTP 404 for a specific resource even it exists in the real world.

The real micro-services work behind the proxy, and the unit test could mock only specific APIs.

As well, everything is programmable.

Installing

npm install -D @samzh72/httpunit

Launching server:

var hu = require('httpunit');
hu.serve({
    mockOptions: {
        port: 8000
    },
    proxyOptions: {
        port: 8001
    }
});

Both mockOptions and proxyOptions are optional. Mock mode or proxy mode will be launched only when the option specified.

Mock APIs

httpunit provides very simple APIs to create, delete mock servers and set handlers for testing routes.

Create server

A mock server will be created on a specified port and bind to a specified IP. But there’re no route handlers installed for this server yet. Any requests to this server will get HTTP 404 response.

Request:

path method
/server POST

Request body:

{
    port: 9000,
    host: '127.0.0.1'
}
field optional comments
port no where the mock-service will listen on
host yes which ip to be bind, default bind to 0.0.0.0

Response:

{
    serverId: 12345678
}
field comments
serverId used for identifying the mock server in further API

Delete server

Mock server could be shut down. But it’s not always necessary, especially while httpunit running in process of unit test.

Request:

path method
/server/:serverId DELETE

No body in response, status code indicates result of the API call.

Install route handler

Define the behavior of mock server for the specific route.

Request:

path method
/:serverId/handler PUT

Request body:

{
    path: '/abc/:id',
    method: 'GET',
    response: {
        delay: 200,
        status: 200,
        headers: {
            'X-any-header': 'any header value'
        },
        body: 'any string or object',
        cookies: [
            {
                name: 'any-cookie-name',
                value: 'cookie-value',
                signed: false,
                domain: 'google.com',
                httpOnly: false,
                expires: '2019-05-11T15:25:37.000Z',
                maxAge: 2000,
                path: '/',
                secure: false,
                sameSite: 'strict'
            }
        ]
    }
}
field optional comments
path no route path to be installed, string starts with ‘/’
method no HTTP method
response no response behavior
delay yes undefined: response immediately
    0: never response, request will be rejected
    others: number in milliseconds, response will be sent only after this delay
status no response status code
headers yes array of headers to be appended to response. header field will be converted into lower case in response
body yes response body, could be string or JSON object
cookies yes cookies to be appended to response
name no cookie name
value no cookie value
signe yes true for signed cookie, sign secret used in httpunit is ‘secret’
domain yes it’s optional, but in most case it should be there
httpOnly yes true for httpOnly cookies
expires yes GMT time, 0 for session cookie
maxAge yes max-age in milliseconds
path yes default to ‘/’
secure yes true to be used with HTTPS only
sameSite yes ‘strict’ or ‘lax’

No body in response, status code indicates result of the API call.

Proxy APIs

TBD

Posts

subscribe via RSS