Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
GraphQLHandler
✓ import { GraphQLHandler } from 'graphql-mocks';
✗ const { GraphQLHandler } = require('graphql-mocks');
`graphql-mocks` is primarily designed for ESM usage, but CJS is supported with appropriate tooling. Always prefer named imports.
createResolverMap
✓ import { createResolverMap } from 'graphql-mocks';
✗ import createResolverMap from 'graphql-mocks/createResolverMap';
A utility function to structure resolver maps, imported as a named export from the main package.
highlight
✓ import { highlight } from 'graphql-mocks';
✗ import { Highlight } from 'graphql-mocks';
The debugging utility `highlight` is a named export, not a class or default export.
This quickstart demonstrates how to set up a `GraphQLHandler` with a schema and a resolver map, then execute a mock query and mutation against it, simulating a GraphQL API.
import { buildSchema } from 'graphql';
import { GraphQLHandler, createResolverMap } from 'graphql-mocks';
const typeDefs = `
type User {
id: ID!
name: String!
email: String
}
type Query {
hello: String!
user(id: ID!): User
users: [User!]!
}
type Mutation {
createUser(name: String!, email: String): User!
}
`;
// Create a GraphQL schema from the type definitions
const schema = buildSchema(typeDefs);
// Define a resolver map with mock data and logic
const resolverMap = createResolverMap({
Query: {
hello: () => 'Hello GraphQL Mocks!',
user: (parent, { id }) => ({ id, name: `User ${id}`, email: `user${id}@example.com` }),
users: () => [
{ id: '1', name: 'Alice', email: 'alice@example.com' },
{ id: '2', name: 'Bob', email: 'bob@example.com' }
]
},
Mutation: {
createUser: (parent, { name, email }) => ({ id: String(Math.random()), name, email })
}
});
// Initialize the GraphQLHandler with the schema and resolver map
const handler = new GraphQLHandler({
schema,
resolverMap
});
async function runMockOperations() {
// Execute a mock query
const query = `
query GetUsers {
users {
id
name
email
}
}
`;
const queryResult = await handler.query(query);
console.log('Mocked Query Result:', queryResult.data);
// Execute a mock mutation
const mutation = `
mutation CreateNewUser {
createUser(name: "Charlie", email: "charlie@example.com") {
id
name
}
}
`;
const mutationResult = await handler.mutate(mutation);
console.log('Mocked Mutation Result:', mutationResult.data);
}
runMockOperations();
Errors
Common errors & fixes
Error: Cannot find module 'graphql-mocks'
The `graphql-mocks` package is not installed or the import path is incorrect.
fixRun `npm install graphql-mocks` or `yarn add graphql-mocks`. Verify your import statement uses `from 'graphql-mocks'`.
Error: Expected `schema` to be a GraphQLSchema instance, but got [object Object]
The `schema` provided to `GraphQLHandler` is not a valid `GraphQLSchema` object from the `graphql` library.
fixEnsure you are using `buildSchema` from `graphql` to create your schema, or that the schema object is correctly instantiated.
GraphQLError: Cannot query field "unknownField" on type "Query".
Attempting to query a field that is not defined in the GraphQL schema provided to the `GraphQLHandler`.
fixReview your GraphQL schema (`typeDefs`) and the query you are sending to ensure all fields are correctly defined and match.
Audit
Dependencies
graphqlrequiredCore GraphQL library for schema definition and execution, required as a peer dependency.