Intercepting operations

To inspect and handle GraphQL operations, you define handlers with the graphql namespace. Here is a minimal example:

import { graphql } from 'mock-config-server';

graphql.query('GetUsers', ({ entities }) => ({
  data: {
    users: [{ id: 1, name: 'John' }]
  }
}));

This handler intercepts any query { ... } operation named GetUsers and gives you access to the incoming variables, headers, and cookies. This page introduces the structure of GraphQL handlers and the supported ways of intercepting operations. Refer to the nested pages for more specific cases like matching by operation name and working with variables.

Anatomy Of A GraphQL Handler

Every GraphQL handler consists of an identifier and a response config. The config can be a static value, a resolver function, a generator function, or graphql.polling(). Pass matchers and response settings in the optional third argument.

//            identifier                    settings
//            v                             v
graphql.query('GetUsers', { data: { users: [] } }, { status: 200 });
//                      ^ response config
//

The identifier decides which operations match the handler. The response config decides what response to return.

Identifier

The identifier is what Mock Config uses to match an incoming GraphQL operation to a handler.

Operation Name As A String

Provide a string to match the exact operation name:

graphql.query('GetUsers', { data: { users: [] } });

This matches any query with operationName: 'GetUsers'.

Regular Expression

Provide a regular expression when you want to match a range of operation names:

graphql.query(/^Get/, { data: {} });

This matches any query whose operation name starts with Get.

Advanced Matching

For additional conditions beyond the operation name — such as specific variable values or headers — use a Matcher via the match field:

import { exists, graphql } from 'mock-config-server';

graphql.query(
  'GetUsers',
  { data: { users: [{ id: 1, name: 'John', role: 'admin' }] } },
  {
    match: {
      variables: { role: 'admin' }
    }
  }
);

The identifier filters by operation name first; the matcher then narrows by the request data.

Resolver

The resolver decides what to return when an operation matches the handler.

Static Response

Pass a response object directly when the result is fixed:

graphql.query('GetUsers', { data: { users: [{ id: 1, name: 'John' }] } });

Dynamic Response

Pass a function when the response depends on the request:

graphql.query<{
  body: { variables: { role?: User['role'] } };
  response: { data: { users: User[] } };
}>('GetUsers', ({ entities }) => ({
  data: {
    users: [{ id: 1, name: 'John', role: entities.variables?.role ?? 'admin' }]
  }
}));

Inside the resolver, you can read variables, headers, cookies, and other request metadata. See Resolver params for the full list.

Next Steps

Continue with the nested guides in this section:

• Operation name
• Variables