mock-web-server

mock-web-server

A lightweight simple helper utility to mock web-servers

Synopsis

Consider working on a API web client whose concerns are:

• format user-provided arguments into the web protcol and fire the request
• expect a reply in a given format
• unwrap data from protocol envelopes and yield/resolve them to the user
• handle net, http and logical errors

Consider the API server to be an expansive resource to access:

• it could require API keys

• it could be tethering your requests and fail builds

• it risk resulting with monetary transactions

• or whatever reason that drove you to decide to develop with a mock server

This utility helps you launch the simplest tiniest nodejs actual web-server, bind it to a port and configure it to play the role of the real API server.

But the real intention is to faciliate testing. The good part - is that you run it in-process to your test suite, and therefore can inspect progrmatically what requests it received (and perform asserts against them) and easily manipulate the response it emits.

Example - the common simple case:

This example uses a simple static response descriptor. Every time the server receives a request - it will:

• capture a REPL-friendly detailed view of the request.
• respond with the same respopnse, no matter what are the characteristics of the request.

You can replace the response descriptor using svr.reset(newResponseDescriptor).

This example uses mocha, however - it can be used with every any test runner.

const mockSvrFactory = require('mock-web-server');
const sut = require('../lib/my-web-client');
const Should = require('should');
const request = require('request');

describe('lib/my-web-client', () => {
  let client;
  before(() => client = sut({baseUrl: "http://localhost:3030"}));

  it('should be a module object',
    () => Should(sut).be.an.Object()
  );
  it('should have .get API', () => {
    () => Should(sut).have.properties(['get'])
  });
  
  describe('when calling .get(id) with a valid id', () =>  {
    let svr = mockSvrFactory({
      status: 200,
      headers: { 'content-type' : 'application/json' },
      body: { 
        status: 'OK', 
        data: {
          entity: { id: 333, note: 'it is what it is' }
        }
      }
    });
    before((done) => svr.listen(3030, done));
    after(() => svr.close());
    
    
    describe('and the server responds with valid response', () => {
      let foundErr, foundRes;
      beforeAll(() => {
        svr.reset()
        return client.get(333)
          .then(entity => foundRes = entity)
          .catch(err => foundErr = err)
      });
      
      it('should send content type header (app/json)', () =>  {
        Should(svr.accepted[0])
          .have.property('headers')
          .have.property('content-type', 'application/json')
      });
  
      it('should hit the correct URL', () =>  {
        Should(svr.accepted[0])
          .have.properties({
            method: 'GET',
            url: 'http://localhost:3030/entity/333'
          })
      });
      
      it('should resolve to the entity, unwrapped from protocol envelopes', () => {
        Should(foundRes).eql({ id: 333, note: 'it is what it is' })
      })
    })
    
    describe('and the server responds with a malformed response', () => {
      let foundErr, foundRes;
      beforeAll(() => {
        //replace the response to a malformed response
        svr.reset({status: 200, body: {}, headres: {} });
        return client.get(333)
          .then(entity => foundRes = entity)
          .catch(err => foundErr = err)
      })
      
      it('should reject with a friendly error', () => {
        Should(foundErr).have.property('message').match(/Bad response from backend service/)
        Should(foundErr).have.property('id', 333);
        Should(foundErr).have.property('innerError').be.an.Error();
      })
    })
    
    describe('and the server does not respond at all', () => {
      let foundErr, foundRes;
      beforeAll(() => {
        //replace the response to a malformed response
        svr.close();
        return client.get(333)
          .then(entity => foundRes = entity)
          .catch(err => foundErr = err)
      })
      
      it('should reject with a friendly error', () => {
        Should(foundErr).have.property('message').match(/No response from backend service/)
        Should(foundErr).have.property('id', 333);
        Should(foundErr).have.property('innerError').be.an.Error();
      })      
    })
  })
})

Example - logic for dynamic responses

(since: 0.9.2)

In most cases, a static response to a single API is enough. However, sometimes you need your mock server to support few endpoints, and/or control for a non-idempotent API that accumulates state between responses.

For this, you can provide an preResponse hook. The hook can map an accepted request to a response, or mutate the response object behind the server.

• The hook should be synchronous.
• The hook is passed the accepted request view as a 1st argument.
• The hook is passed the response descriptor the server holds as a 2nd parameter.
• The hook is also called on the context of the response descriptor.

The server will keep collecting REPL-friendly views of the accepted requests as usual, so you can ask it what it heard from your tested client.

mapper preResponse hook

If you return a value from your preResponse hook - its props cascades their equivalents on the response descriptor the server holds.

In this example, the response descriptor the sever is initiated with defaults to a reply of Not-found. However, when the uri represents a supported entry - the returned object cascades the status: 200 and the body for that entry.

    const routes = {
      '/api/user/1': { name: 'John Snow '},
      '/api/user/2': { name: 'John Doe '},
    };
    const svr = mockSvrFactory({
      status: 404,
      headers: {
        'Content-Type': 'application/json; charset: utf-8',
      },
      body: { err: 'not-found' },
      preResponse: ({ uri }) => routes[uri] && ({ status: 200, body: this.routes[uri] }),
    });

mutator preResponse hook

Using the hook as a mutator lets you manage a simple in-memory state on the response descriptor. If you don't want to manage it in a closure - you can use this object as a context object.

The response descriptor is both passed to the hook as a 2nd argument, and used as the context on which the hook is called, so you can use this, or an arrow-function according to your preferences.

This example uses a queue of bodies on the response descriptor, and accesses it via the this keyword.

    const faker = require('faker');
    const svr = mockSvrFactory({
      queue: [{ one: 1 }, { two: 2 }, { three: 3 }],
      preResponse: ({ method }, response) => {
        const body = this.queue.unshift();
        if (!body) return { status: 404, body: { status: 'empty' } };

        return { status: 200, body };
      },
    });

This example uses a sum counter on the response desriptor, and accesses it via the 2nd argument:

    const svr = mockSvrFactory({
      sum: 0,
      preResponse: ({ body: { sum = 0 } }, response) => {
        this.sum += sum;
        return { status: 200, body: { requests: svr.accepted.length, sum: this.sum } };
      },
    });

Specs

  mock-web-server
    ✓ should be a factory function that names 1 arguments - response (it has an optional 2nd param for options)
    when provided only a response object
      ✓ should not fail and return an server instance
    when provided a response object and the optional config object
      ✓ should not fail and return an server instance
    a server instance obtained by the factory
      supported API:
        ✓ method .listen(port, done) to start the server
        ✓ method .close(done) to close it
        ✓ attribute .response as the provided response
        ✓ attribute .accepted as array of accepted requests
        ✓ method .reset() to clear the accepted requests and optionally - reset the response
      starting and closing the server should work
        and the server should serve requests with
          ✓ the provided status code
          ✓ the provided headers
          ✓ the provided body
        and server keeps a REPL-friendly view of the accepted requests that is cleared with .reset()
          ✓ found 3 requests
          ✓ views are serializable
          ✓ .reset() returns the interface and clears the accepted array
          ✓ .reset(response) returns the interface and sets the response
          structure of a request view should contain
            ✓ httpVersion
            ✓ method
            ✓ url
            ✓ headers
            ✓ rawHeaders
            ✓ upgrade
            ✓ body
            ✓ trailers
            ✓ rawTrailers
      when response object has a preResponse hook
        and the response hook returns an object
          the server should serve request with response returned by the hook
            ✓ the provided status code
            ✓ the provided headers
            ✓ the provided body
        and the response hook mutates current response using `this`
          the server should serve request with response mutated by the hook
            ✓ the provided status code
            ✓ the provided headers
            ✓ the provided body
      closing the server with a callback
        ✓ should call the callback as well as closing the server
      an error passed by body-parser
        ✓ should be collected to the request view as .parseError

  ~internals
    .mapParsers(parsers)
      ✓ should be a function that names 1 argument - parsers
      when called with an object element
        ✓ should not fail
      when called with a function element
        ✓ should not fail
      when called with a string element that is not a body-parser built-in
        ✓ should not fail and map it to an instance produced by the required module
      when called with an object element who's first key is not a body-parser built-in
        ✓ should not fail
        ✓ should map it to an instance produced by the required module
        ✓ should pass it the arguments


  39 passing (53ms)

Changelog

0.9.2

• support preResponse hook
• change lisence to ISC