⭐️ graphql-automock ⭐️
Automatically mock GraphQL schemas for better testing.
Features:
- Automatically and deterministically mock GraphQL schemas
- Mock
react-apollo
for simple UI testing - Control schema execution to reliably test loading and success states
Getting started
Install via npm or yarn:
npm install --save-dev graphql-automock
yarn add --dev graphql-automock
Mocking just the schema
Simply pass your GraphQL type definitions to mockSchema
and
you're ready to go:
import { mockSchema } from "graphql-automock";
import { graphql } from "graphql";
const types = `
type Query {
recentPosts: [Post!]!
}
type Post {
id: ID!
content: String!
likes: Int!
}
`;
const mocked = mockSchema(types);
const query = `{
recentPosts {
id
content
likes
}
}`;
graphql(mocked, query);
Without any further configuration, this query will return:
{
"data": {
"recentPosts": [
{
"id": "recentPosts.0.id",
"content": "recentPosts.0.content",
"likes": 2
},
{
"id": "recentPosts.1.id",
"content": "recentPosts.1.content",
"likes": 2
}
]
}
}
To understand how these values are derived, see Default values.
Mocking react-apollo
In addition to schema mocking, <MockApolloProvider>
makes the testing of UI components much easier.
Simply wrap your elements in a <MockApolloProvider>
, and any
graphql()
and <Query>
components in the tree will be able to function:
import { MockApolloProvider } from "graphql-automock";
<MockApolloProvider schema={types}>
<Post id="123" />
</MockApolloProvider>;
One issue to be aware of when doing this is that components will first enter a loading state, before the query resolves and components re-render
with the query result. You will most likely want to test both states. SchemaController
allows you to step through schema execution to do just that:
import { SchemaController, MockApolloProvider } from "graphql-automock";
import TestUtils from "react-dom/test-utils";
it("renders a Post", async () => {
const controller = new SchemaController();
const tree = TestUtils.renderIntoDocument(
<MockApolloProvider schema={types} controller={controller}>
<Post id="123" />
</MockApolloProvider>
);
const spinners = TestUtils.scryRenderedComponentsWithType(tree, Spinner);
expect(spinners).toHaveLength(1);
await controller.run();
const content = TestUtils.scryRenderedComponentsWithType(tree, Content);
expect(content).toHaveLength(1);
});
Customizing mocks
Automatically mocking the entire schema with sensible, deterministic data allows test code to customize only the data that affects the test. This results in test code that is more concise and easier to understand:
it("hides the likes count when there are no likes", () => {
const mocks = {
Post: () => ({
likes: 0
})
};
const mockedSchema = mockSchema({
schema: types,
mocks: mocks
});
const mockedElements = (
<MockApolloProvider schema={types} mocks={mocks}>
<Post id="123" />
</MockApolloProvider>
);
});
Mocking errors
Both GraphQL errors and network errors can be mocked.
Mocking GraphQL errors
Just like with a real GraphQL implementation, GraphQL errors are generated by throwing an error from a (mock) resolver.
import { mockSchema } from "graphql-automock";
mockSchema({
schema: types,
mocks: {
Post: () => {
throw new Error("Could not retrieve Post");
}
}
});
Mocking network errors
Since network errors are external to the GraphQL schema, they are generated with a SchemaController
.
import { SchemaController, MockApolloProvider } from "graphql-automock";
import TestUtils from "react-dom/test-utils";
it("renders a Post", async () => {
const controller = new SchemaController();
const tree = TestUtils.renderIntoDocument(
<MockApolloProvider schema={types} controller={controller}>
<Post id="123" />
</MockApolloProvider>
);
const spinners = TestUtils.scryRenderedComponentsWithType(tree, Spinner);
expect(spinners).toHaveLength(1);
await controller.run({
networkError: () => new Error("Disconnected")
});
const errorMessage = TestUtils.scryRenderedComponentsWithType(
tree,
ErrorMessage
);
expect(errorMessage).toHaveLength(1);
});
Default values
To ensure that tests are reliable, the values generated by graphql-automock
are 100% deterministic. The following default values are used:
- Boolean:
true
- Int:
2
- Float:
3.14
- String: Path to value
- ID: Path to value
- Enum: The first enum value, sorted alphabetically by name
- Interface: The first possible implementation, sorted alphabetically by name
- Union: The first possible member type, sorted alphabetically by name
- List length:
2
API Reference
mockSchema()
Create a mocked GraphQL schema.
function mockSchema(schema: String | GraphQLSchema): GraphQLSchema;
function mockSchema({
schema: String | GraphQLSchema,
mocks: { [String]: MockResolverFn }
}): GraphQLSchema;
mockApolloClient()
Create a mocked Apollo Client.
function mockApolloClient(schema: String | GraphQLSchema): ApolloClient;
function mockApolloClient({
schema: String | GraphQLSchema,
mocks: { [String]: MockResolverFn },
controller: SchemaController
}): ApolloClient;
<MockApolloProvider>
React component that renders a mocked ApolloProvider.
<MockApolloProvider
schema={String | GraphQLSchema}
mocks={{ [String]: MockResolverFn }}
controller={SchemaController}
>
type MockResolverFn
type MockResolverFn = (parent, args, context, info) => any;
SchemaController
pause()
function pause(): void;
Pause GraphQL execution until it is explicitly resumed.
SchemaController starts in this state.
run()
function run(): Promise<void>;
function run({ networkError: () => any }): Promise<void>;
Resume GraphQL execution if it is paused.
Returns a Promise that resolves when all pending queries have finished executing. If execution was not paused, then it returns a resolved Promise.
If a networkError
function is provided, pending and subsequent queries will fail with the result of calling that function. The function is called once for each query.