add v3 fixtures with andReturnJSON option

[morewry]

Summary

Adds /v3/fixtures with an option to utilize andReturnJSON functionality of mock endpoints.

Purpose

The three "fixtures" middleware handlers enable the customization of fixtures returned by mock endpoints from web clients, e.g. with XMLHttpRequest or fetch, addressing use cases of web UI developers and manual QA.

The existing /fixtures and /v2/fixtures handlers enable the selection of a pre-existing method from mock endpoints. This pull requests creates a /v3/fixtures handler that enables a user to set an explicit complete response in JSON, giving the web client interface functional parity (basically, also see further about status) with the Node.js runtime interface in controlling mock endpoint responses.

Previous Usage

On a web page used for active development or testing,

var xhr = new XMLHttpRequest();
xhr.open("POST", "http://localhost/v2/fixtures");
xhr.setRequestHeader("Content-Type", "application/json;charset=UTF-8");
xhr.send(JSON.stringify({
  fixtures: [{
    endpoint: "MyMockEndpoint",
    method: "myMethod"
  }]
}));

If the mock server is running on localhost and the mock endpoint MyMockEndpoint is registered and has a method myMethod, the POST request succeeds and successive requests that are handled by MyMockEndpoint will run myMethod to generate its response.

New Usage

Method

var xhr = new XMLHttpRequest();
xhr.open("POST", "http://localhost/v3/fixtures");
xhr.setRequestHeader("Content-Type", "application/json;charset=UTF-8");
xhr.send(JSON.stringify({
  fixtures: [{
    endpoint: "MyMockEndpoint",
    method: "myMethod"
  }]
}));

If the mock server is running on localhost and the mock endpoint MyMockEndpoint is registered and has a method myMethod, the POST request succeeds and successive requests that are handled by MyMockEndpoint will run myMethod to generate its response.

JSON

var xhr = new XMLHttpRequest();
xhr.open("POST", "http://localhost/v3/fixtures");
xhr.setRequestHeader("Content-Type", "application/json;charset=UTF-8");
xhr.send(JSON.stringify({
  fixtures: [{
    endpoint: "MyMockEndpoint",
    json: {"example":[1, 2, 3]}
  }]
}));

If the mock server is running on localhost and the mock endpoint MyMockEndpoint is registered, the POST request succeeds and successive requests that are handled by MyMockEndpoint will respond with an HTTP status of 200 and the JSON {"example":[1, 2, 3]}.

Status (optional)

Removed due to bug (see comments).

[morewry]

The tests for the status option fail on older versions of Node.js--only on 0.10, 0.11, 0.12 (reproduced locally on 0.12.15).

These tests fail because Object.assign is undefined, causing the error undefined is not a function. Object.assign was standardized in ES2015/ES6 (although I was baffled at first because I forgot that), so isn't present in many older versions of Node.js.

This looks to me like a potential problem in spur-errors, as the transpiled code reads,

exports.__esModule = true;var BaseError = {
  create: function create(message, internalError) {
    Error.captureStackTrace(this);
    var error = Object.assign(new Error(), BaseError);
    if (message) {
      error.message = message;
    }
    if (internalError) {
      error.internalError = internalError;
    }
    return error;
  }
}

The fix is probably to use transform-object-assign, which evidently isn't part of the ES2015 preset.

For later, I removed:

Status (optional)

var xhr = new XMLHttpRequest();
xhr.open("POST", "http://localhost/v3/fixtures");
xhr.setRequestHeader("Content-Type", "application/json;charset=UTF-8");
xhr.send(JSON.stringify({
  fixtures: [{
    endpoint: "MyMockEndpoint",
    json: {},
    status: 404
  }]
}));

If the mock server is running on localhost and the mock endpoint MyMockEndpoint is registered, the POST request succeeds and successive requests that are handled by MyMockEndpoint will respond with an HTTP status of 404 and the JSON {}.

The minimally required empty object models the existing parameters and behavior of the MockEndpoint andReturnJSON method.

Removed Support

@["#{fixture.endpoint}"].andReturnJSON(fixture.json, fixture.status)

to

@["#{fixture.endpoint}"].andReturnJSON(fixture.json)

Failing Tests

it "should respond with 304 status", ()->
  @HTTPService
    .post("http://localhost:#{@config.Port}/v3/fixtures/")
    .send({
      fixtures: [{
        endpoint: "UsersMockEndpoint"
        json: {"test": true}
        status: 304
      }]
    })
    .promiseBody()
    .then =>
      @HTTPService
        .get("http://localhost:#{@config.Port}/api/users/")
        .promiseBody()
        .then (response)->
          expect(response.statusCode).to.equal(304)

it "should respond with 404 status", ()->
  @HTTPService
    .post("http://localhost:#{@config.Port}/v3/fixtures/")
    .send({
      fixtures: [{
        endpoint: "UsersMockEndpoint"
        json: {}
        status: 404
      }]
    })
    .promiseBody()
    .then =>
      @HTTPService
        .get("http://localhost:#{@config.Port}/api/users/")
        .promiseBody()
        .catch (error)->
          expect(error.statusCode).to.equal(404)

I was also surprised to see that the 302 status causes the promise to reject, meaning it has to be handled in a catch, rather than a then, although 302/unmodified would generally be considered a successful request.

[acolchado]

@morewry Looks good overall. Just one minor request, could you please add the example client usage to the readme? Didn't notice we were missing that. We can start with the v3:

var xhr = new XMLHttpRequest();
xhr.open("POST", "http://localhost/v3/fixtures");
xhr.setRequestHeader("Content-Type", "application/json;charset=UTF-8");
xhr.send(JSON.stringify({
  fixtures: [{
    endpoint: "MyMockEndpoint",
    json: '{"example":[1, 2, 3]}'
  }]
}));

Only correction I would add there is the JSON as as string part:

json: {"example":[1, 2, 3]}

[morewry]

@acolchado Updated PR with README

[acolchado]

Thank you much for the change @morewry