Docs
Launch GraphOS Studio
Apollo Server 3 is officially deprecated, with end-of-life scheduled for 22 October 2024. Learn more about upgrading to a supported Apollo Server version.

Mocking

Mock your GraphQL data based on a schema.


Mocking enables to return simulated data for based on your server's schema. The strongly-typed nature of a GraphQL API lends itself to mocking, which is an important part of a GraphQL-first development process.

Mocking enables frontend developers to build out and test UI components and features without needing to wait for a full backend implementation. Mocking is also valuable when using a UI tool like Storybook, because you don't need to start a real .

Using default mocks

You can turn on 's default mocking logic by passing mocks: true to the ApolloServer constructor:

const { ApolloServer, gql } = require('apollo-server');
const typeDefs = gql`
type Query {
hello: String
}
`;
const server = new ApolloServer({
typeDefs,
mocks: true,
});
server.listen().then(({ url }) => {
console.log(`🚀 Server ready at ${url}`)
});

Mocking logic looks at the type returned by each schema and returns a default value for that type.

The table below covers the default types and the default mocked values returned for each type:

TypeDefault Mock Value
Int

Returns a random positive or negative integer.

String

Returns Hello world.

Float

Returns a random positive or negative double-precision floating-point value.

Boolean

Randomly returns either true or false.

ID

Returns a randomized UUID containing a combination of integers and letters.

When using mocks, you don't have to specify resolvers. By default, any resolvers you specify are ignored when you enable mocks. To configure this behavior, see Using existing resolvers with mocks.

Note: If typeDefs has any custom scalar types, you will need to specify what your server should return for those types. You can do this by creating a customized mock with for each custom type, as described below.

Customizing mocks

For more sophisticated testing, you can customize your mocks to return user-specified data.

Instead of providing a boolean to the mocks option, you can provide an object that defines custom mocking logic. This enables you to specify values to return for different return types.

By default, the functions in mocks take precedence over any currently defined . In the below example, both Query.hello and Query.resolved return Hello.

const { ApolloServer, gql } = require('apollo-server');
const typeDefs = gql`
type Query {
hello: String
resolved: String
}
`;
const resolvers = {
Query: {
resolved: () => 'Resolved',
},
};
const mocks = {
Int: () => 6,
Float: () => 22.1,
String: () => 'Hello',
};
const server = new ApolloServer({
typeDefs,
resolvers,
mocks,
});
server.listen().then(({ url }) => {
console.log(`🚀 Server ready at ${url}`)
});

You can also use mocks to define and the belonging to those object types (much like a resolver map).

In the below example, note that our mocked Person object calls a function returning an object with that contain other functions:

// importing the casual library
const casual = require('casual');
const mocks = {
Person: () => ({
name: casual.name,
age: () => casual.integer(0, 120),
}),
};

The previous example uses casual, a fake data generator for JavaScript that returns a different result every time the function is called. In other scenarios, such as testing, a collection of fake objects or a generator that always uses a consistent seed are often necessary to provide consistent data.

Using lists in mocks

To automate mocking a list, return an array of the desired length. Using [...new Array(n)] is convenient syntax for creating an array that contains n copies of undefined.

const casual = require('casual');
const mocks = {
Person: () => ({
// a list of length between 2 and 6, using the "casual" npm module
// to generate a random integer
friends: [...new Array(casual.integer(2, 6))],
// a list of three lists of two items: [[1, 1], [2, 2], [3, 3]]
listOfLists: () => [...new Array(3)].map((i) => [...new Array(2)]),
}),
};

Using existing resolvers with mocks

The default behavior for mocks is to overwrite the already present in the schema. To use your server's existing resolvers while mocking, set the mockEntireSchema option to false.

Note: Mocking doesn't work if the mocks option is false, even if mockEntireSchema is true.

const { ApolloServer, gql } = require('apollo-server');
const typeDefs = gql`
type Query {
hello: String
resolved: String
}
`;
const resolvers = {
Query: {
resolved: () => 'Resolved',
},
};
const mocks = {
Int: () => 6,
Float: () => 22.1,
String: () => 'Hello',
};
const server = new ApolloServer({
typeDefs,
resolvers,
mocks,
mockEntireSchema: false,
});
server.listen().then(({ url }) => {
console.log(`🚀 Server ready at ${url}`)
});

Running the above example with the mockEntireSchema option set to false, the resolved now returns the string Resolved.

Mocking a schema using introspection

The specification allows clients to introspect the schema with a special set of types and fields that every schema must include. The results of a standard introspection query can be used to generate an instance of GraphQLSchema that can be mocked as explained above.

This helps when you need to mock a schema defined in a language besides JavaScript.

To convert an introspection query result to a GraphQLSchema object, you can use the buildClientSchema utility from the graphql package.

const { buildClientSchema } = require('graphql');
const introspectionResult = require('schema.json');
const { ApolloServer } = require('apollo-server');
const schema = buildClientSchema(introspectionResult.data);
const server = new ApolloServer({
schema,
mocks: true,
});
server.listen().then(({ url }) => {
console.log(`🚀 Server ready at ${url}`)
});

API

Under the hood, 's mocking functionality is provided by the function addMocksToSchema from the @graphql-tools/mock package. The mocks object is passed directly to the addMocksToSchema function, and preserveResolvers is the inverse of mockEntireSchema.

does not support all of the to addMocksToSchema, such as resolvers. To use features of @graphql-tools/mock that aren't supported by , you can install and use @graphql-tools/mock directly:

const { addMocksToSchema } = require('@graphql-tools/mock')
const { makeExecutableSchema } = require('@graphql-tools/schema');
const server = new ApolloServer({
schema: addMocksToSchema({
schema: makeExecutableSchema({ typeDefs, resolvers }),
}),
});
Previous
Request format
Next
Integration testing
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company