https://github.com/DataArt-Romania/graphql-kimera
Kimera allows you to mock GraphQL schemas with precision
https://github.com/DataArt-Romania/graphql-kimera
Last synced: about 1 year ago
JSON representation
Kimera allows you to mock GraphQL schemas with precision
- Host: GitHub
- URL: https://github.com/DataArt-Romania/graphql-kimera
- Owner: lola-tech
- License: mit
- Created: 2020-04-15T13:13:07.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2023-12-15T05:21:32.000Z (over 2 years ago)
- Last Synced: 2024-11-06T09:49:01.147Z (over 1 year ago)
- Language: JavaScript
- Homepage: https://lola-tech.github.io/graphql-kimera/
- Size: 4.45 MB
- Stars: 26
- Watchers: 10
- Forks: 0
- Open Issues: 20
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-list - graphql-kimera - tech | 24 | (JavaScript)
README
---
# What is Kimera?
Kimera is an automocking library for GraphQL that allows you to be very precise about how mocks should be generated.
[](https://img.shields.io/badge/license-MIT-blue)  [](http://makeapullrequest.com)
  [](https://codecov.io/gh/lola-tech/graphql-kimera) [](https://spectrum.chat/graphql-kimera)
## 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](https://github.com/lola-tech/graphql-kimera/blob/master/packages/graphql-kimera/src/__test__/testing.schema.graphql).
#### Basic Example
Running the `rockets` query will return four rockets, all of type `Shuttle`, with the first being called `Apollo`.
```js
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: () => ({
type: '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.
```js
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) => (_, { type }) => {
// `mocks` is a store that contains the mocks for the `rockets` query
const rockets = mocks.get();
return type
? rockets.filter((rocket) => rocket.type === type)
: rockets;
},
// Optionally define a node scenario
[{}, { type: 'Starship' }, { type: 'Starship' }]
),
},
builders: {
Rocket: () => ({
type: 'Shuttle',
}),
},
}),
});
// Starting your server using the above defined executable schema ....
```
Now running:
```graphql
query {
rockets(type: "Starship") {
name
type
}
}
```
Should return two rockets. Changing the `type` argument to `Shuttle` should return one rocket.
#### Mutations resolvers example
```js
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](https://github.com/lola-tech/graphql-kimera/blob/master/CONTRIBUTING.md) for the process for submitting pull requests to us.
### Code of conduct
[Lola Tech](https://www.lola.tech/) has adopted a Code of Conduct that we expect project participants to adhere to. Please read [CODE_OF_CONDUCT.md](https://github.com/lola-tech/graphql-kimera/blob/master/CODE_OF_CONDUCT.md) so that you can understand what actions will and will not be tolerated.
## Versioning
We use [lerna](https://lerna.js.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/lola-tech/graphql-kimera/tags).
## License
This project is licensed under the MIT License. See the [LICENSE.md](https://github.com/lola-tech/graphql-kimera/blob/master/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](https://www.npmjs.com/package/uuid) package - [details here](https://github.com/lola-tech/graphql-kimera/issues/64#issuecomment-636201513).