What is Kimera?

Kimera is an automocking library for GraphQL that allows you to be very precise about how mocks should be generated.

Why?

Kimera is useful to:

• Speed up the prototyping process. It's very easy to get a mocked server up and running by just updating the schema definition and optionally customizing the mocks providers.
• Allow large teams to better coordinate. Frontend developers can negotiate changes to the schema with the backend developers and then quickly add mocks for the changes in a Kimera mocked version of the server while the backend team gets to implmenting the changes.
• Improve testing in front end applications that use GraphQL. Using Kimera allows one to customize query responses by defining a single scenario as opposed to exhaustively mocking each query response, which is extremely useful for large component trees where queries are used at different levels of the component hierarchy.

Getting Started

To install Kimera you can install it via npm or yarn, it's totally up to you. We're guessing that you'll most likely want Kimera to be a dev dependency.

npm install --save-dev @lola-tech/graphql-kimera graphql@14

or if you want to use yarn

yarn add --dev @lola-tech/graphql-kimera graphql@14

Examples

These examples assume the use of the example schema we are using for testing.

Basic Example

Running the rockets query will return four rockets, all of type Shuttle, with the first being called Apollo.

const { getExecutableSchema } = require('@lola-tech/graphql-kimera');

// Importing the typeDefs from the `schema.graphql` file...

const executableSchema = getExecutableSchema({
  typeDefs,
  mockProvidersFn: () => ({
    scenario: {
      rockets: [{ name: 'Apollo' }, {}, {}, {}],
    },
    builders: {
      Rocket: () => ({
        model: 'Shuttle',
      }),
    },
  }),
});

const apollo = new ApolloServer({
  schema: executableSchema,
  introspection: true,
});

apollo.listen({ port: 4000 }).then(({ url }) => {
  console.log(chalk.green.bold(`🚀 Server ready at ${url}`));
});

Custom query resolvers examples

If you want to implement filtering in the mocked rockets query, you can define a resolver uing the mockResolver function.

const {
  getExecutableSchema,
  mockResolver,
} = require('@lola-tech/graphql-kimera');

// Importing the typeDefs from the `schema.graphql` file...

const executableSchema = getExecutableSchema({
  typeDefs,
  mockProvidersFn: () => ({
    scenario: {
      rockets: mockResolver(
        // Define a resolver factory
        (mocks) => (_, { model }) => {
          // `mocks` is a store that contains the mocks for the `rockets` query
          const rockets = mocks.get();
          return model
            ? rockets.filter((rocket) => rocket.model === model)
            : rockets;
        },
        // Optionally define a node scenario
        [{}, { model: 'Starship' }, { model: 'Starship' }]
      ),
    },
    builders: {
      Rocket: () => ({
        model: 'Shuttle',
      }),
    },
  }),
});

// Starting your server using the above defined executable schema ....

Now running:

query {
  rockets(model: "Starship") {
    name
    type
  }
}

Should return two rockets. Changing the type argument to Shuttle should return one rocket.

Mutations resolvers example

const { getExecutableSchema } = require('@lola-tech/graphql-kimera');

// Importing the typeDefs from the `schema.graphql` file...

const executableSchema = getExecutableSchema({
  typeDefs,
  mutationResolversFn: (store, buildMocks) => ({
    // Example of how you would use buildMocks to build a node of a specific
    // type. If the Rocket `type` is omitted from the `input`, the `Shuttle`
    // value defined in the `Rocket` builder is used.
    createRocket: (_, { input }) => {
      let newRocket = null;
      // Example of mocking the unhappy path
      if (input.name !== 'Fail') {
        newRocket = buildMocks('Rocket', { ...input }, true);
        store.update({ rockets: [...store.get('rockets'), newRocket] });
      }

      return {
        successful: input.name !== 'Fail',
        rockets: store.get('rockets'),
      };
    },
  }),
});

// Starting your server using the above defined executable schema ....

Contributing

The main purpose of this repository is to continue to evolve Kimera. Development of Kimera happens in the open on GitHub, and we are grateful to the community for contributing bugfixes and improvements. Read below to learn how you can take part in improving Kimera.

Contributing Guide

We welcome anyone who wants to contribute or provide constructive feedback, no matter the age or level of experience.

Please read CONTRIBUTING.md for the process for submitting pull requests to us.

Code of conduct

Lola Tech has adopted a Code of Conduct that we expect project participants to adhere to. Please read CODE_OF_CONDUCT.md so that you can understand what actions will and will not be tolerated.

Versioning

We use lerna for versioning. For the versions available, see the tags on this repository.

License

This project is licensed under the MIT License. See the LICENSE.md file for details.

Acknowledgements

The "Kimera" name has been inspired from greek mythology - Chimera, and the logo harkens back to the graphql logo.

Tips (FAQ)

Currently, Kimera mocks ID scalars as a string. Perhaps it is possible to mock them with unique values?

Adding different IDs for all types is currently opt in. You can optionally do this as a consumer of Kimera by defining a builder for the ID type in which you can use the uuid package - details here.