graphql-fixtures

graphql-fixtures

Utilities for generating fixture objects from GraphQL documents.

Installation

npm install graphql-fixtures --save-dev

or, with Yarn:

yarn add graphql-fixtures --dev

Usage

createFiller(schema: GraphQLSchema, options?: Options): Filler

Returns a funtion that will be used to create object fixtures. This function takes the GraphQL schema (which will be used to generate the correct type of data given the document), and an optional object with the following properties:

• addTypename: whether or not to add __typename fields to all object types in the generated fixture. Defaults to false.

• resolvers: an object whose keys are names of types in the passed schema, and whose values are functions that return a fixture version of that type. This function can return a partial fixture; the default resolvers will then fill the remainder of the object. The function will be called with the type being filled, and the parent object type whose field has that type. You could use this to, for example, create dynamic values for a type based on the object in which it resides:

  let currentID = 1;
  const fill = createFiller(schema, {
    resolvers: {
      ID: (_type: GraphQLType, parent: GraphQLObjectType) =>
        `gid://${parent.name}/${currentID++}`,
    },
  });
  

  If you return a fixture for an object type, the value of the fields you provide will be preferred over resolvers for the types of those fields.

  This library provides default fillers for all scalar types (including custom scalars, which will be filled as a random string value). It also will automatically select a random value from any enum type by default.

The function returned from createFiller has the following signature:

function fill<Data, PartialData>(
  document: DocumentNode<Data, any, PartialData>,
  data?: DeepThunk<PartialData>,
): Data;

A document is generated by using the gql tagged template literal or by importing a .graphql file using graphql-tag. To get automatic typing of the data that is expected for a document, use .graphql files and graphql-typescript-definitions.

The second argument is an optional data object. This object is how you can fill some set of fields each time you generate a fixture. You will usually want to use this in order to generate a fixture that has some subset of the query in a particular state, while the rest is randomly generated. The data provided here must match the shape of the data the GraphQL operation will provide, but every field and subfield is optional, and every field can either be a literal value or a function that returns a literal value. If using a function, the function will be called with the type being filled and the parent object type as noted in the resolvers section above.

Interfaces and Unions

When attempting to fill data for a union or interface type, the filler will default to selecting a random type that implements the interface/ is a member of the union. If you would like to ensure a particular type is selected, but leave all the other fields to be filled by resolvers, you can provide a __typename field in the data argument for that field that selects the type you wish to be filled.

Example

Assuming the following schema:

type Person {
  name: String!
}

type Query {
  self: Person!
}

With the following query:

query MyQuery {
  self {
    __typename
    name
  }
}

We can create a simpler filler globally, and use it every time we wish to generate a fixture:

import {createFiller} from 'graphql-fixtures';
import schema from './schema';
import myQuery from './MyQuery.graphql';

const fill = createFiller(schema);

// will result in {self: {__typename: 'Person', name: <String>}}
const fixtureOne = fill(myQuery);

// will result in {self: {__typename: 'Person', name: 'Chris'}}
const fixtureTwo = fill(myQuery, {self: {name: 'Chris'}});
const fixtureThree = fill(myQuery, {self: () => ({name: 'Chris'})});

list<T>(size: number | [number, number], fill?: T): T[]

Generates a list of the specified size for use in creating partially-filled data to a fill function as described above. The optional second argument is the value that will be used in each entry of the array, and so can be either a literal type the matches the list type you are filling, or a function that returns such a literal.

When a single number is provided as the first argument, an array of that size will be created. When an array with two numbers is provided, an array randomly sized in that range (inclusively) will be created.

// assuming `widgets` in a list of Widget objects

const fixture = fill(widgetQuery, {
  widgets: list([2, 4], {id: () => faker.random.uuid()}),
});