/amarillo

A stateless graphql mock with stateful capabilities

Primary LanguageJavaScriptMIT LicenseMIT

Amarillo

A stateless GraphQL mock with stateful capabilities.

This library serves to act as a mock of one or many GraphQL graphs. It does so by making a small extension to the API of graphql-tools, and adding a cookie-based mechanism for keeping a small state representation on the client.

Table of contents

Why Amarillo

This library is built with two primary use cases in mind:

  • Developing a web app that depends on a GraphQL API
  • Testing a web app that depends on a GraphQL API

For development you may or may not have an API available to you. If you have the GraphQL schema setting up a rich mock is simple with Amarillo.

For testing you might not want to depend on other services than the application you are testing. Amarillo can be run in the same process as your web app, or side by side, to make application testing without dependencies to other services simple.

Requirements

To use this library:

To develop this library:

Getting started

  • Set up an express server with a body parser and cookie parser of your choice.
  • Add a mock, or default mock - see Mock folder.
  • Designate the mock folder in the environment variable AMARILLO_MOCK_PATH.
  • (optional) Configure a mock header name - see Specifying a mock in your graphql query
  • Mount the Amarillo middleware on a path of your choice - e.g. app.use('/gql-mock', amarillo);.
  • Start your server and start querying! See Specifying a mock in your graphql query for more info on how to pick a mock per query.

See Running the example for an example and tips for getting started.

Mock folder

Amarillo supports exactly one mock folder, with no subfolders. The mock folder contains all graph mocks, according to the Mock format. The file name will denote the unique name of your mock, e.g mocks/my-mock.js will be given the unique name my-mock.

When starting your app, the mock folder is designated by the mandatory AMARILLO_MOCK_PATH env variable.

Specifying a mock in your graphql query

To specify which mock to use when responding to a query, the optional amarillo-graph-name can be set to the mocks name. If you want to change the header name, set the environment AMARILLO_HEADER_NAME to your desired name.

How the graph name is chosen is described in Mock folder.

If the header is not set, a mock named default will be used. If the header is not set and there is no mock named default the service will respond with a 500.

One way of doing this in your client per query is to use the apollo client context

Mock format

The mock format is inspired by the parameters provided when setting up a graphql mock in graphql-tools. A mock file must export a single object with the following fields:

  • typeDefs - the graphql schema string to mock.
  • resolvers - any resolvers to include. May be an empty object.
  • mocks - The mocks to use, according to the format specified in Customizing mocks.
  • deltas - An array of deltas to apply, giving the mock client-driven statefulness. Specifying deltas will allow the mock to respond to the same query in different ways to simulate statefulness. See Deltas for more info.
  • deltasCumulative (optional) - A boolean indicating whether to apply deltas in a cumulative fashion. If true, all deltas up until, and including, the current delta index will be applied before sending the response, instead of only the delta at the delta index.

Deltas

Each delta will override the mocking specified in the mocks field. The deltas will be merged with the mocks, overriding only what you specify in the deltas.

The deltas will be served round-robin, starting at index 0. Once the last delta is served, the mock will serve one delta-free response and then start applyting deltas again.

The delta functionality stores a cookie in the client to indicate which delta to serve next. If the client does not support cookies the initial state will always be served.

Running the example

The example is a separate node project found under /example. To start it:

  • Check out the repo.

In the example folder: