https://github.com/surveymonkey/graphql-ergonomock
Automatic mocking of GraphQL queries
https://github.com/surveymonkey/graphql-ergonomock
apollo apollo-client factory fixtures graphql mock mocking test testing
Last synced: about 1 year ago
JSON representation
Automatic mocking of GraphQL queries
- Host: GitHub
- URL: https://github.com/surveymonkey/graphql-ergonomock
- Owner: SurveyMonkey
- License: mit
- Created: 2020-03-08T12:50:45.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2025-04-13T09:33:18.000Z (about 1 year ago)
- Last Synced: 2025-04-13T10:32:24.029Z (about 1 year ago)
- Topics: apollo, apollo-client, factory, fixtures, graphql, mock, mocking, test, testing
- Language: TypeScript
- Size: 436 KB
- Stars: 19
- Watchers: 1
- Forks: 6
- Open Issues: 26
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
[![CircleCI][circleci-shield]][circleci-url]
[![CodeCov][codecov-shield]][codecov-url]
[![Contributors][contributors-shield]][contributors-url]
[![Forks][forks-shield]][forks-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![Version][version-shield]][version-url]
[![MIT License][license-shield]][license-url]
GraphQL Ergonomock
🔮 Developer-friendly automagical mocking for GraphQL
Report Bug
·
Request Feature
## Table of Contents
- [Table of Contents](#table-of-contents)
- [About The Project](#about-the-project)
- [Basic Example](#basic-example)
- [Basic Example (Apollo)](#basic-example-apollo)
- [Built With](#built-with)
- [Getting Started](#getting-started)
- [Installation](#installation)
- [Usage](#usage)
- [Default Case](#default-case)
- [ErgonoMockedProvider for Use with Apollo-Client](#ergonomockedprovider-for-use-with-apollo-client)
- [Providing Functions as Resolver in the Mock Shape](#providing-functions-as-resolver-in-the-mock-shape)
- [Mocking Errors](#mocking-errors)
- [Mocking Mutations](#mocking-mutations)
- [API](#api)
- [`ergonomock()`](#ergonomock)
- [``](#ergonomockedprovider)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
- [License](#license)
- [Contact](#contact)
- [Acknowledgements](#acknowledgements)
## About The Project
This library provides a developer-friendly method to mock your GraphQL requests. By default, it ships with the following features:
* **Automatic mocking** of types and fields based on schema definition.
* **Deterministic randomization** of mocked values based on the provided mock shape, to support usage of features such as snapshots.
* Support for queries using **fragments, unions & interfaces**.
* Allows usage of **functions as mock values**, which have the signature of a GraphQL resolver, and are resolved at runtime.
### Basic Example
```js
import { ergonomock } from 'graphql-ergonomock';
// Given a particular GraphQL Schema, ...
const schema = gql`
type Shape {
id: ID!
returnInt: Int
nestedShape: Shape
returnBoolean: Boolean
}
type Query {
getShape: Shape
}
`;
// ...a GraphQL query, ...
const query = gql`
{
getShape {
id
nestedShape {
returnInt
nestedShape {
returnInt
returnBoolean
}
}
}
}
`;
// ...and a partial, possibly nested shape of data...
const mocks = {
getShape: {
nestedShape: {
returnInt: 5,
nestedShape: {
returnInt: 10
}
}
}
};
// ... provides the expected object filled with mock data
const resp = ergonomock(schema, query, { mocks });
expect(resp.data).toMatchObject({
id: expect.toBeString(),
nestedShape: {
returnInt: 5,
nestedShape: {
returnInt: 10,
returnBoolean: expect.toBeBoolean()
}
}
}); // ✅ test pass
```
### Basic Example (Apollo)
```js
import { ErgonoMockedProvider as MockedProvider } from "graphql-ergonomock";
// Given a particular GraphQL Schema, ...
const schema = gql`
type Shape {
id: ID!
returnString: String
returnBoolean: Boolean
}
type Query {
getShape: Shape
}
`;
// ...a component making a query ...
const QUERY = gql`
query MyQuery {
getShape {
id
returnString
returnBoolean
}
}
`;
const MyComponent = () => {
const { loading, error, data } = useQuery(QUERY);
if (loading) return
Loading
;
if (error) return Error
;
return (
MyComponent.
String: {data.getShape.returnString}
Boolean: {data.getShape.returnBoolean.toString()}
);
};
test("MyComponent can render the query results.", async () => {
const mocks = {
MyQuery: {
getShape: { returnString: "John Doe" }
}
};
const { findByText } = render(
);
expect(await findByText(/String: John Doe/)).toBeVisible();
expect(await findByText(/Boolean: (true|false)/)).toBeVisible();
}); // ✅ test pass
```
### Built With
* [Typescript](https://www.typescriptlang.org/)
* [GraphQL](https://graphql.org)
* [Jest](https://jestjs.io)
## Getting Started
### Installation
```shell
npm i graphql-ergonomock --save-dev
```
### Usage
#### Default Case
The `ergonomock()` function can be used on its own to create mock responses out of GraphQL queries.
See example
```js
import { ergonomock } from 'graphql-ergonomock';
import schema from '../my-schema.graphql';
test("I can mock a response", () => {
const resp = ergonomock(schema, 'query MyCrucialOperation { car { id, plateNumber } }', {
mocks: { car: { plateNumber: '123abc' } }
});
expect(resp).toMatchObject({
data: {
car: {
id: expect.toBeString(),
plateNumber: '123abc'
}
}
});
});
```
#### ErgonoMockedProvider for Use with Apollo-Client
If your app uses Apollo-Client, you can also use `ErgonoMockedProvider` which wraps `ergonomock()`. The generated values are stable & deterministic based on the query name, shape, and variables (this is so you can leverage testing snapshots if you are so inclined).
See example
```jsx
import { ErgonoMockedProvider as MockedProvider } from 'graphql-ergonomock';
import schema from '../my-schema.graphql';
test("I can mock a response", () => {
const mocks = {
MyCrucialOperation: {
car: { plateNumber: '123abc' }
}
};
const { findByText } = render(
);
expect(await findByText(/'123abc'/)).toBeVisible();
});
```
If a particular component is called multiple times in the React tree (but with different variables), you can provide a function as value for an operation, and the function will be called with the `operation: GraphQLOperation` as first and only argument.
See example
```jsx
import { ErgonoMockedProvider as MockedProvider } from 'graphql-ergonomock';
import schema from '../my-schema.graphql';
test("I can mock a response with a function", () => {
let cardinality = 0;
const mocks = {
MyCrucialOperation: (operation) => ({ plateNumber: `aaa00${cardinality++}` })
};
const { findAllByText } = render(
);
expect(await findAllByText(/'aaa00'/)).toHaveLength(3);
});
```
Finally, you can spy on executed operations via the `onCall` prop.
See example
```jsx
const spy = jest.fn();
const { findByText } = render(
);
//...
expect(spy.mock.calls).toHaveLength(3);
const { operation, response } = spy.mock.calls[0][0];
expect(operation.variables.id).toEqual("1");
```
#### Providing Functions as Resolver in the Mock Shape
You can use functions for any part of the nested mock, and it will be used as a resolver for this field. The typical signature for a resolver is `(root, args, context, info) => any`.
See example
```js
// ...
const mocks = {
returnShape: {
returnInt: 4321,
nestedShape: (root: any, args: any, ctx: any, info: any) => {
return {
returnInt: root.someField ? 1234 : 5678
};
}
}
}
//...
```
#### Providing default mock resolver functions
If you have custom scalar types or would like to provide default mock resolver functions for certain types, you can pass your mock functions via the `resolvers` option.
See example
```js
const schema = gql`
type Shape = {
id: ID!
returnInt: Int
date: Date
nestedShape: Shape
}
type Query {
getShape: Shape
}
`;
const testQuery = gql`
{
getShape {
id
returnInt
date
nestedShape {
date
}
}
}
`;
const resp = ergonomock(schema, testQuery, {
resolvers: {
Date: () => "2021-04-09"
}
});
expect(resp.data).toMatchObject({
id: expect.toBeString(),
returnInt: expect.toBeNumber(),
date: '2021-04-09'
nestedShape {
date: '2021-04-09'
}
});
```
#### Mocking Errors
You can return or throw errors within the mock shape.
See example
```js
const testQuery = gql`
{
getCar {
id
}
}
`;
const resp = ergonomock(schema, testQuery, {
mocks: {
getCar: () => { throw new Error("Server Error"); }
// or simply getCar: new Error("Server Error")
}
});
console.log(resp.data.getCar); // null
console.log(resp.errors[0]); // { message: "Server Error", ...}
```
#### Mocking Mutations
You can mock mutations, but if you are using `ergonomock()` directly, you'll have to provide the correct variables for the operation in order for it to not fail.
See example
```jsx
test("Can partially mock mutations", () => {
const query = /* GraphQL */ `
mutation SampleQuery($input: ShapeInput!) {
createShape(input: $input) {
id
returnInt
returnString
}
}
`;
const resp: any = ergonomock(schema, query, {
mocks: {
createShape: { id: "567" }
},
variables: {
input: { someID: "123", someInt: 123 }
}
});
expect(resp.data.createShape).toMatchObject({
id: "567",
returnInt: expect.toBeNumber(),
returnString: expect.toBeString()
});
});
```
## API
### `ergonomock()`
The `ergonomock(schema, query, options)` function takes 3 arguments
1. _(required)_ A GraphQL **schema** (not in SDL form).
2. _(required)_ A GraphQL **query**, either in SDL (string) form, or `DocumentNode`.
3. _(optional)_ An option object.
1. `mocks` is an object that can partially or fully match the expected response shape.
2. `seed` is a string used to seed the random number generator for automocked values.
3. `variables` is the variable values object used in the query or mutation.
### ``
This component's props are very similar to Apollo-Client's [MockedProvider](https://www.apollographql.com/docs/react/api/react-testing/#mockedprovider). The only differences are:
- `mocks` is an object where keys are the operation names and the values are the `mocks` input that `ergonomock()` would accept. (i.e. could be empty, or any shape that matches the expected response.)
- `onCall` is a handler that gets called by any executed query. The call signature is `({operation: GraphQLOperation, response: any}) => void` where response is the full response being returned to that single query. The purpose of `onCall` is to provide some sort of spy (or `jest.fn()`) to make assertions on which calls went through, with which variables, and get a handle on the generated values from `ergonomock()`.
- `resolvers` is an object where the keys are the `gql` type and the values are the mock resolver functions. It's designed to allow users to override or provide a default mock function for certain types. (e.g. custom scalar types) The call signature is `(root, args, context, info) => any`.
## Roadmap
See the [open issues](https://github.com/SurveyMonkey/graphql-ergonomock/issues) for a list of proposed features (and known issues).
## Contributing
Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are **greatly appreciated**.
1. Fork the Project
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the Branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## License
Distributed under the MIT License. See `LICENSE` for more information.
## Contact
Maintainer: Joel Marcotte (Github [@joual](https://github.com/joual))
Project Link: [https://github.com/SurveyMonkey/graphql-ergonomock](https://github.com/SurveyMonkey/graphql-ergonomock)
## Acknowledgements
* [A new approach to mocking GraphQL Data](https://www.freecodecamp.org/news/a-new-approach-to-mocking-graphql-data-1ef49de3d491/)
* [GraphQL-Tools](https://github.com/apollographql/graphql-tools)
* [GraphQL-JS](https://github.com/graphql/graphql-js)
[contributors-shield]: https://img.shields.io/github/contributors/SurveyMonkey/graphql-ergonomock.svg?style=flat-square
[contributors-url]: https://github.com/SurveyMonkey/graphql-ergonomock/graphs/contributors
[forks-shield]: https://img.shields.io/github/forks/SurveyMonkey/graphql-ergonomock.svg?style=flat-square
[forks-url]: https://github.com/SurveyMonkey/graphql-ergonomock/network/members
[stars-shield]: https://img.shields.io/github/stars/SurveyMonkey/graphql-ergonomock.svg?style=flat-square
[stars-url]: https://github.com/SurveyMonkey/graphql-ergonomock/stargazers
[version-url]:https://www.npmjs.com/package/graphql-ergonomock
[version-shield]:https://img.shields.io/npm/v/graphql-ergonomock.svg?style=flat-square
[issues-shield]: https://img.shields.io/github/issues/SurveyMonkey/graphql-ergonomock.svg?style=flat-square
[issues-url]: https://github.com/SurveyMonkey/graphql-ergonomock/issues
[license-shield]: https://img.shields.io/github/license/SurveyMonkey/graphql-ergonomock.svg?style=flat-square
[license-url]: https://github.com/SurveyMonkey/graphql-ergonomock/blob/master/LICENSE.txt
[circleci-shield]: https://circleci.com/gh/SurveyMonkey/graphql-ergonomock.svg?style=shield
[circleci-url]: https://app.circleci.com/pipelines/github/SurveyMonkey/graphql-ergonomock
[codecov-shield]: https://codecov.io/gh/SurveyMonkey/graphql-ergonomock/branch/master/graph/badge.svg
[codecov-url]: https://codecov.io/gh/SurveyMonkey/graphql-ergonomock