Mock Apollo Client for Unit Testing

Common errors

• TypeError: Cannot read properties of undefined (reading 'query')

  cause Often occurs when an older version of `mock-apollo-client` is used with a newer `@apollo/client` or vice-versa, leading to incompatible client interfaces.
  fix Verify that your `mock-apollo-client` and `@apollo/client` versions are compatible. For `@apollo/client@4.x`, use `mock-apollo-client@2.x`. For `@apollo/client@3.x`, use `mock-apollo-client@1.x`.

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use CommonJS `require()` syntax in an ESM project, or when the library is specifically published as ESM-only.
  fix Use ES module `import` syntax: `import { createMockClient } from 'mock-apollo-client';`.

• Error: GraphQL query was not found in the mock client's request handlers.

  cause A GraphQL query was executed by the component under test, but no `setRequestHandler` was defined for that specific query in the `mock-apollo-client` instance.
  fix Ensure that `mockClient.setRequestHandler()` is called for every `gql` document (query or mutation) that your component is expected to execute during the test, before rendering the component.

Warnings

• breaking Major versions of `mock-apollo-client` are tightly coupled to major versions of `@apollo/client`. Using an incompatible version combination will lead to runtime errors or unexpected behavior.
  Fix: Consult the `mock-apollo-client` README or changelog for compatibility tables. Ensure your `mock-apollo-client` version matches your `@apollo/client` version (e.g., `mock-apollo-client@2.x` for `@apollo/client@4.x`).
• gotcha When using `setRequestHandler`, remember that the handler function is called with the variables provided to the GraphQL operation. This is your opportunity to assert variable values or dynamically change mock data based on inputs.
  Fix: Pass a function to `setRequestHandler` that accepts the `variables` argument and perform your assertions or data manipulation within it, e.g., `(variables) => { expect(variables).toEqual({ name: 'test' }); return Promise.resolve(...) }`.
• gotcha `mock-apollo-client` is designed to complement, not entirely replace, `@apollo/client/testing`'s `MockedProvider`. For very simple, static mock scenarios, `MockedProvider` might be sufficient. `mock-apollo-client` shines in tests requiring dynamic responses, assertion of call variables/counts, or controlling loading states.
  Fix: Evaluate your testing needs. If you require more control, such as asserting specific variables, dynamic responses, or error conditions not easily handled by `MockedProvider`, then `mock-apollo-client` is the appropriate choice.

Install

• npm install mock-apollo-client npm
• yarn add mock-apollo-client yarn
• pnpm add mock-apollo-client pnpm

Imports

• createMockClient
  wrong:

  const { createMockClient } = require('mock-apollo-client');

  correct:

  import { createMockClient } from 'mock-apollo-client';

  Primarily designed for ESM usage. While CJS might work via transpilation, direct require is not the recommended or native import style. The library ships with TypeScript types.
• createMockClient (type)

  import type { ApolloClient } from '@apollo/client';
  import { createMockClient } from 'mock-apollo-client';

  When mocking, you'll often need to import types from @apollo/client itself for proper type inference and safety.
• setRequestHandler

  mockClient.setRequestHandler(GET_DOG_QUERY, () => { /* ... */ });

  This is a method on the `createMockClient` instance, not a direct export. It's the primary way to define mock responses for specific GraphQL operations.

Quickstart

This quickstart demonstrates how to create a mock Apollo client, define a mock response for a specific GraphQL query using `setRequestHandler`, and render a component wrapped in `ApolloProvider` with the mocked client. It also shows basic assertion of query variables and the rendered output.

import '@testing-library/jest-dom';
import { ApolloProvider, gql } from '@apollo/client/react';
import { render, screen } from '@testing-library/react';
import { createMockClient } from 'mock-apollo-client';

// Imagine this is in dog.jsx
export const GET_DOG_QUERY = gql`
  query getDog($name: String) {
    dog(name: $name) {
      id
      name
      breed
    }
  }
`;

// Imagine this is in dog.jsx
import { useQuery } from '@apollo/client/react';
export const Dog = ({ name }) => {
  const { loading, error, data } = useQuery(GET_DOG_QUERY, {
    variables: { name },
  });
  if (loading) return <p>Loading...</p>;
  if (error) return <p>{error.message}</p>;

  return (
    <p>
      {data.dog.name} is a {data.dog.breed}
    </p>
  );
};

describe('Dog component', () => {
  it('renders the dog name and breed', async () => {
    const mockClient = createMockClient();

    mockClient.setRequestHandler(GET_DOG_QUERY, (variables) => {
      // Assert variables if needed
      expect(variables.name).toBe('Rufus');
      return Promise.resolve({
        data: { dog: { id: 1, name: 'Rufus', breed: 'Poodle' } },
      });
    });

    render(
      <ApolloProvider client={mockClient}>
        <Dog name="Rufus" />
      </ApolloProvider>,
    );

    expect(await screen.findByText('Rufus is a Poodle')).toBeInTheDocument();
  });
});