scenario-mock-server

Scenario Mock Server

Mock server powered by scenarios.

Table of contents

• Scenario Mock Server
  • Table of contents
  • Installation
  • Example usage
  • Cookie mode
  • Allowing for multiple responses
  • Running tests in parallel
    • sms-scenario-id header
    • sms-context-id header
  • Additional API paths
    • /scenarios
    • /select-scenario
    • /groups
  • API
    • createExpressApp
    • run
      • scenarios
      • groups
      • options
  • Types
    • Mock
    • HttpMock
    • Response
    • HttpResponseFunction
    • GraphQlMock
      • Operation
    • GraphQlResponse
    • GraphQlResponseFunction

Installation

npm install scenario-mock-server

Example usage

const { run } = require('scenario-mock-server');

run({
	scenarios: {
		item: [
			{
				path: '/api/test-me',
				method: 'GET',
				response: { data: { blue: 'yoyo' } },
			},
		],
		cheese: [
			{
				path: '/api/test-me',
				method: 'GET',
				response: { data: { blue: 'cheese' } },
			},
		],
	},
});

Calls to http://localhost:3000/api/test-me will start by returning { blue: 'yoyo' }.

Visiting http://localhost:3000 will allow you to select a scenario. The first declared scenario will be initially selected. In this case, enabling cheese will modify /api/test-me so that it returns { blue: 'cheese' }.

Cookie mode

By default Scenario Mock Server runs in server mode storing the current selected scenario and context in server memory. Alternatively you can set cookieMode to true in the options, which stores the current scenario and context in a cookie instead. This is useful when you want to run a central mock server, but allow each user to select and store their own scenarios and associated contexts without it affecting other users.

Allowing for multiple responses

Sometimes you may want an endpoint to respond with different status codes depending on what is sent. It is the recommendation of this package that this can be achieved by using scenarios. However, given response can be a function, it is possible to respond with a different value for the status, headers, data and delay properties:

const mock = {
	path: '/some-path',
	method: 'GET',
	response: ({ body }) => {
		if (body.name === 'error1') {
			return {
				status: 400,
				data: { message: 'something went wrong' },
				delay: 1000,
			};
		}

		if (body.name === 'error2') {
			return {
				status: 500,
				data: { message: 'something else went wrong' },
				delay: 2000,
			};
		}

		if (body.name === 'notFound') {
			return {
				status: 404,
				data: { message: 'no data here' },
			};
		}

		// Default status is 200
		return { data: { message: 'success' } };
	},
};

Running tests in parallel

Scenario Mock Server aims for mock data to be readily available while you're devloping locally, but also when you're running your tests.

The default behaviour of Scenario Mock Server is to run with one scenario active at a time. However, this falls down if you want to use multiple scenarios at the same time when running your tests in parallel. This is where 2 custom headers will become useful: sms-scenario-id and sms-context-id.

Note: These headers are not currently supported in cookieMode.

sms-scenario-id header

When this header is set to the scenario id of choice, regardless of what the current scenario is set to in the server, all responses will behave as if this was the currently set scenario instead.

sms-context-id header

This header must also be set when context is being used, otherwise context will reset on each call to the server when using the sms-scenario-id header.

Additional API paths

In addition to responding to API requests as set up by the currently active scenario a few additional endpoints exist that return json:

• /scenarios
• /select-scenario
• /groups

These paths can be modified by using options (in case they clash with paths from scnearios).

/scenarios

Returns an array of scenarios available. Use GET.

type ApiScenario = {
	id: string;
	name: string;
	description: null | string;
	selected: boolean;
	group: null | string;
};

/select-scenario

Allows you to select which scenario is active. Use PUT and the following body:

{
	"scenarioId": "{SCENARIO_YOU_WANT_TO_SELECT}"
}

/groups

Returns an array of groups. Use GET.

type ApiGroup = {
	id: string;
	name: string;
};

API

createExpressApp

Returns the internal express instance.

function({ scenarios, options })

run

Returns an http server, with an additional kill method.

function({ scenarios, options })

scenarios

{ [scenarioId]: Array<Mock> | { name, description, context, mocks, extend, group } }

Property	Type	Default	Description
scenarioId	string	required	Scenario id. Used in calls to /select-scenario.
Mock	Mock	required	See Mock for more details.
name	string	${scenarioId}	Scenario name. Used in the UI and available in /scenarios.
description	string	undefined	Scenario description. Used in the UI and available in /scenarios.
context	object	undefined	Used to set up data across API calls.
mocks	Array<Mock>	required	See Mock for more details.
extend	string	undefined	Use for extending other scenarios. Requires a scenario id.
group	string	undefined	Used for grouping scenarios in the UI.

groups

{ [groupId]: groupName }

Property	Type	Default	Description
groupId	string	required	Group id. Matches with group assigned to scenarios.
groupName	string	required	Used for heading in UI when groups exist.

options

{ port, uiPath, selectScenarioPath, scenariosPath, groupsPath, cookieMode, parallelContextSize } | defaults to {}

Property	Type	Default	Description
port	number	3000	Port that the http server runs on.
uiPath	string	/	Path that the UI will load on. http://localhost:{port}{uiPath}
selectScenarioPath	string	/select-scenario	API path for selecting a scenario. http://localhost:{port}{selectScenarioPath}
scenariosPath	string	/scenarios	API path for getting scenarios. http://localhost:{port}{scenariosPath}
groupsPath	string	/groups	API path for getting groups. http://localhost:{port}{groupsPath}
cookieMode	boolean	false	Whether or not to store scenario selections in a cookie rather than directly in the server
parallelContextSize	number	10	How large to make the number of contexts that can run in parallel. See Running tests in parallel

Types

Mock

HttpMock | GraphQlMock

See HttpMock and GraphQlMock for more details.

HttpMock

{ path, method, response }

Property	Type	Default	Description
path	string / RegExp	required	Path of endpoint. Must start with /.
method	'GET' / 'POST' / 'PUT' / 'DELETE' / 'PATCH'	required	HTTP method of endpoint.
response	undefined / Response / HttpResponseFunction	undefined	Response, HttpResponseFunction.

Response

{ status, headers, data, delay }

Property	Type	Default	Description
status	number	200	HTTP status code for response.
headers	object / undefined	See description	Key/value pairs of HTTP headers for response. Defaults to undefined when response is undefined, adds 'Content-Type': 'application/json' when response is not undefined and Content-Type is not supplied.
data	null / string / object	undefined	Response data
delay	number	0	Number of milliseconds before the response is returned.

HttpResponseFunction

function({ query, body, params, headers, context, updateContext }): response | Promise<response>

Property	Type	Default	Description
query	object	{}	query object as defined by express.
body	object	{}	body object as defined by express.
params	object	{}	params object as defined by express.
headers	object	{}	Request headers, lowercase keys, string values only.
context	object	{}	Data stored across API calls.
updateContext	Function	partialContext => updatedContext	Used to update context. partialContext can either be an object or a function (context => partialContext).
response	undefined / Response	required	Response.

GraphQlMock

{ path, method, operations }

Property	Type	Default	Description
path	string	required	Path of endpoint.
method	'GRAPHQL'	required	Indentifies this mock as a GraphQlMock.
operations	Array<Operation>	required	List of operations for GraphQL endpoint. See Operation for more details.

Operation

{ type, name, response }

Property	Type	Default	Description
type	'query' / 'mutation'	required	Type of operation.
name	string	required	Name of operation.
response	undefined / GraphQlResponse / GraphQlResponseFunction	undefined	GraphQlResponse, GraphQlResponseFunction.

GraphQlResponse

{ status, headers, data, delay }

Property	Type	Default	Description
status	number	200	HTTP status code for response.
headers	object / undefined	See description	Key/value pairs of HTTP headers for response. Defaults to undefined when response is undefined, adds 'Content-Type': 'application/json' when response is not undefined and Content-Type is not supplied.
data	{ data?: null / object, errors?: array }	undefined	Response data
delay	number	0	Number of milliseconds before the response is returned.

GraphQlResponseFunction

function({ variables, headers, context, updateContext }): response | Promise<response>

Property	Type	Default	Description
variables	object	{}	variables sent by client.
headers	object	{}	Request headers, lowercase keys, string values only.
context	object	{}	Data stored across API calls.
updateContext	Function	partialContext => updatedContext	Used to update context. partialContext can either be an object or a function (context => partialContext).
response	undefined / GraphQlResponse	required	GraphQlResponse.

Changelog

1.2.0

Minor Changes

• 252134d: Allow for grouping of scenarios. This change allows for an additional group property to be added to scenarios and a groups object that maps group id to group name for the UI. In the UI scenarios will be split by group to make it easier to manage a larger number of scenarios.