`](#ergonomockedprovider)\n- [Roadmap](#roadmap)\n- [Contributing](#contributing)\n- [License](#license)\n- [Contact](#contact)\n- [Acknowledgements](#acknowledgements)\n\n\n\n\n## About The Project\n\nThis library provides a developer-friendly method to mock your GraphQL requests. By default, it ships with the following features:\n\n* **Automatic mocking** of types and fields based on schema definition.\n* **Deterministic randomization** of mocked values based on the provided mock shape, to support usage of features such as snapshots.\n* Support for queries using **fragments, unions & interfaces**.\n* Allows usage of **functions as mock values**, which have the signature of a GraphQL resolver, and are resolved at runtime.\n\n### Basic Example\n\n```js\nimport { ergonomock } from 'graphql-ergonomock';\n\n// Given a particular GraphQL Schema, ...\nconst schema = gql`\n type Shape {\n id: ID!\n returnInt: Int\n nestedShape: Shape\n returnBoolean: Boolean\n }\n\n type Query {\n getShape: Shape\n }\n`;\n\n// ...a GraphQL query, ...\nconst query = gql`\n{\n getShape {\n id\n nestedShape {\n returnInt\n nestedShape {\n returnInt\n returnBoolean\n }\n }\n }\n}\n`;\n\n// ...and a partial, possibly nested shape of data...\nconst mocks = {\n getShape: {\n nestedShape: {\n returnInt: 5,\n nestedShape: {\n returnInt: 10\n }\n }\n }\n};\n\n// ... provides the expected object filled with mock data\nconst resp = ergonomock(schema, query, { mocks });\nexpect(resp.data).toMatchObject({\n id: expect.toBeString(),\n nestedShape: {\n returnInt: 5,\n nestedShape: {\n returnInt: 10,\n returnBoolean: expect.toBeBoolean()\n }\n }\n}); // โ
test pass\n```\n\n### Basic Example (Apollo)\n\n```js\nimport { ErgonoMockedProvider as MockedProvider } from \"graphql-ergonomock\";\n\n// Given a particular GraphQL Schema, ...\nconst schema = gql`\n type Shape {\n id: ID!\n returnString: String\n returnBoolean: Boolean\n }\n\n type Query {\n getShape: Shape\n }\n`;\n\n// ...a component making a query ...\nconst QUERY = gql`\nquery MyQuery {\n getShape {\n id\n returnString\n returnBoolean\n }\n}\n`;\nconst MyComponent = () => {\n const { loading, error, data } = useQuery(QUERY);\n if (loading) return Loading
;\n if (error) return Error
;\n\n return (\n \n MyComponent.\n
String: {data.getShape.returnString}
\n
Boolean: {data.getShape.returnBoolean.toString()}
\n
\nSee example
\n\n\n```js\nimport { ergonomock } from 'graphql-ergonomock';\nimport schema from '../my-schema.graphql';\n\ntest(\"I can mock a response\", () => {\n const resp = ergonomock(schema, 'query MyCrucialOperation { car { id, plateNumber } }', {\n mocks: { car: { plateNumber: '123abc' } }\n });\n\n expect(resp).toMatchObject({\n data: {\n car: {\n id: expect.toBeString(),\n plateNumber: '123abc'\n }\n }\n });\n});\n```\n
\n \n\n#### ErgonoMockedProvider for Use with Apollo-Client\n\nIf 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).\n\n\nSee example
\n\n\n```jsx\nimport { ErgonoMockedProvider as MockedProvider } from 'graphql-ergonomock';\nimport schema from '../my-schema.graphql';\n\ntest(\"I can mock a response\", () => {\n const mocks = {\n MyCrucialOperation: {\n car: { plateNumber: '123abc' }\n }\n };\n const { findByText } = render(\n \n \n \n );\n expect(await findByText(/'123abc'/)).toBeVisible();\n});\n```\n
\n \n\nIf 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.\n
\n\nSee example
\n\n\n```jsx\nimport { ErgonoMockedProvider as MockedProvider } from 'graphql-ergonomock';\nimport schema from '../my-schema.graphql';\n\ntest(\"I can mock a response with a function\", () => {\n let cardinality = 0;\n const mocks = {\n MyCrucialOperation: (operation) => ({ plateNumber: `aaa00${cardinality++}` })\n };\n const { findAllByText } = render(\n \n \n \n );\n expect(await findAllByText(/'aaa00'/)).toHaveLength(3);\n});\n```\n
\n\nFinally, you can spy on executed operations via the `onCall` prop.\n
\n\nSee example
\n\n```jsx\nconst spy = jest.fn();\nconst { findByText } = render(\n \n \n \n \n \n);\n\n//...\nexpect(spy.mock.calls).toHaveLength(3);\nconst { operation, response } = spy.mock.calls[0][0];\nexpect(operation.variables.id).toEqual(\"1\");\n```\n
\n\n\n\n\n#### Providing Functions as Resolver in the Mock Shape\n\nYou 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`.\n\n\nSee example
\n\n```js\n// ...\nconst mocks = {\n returnShape: {\n returnInt: 4321,\n nestedShape: (root: any, args: any, ctx: any, info: any) => {\n return {\n returnInt: root.someField ? 1234 : 5678\n };\n }\n }\n}\n//...\n```\n
\n\n\n#### Providing default mock resolver functions\n\nIf 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.\n\n\nSee example
\n\n```js\nconst schema = gql`\n type Shape = {\n id: ID!\n returnInt: Int\n date: Date\n nestedShape: Shape\n }\n\n type Query {\n getShape: Shape\n }\n`;\n\nconst testQuery = gql`\n{\n getShape {\n id\n returnInt\n date\n nestedShape {\n date\n }\n }\n}\n`;\n\nconst resp = ergonomock(schema, testQuery, {\n resolvers: {\n Date: () => \"2021-04-09\"\n }\n});\nexpect(resp.data).toMatchObject({\n id: expect.toBeString(),\n returnInt: expect.toBeNumber(),\n date: '2021-04-09'\n nestedShape {\n date: '2021-04-09'\n }\n});\n```\n
\n\n#### Mocking Errors\n\nYou can return or throw errors within the mock shape.\n\n\nSee example
\n\n```js\nconst testQuery = gql`\n {\n getCar {\n id\n }\n }\n`;\n\nconst resp = ergonomock(schema, testQuery, {\n mocks: {\n getCar: () => { throw new Error(\"Server Error\"); }\n // or simply getCar: new Error(\"Server Error\")\n }\n});\n\nconsole.log(resp.data.getCar); // null\nconsole.log(resp.errors[0]); // { message: \"Server Error\", ...}\n```\n
\n\n\n#### Mocking Mutations\n\nYou 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.\n\n\nSee example
\n\n```jsx\ntest(\"Can partially mock mutations\", () => {\n const query = /* GraphQL */ `\n mutation SampleQuery($input: ShapeInput!) {\n createShape(input: $input) {\n id\n returnInt\n returnString\n }\n }\n `;\n\n const resp: any = ergonomock(schema, query, {\n mocks: {\n createShape: { id: \"567\" }\n },\n variables: {\n input: { someID: \"123\", someInt: 123 }\n }\n });\n\n expect(resp.data.createShape).toMatchObject({\n id: \"567\",\n returnInt: expect.toBeNumber(),\n returnString: expect.toBeString()\n });\n});\n```\n
\n\n\n## API\n\n### `ergonomock()`\n\nThe `ergonomock(schema, query, options)` function takes 3 arguments\n\n1. _(required)_ A GraphQL **schema** (not in SDL form).\n2. _(required)_ A GraphQL **query**, either in SDL (string) form, or `DocumentNode`.\n3. _(optional)_ An option object.\n 1. `mocks` is an object that can partially or fully match the expected response shape.\n 2. `seed` is a string used to seed the random number generator for automocked values.\n 3. `variables` is the variable values object used in the query or mutation.\n\n\n### ``\n\nThis 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:\n\n- `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.)\n- `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()`.\n- `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`.\n\n\n## Roadmap\n\nSee the [open issues](https://github.com/SurveyMonkey/graphql-ergonomock/issues) for a list of proposed features (and known issues).\n\n\n\n## Contributing\n\nContributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are **greatly appreciated**.\n\n1. Fork the Project\n2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the Branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n\n\n\n## License\n\nDistributed under the MIT License. See `LICENSE` for more information.\n\n\n\n## Contact\n\nMaintainer: Joel Marcotte (Github [@joual](https://github.com/joual))\n\nProject Link: [https://github.com/SurveyMonkey/graphql-ergonomock](https://github.com/SurveyMonkey/graphql-ergonomock)\n\n\n\n## Acknowledgements\n\n* [A new approach to mocking GraphQL Data](https://www.freecodecamp.org/news/a-new-approach-to-mocking-graphql-data-1ef49de3d491/)\n* [GraphQL-Tools](https://github.com/apollographql/graphql-tools)\n* [GraphQL-JS](https://github.com/graphql/graphql-js)\n\n\n\n\n[contributors-shield]: https://img.shields.io/github/contributors/SurveyMonkey/graphql-ergonomock.svg?style=flat-square\n[contributors-url]: https://github.com/SurveyMonkey/graphql-ergonomock/graphs/contributors\n[forks-shield]: https://img.shields.io/github/forks/SurveyMonkey/graphql-ergonomock.svg?style=flat-square\n[forks-url]: https://github.com/SurveyMonkey/graphql-ergonomock/network/members\n[stars-shield]: https://img.shields.io/github/stars/SurveyMonkey/graphql-ergonomock.svg?style=flat-square\n[stars-url]: https://github.com/SurveyMonkey/graphql-ergonomock/stargazers\n[version-url]:https://www.npmjs.com/package/graphql-ergonomock\n[version-shield]:https://img.shields.io/npm/v/graphql-ergonomock.svg?style=flat-square\n[issues-shield]: https://img.shields.io/github/issues/SurveyMonkey/graphql-ergonomock.svg?style=flat-square\n[issues-url]: https://github.com/SurveyMonkey/graphql-ergonomock/issues\n[license-shield]: https://img.shields.io/github/license/SurveyMonkey/graphql-ergonomock.svg?style=flat-square\n[license-url]: https://github.com/SurveyMonkey/graphql-ergonomock/blob/master/LICENSE.txt\n[circleci-shield]: https://circleci.com/gh/SurveyMonkey/graphql-ergonomock.svg?style=shield\n[circleci-url]: https://app.circleci.com/pipelines/github/SurveyMonkey/graphql-ergonomock\n[codecov-shield]: https://codecov.io/gh/SurveyMonkey/graphql-ergonomock/branch/master/graph/badge.svg\n[codecov-url]: https://codecov.io/gh/SurveyMonkey/graphql-ergonomock\n","readmeFilename":"README.md"}