Mocking Apollo Client Mutations in Jest

This challenge focuses on a common scenario in modern web development: testing components that interact with GraphQL APIs using Apollo Client. Specifically, you'll learn how to mock GraphQL mutations in your Jest tests to isolate component logic and ensure predictable test outcomes without needing a live GraphQL server.

Problem Description

Your task is to write Jest unit tests for a React component that performs a GraphQL mutation. You need to use @apollo/client/testing to mock the useMutation hook. This will allow you to:

• Simulate successful mutation responses: Verify that your component handles successful data updates correctly.
• Simulate mutation errors: Ensure your component gracefully handles API errors.
• Assert mutation arguments: Check that the correct variables are being passed to the mutation.

You will be provided with a simple React component that uses useMutation to add a new item to a list. Your goal is to test this component's behavior under different scenarios.

Key Requirements:

1. Mock useMutation: Use MockedProvider from @apollo/client/testing to provide mock responses for your GraphQL mutations.
2. Define Mocked Responses: Create specific MockedResponse objects that match the GraphQL mutation document and variables you intend to mock.
3. Test Success Scenario: Verify that the component renders correctly and updates its state (or performs expected side effects) when the mutation succeeds.
4. Test Error Scenario: Verify that the component displays an appropriate error message or handles the error state when the mutation fails.
5. Test Variable Passing: Assert that the correct variables are sent with the mutation.

Expected Behavior:

• When the mutation is successful, the component should indicate success (e.g., clear form, show a success message).
• When the mutation fails, the component should display an error message to the user.
• The mocked mutation should be called with the expected input variables.

Edge Cases to Consider:

• What happens if the useMutation hook is called without any mocks defined? (Though MockedProvider handles this, understanding the implication is good).
• Handling different GraphQL error structures.

Examples

Example 1: Successful Item Addition

Component (Simplified):

// src/components/AddItemForm.tsx
import React, { useState } from 'react';
import { gql, useMutation } from '@apollo/client';

const ADD_ITEM_MUTATION = gql`
  mutation AddItem($name: String!) {
    addItem(name: $name) {
      id
      name
    }
  }
`;

interface AddItemFormProps {
  onItemAdded: (item: { id: string; name: string }) => void;
}

export const AddItemForm: React.FC<AddItemFormProps> = ({ onItemAdded }) => {
  const [itemName, setItemName] = useState('');
  const [addItem, { error }] = useMutation(ADD_ITEM_MUTATION);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    try {
      const { data } = await addItem({ variables: { name: itemName } });
      if (data && data.addItem) {
        onItemAdded(data.addItem);
        setItemName('');
      }
    } catch (err) {
      // Error is already available via the hook's 'error' property
      console.error("Mutation failed:", err);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        value={itemName}
        onChange={(e) => setItemName(e.target.value)}
        placeholder="Enter item name"
      />
      <button type="submit" disabled={!itemName}>Add Item</button>
      {error && <p data-testid="error-message">Error: {error.message}</p>}
    </form>
  );
};

Test Setup (Conceptual):

// src/components/AddItemForm.test.tsx
import React from 'react';
import { render, screen, fireEvent, waitFor } from '@testing-library/react';
import { MockedProvider } from '@apollo/client/testing';
import { AddItemForm, ADD_ITEM_MUTATION } from './AddItemForm';
import { DocumentNode } from 'graphql';

// Define the GraphQL mutation and expected variables
const ADD_ITEM_MUTATION_DOC: DocumentNode = ADD_ITEM_MUTATION; // Re-export or define if not exported

const mockOnItemAdded = jest.fn();

// Mocked response for a successful mutation
const successMocks = [
  {
    request: {
      query: ADD_ITEM_MUTATION_DOC,
      variables: { name: 'New Gadget' },
    },
    result: {
      data: {
        addItem: {
          __typename: 'Item',
          id: 'item-123',
          name: 'New Gadget',
        },
      },
    },
  },
];

// ... rest of the test

Input: A form with an input field and an "Add Item" button. The user types "New Gadget" into the input field and clicks the "Add Item" button.

Expected Output (during test execution):

• The onItemAdded prop should be called with { id: 'item-123', name: 'New Gadget' }.
• The input field should be cleared.
• No error message should be displayed.

Explanation: The MockedProvider intercepts the ADD_ITEM_MUTATION. Because the request.variables match { name: 'New Gadget' }, MockedProvider returns the result.data defined in successMocks. The component then calls onItemAdded with this data and clears the input.

Example 2: Mutation Failure

Test Setup (Conceptual):

// src/components/AddItemForm.test.tsx (continued)

import { ApolloError } from '@apollo/client';

// Mocked response for a failed mutation
const errorMocks = [
  {
    request: {
      query: ADD_ITEM_MUTATION_DOC,
      variables: { name: 'Broken Item' },
    },
    error: new ApolloError({
      errorMessage: 'Failed to add item.',
      graphQLErrors: [{ message: 'Server error: Validation failed' }],
    }),
  },
];

// ... rest of the test

Input: The user types "Broken Item" into the input field and clicks the "Add Item" button.

Expected Output (during test execution):

• The onItemAdded prop should NOT be called.
• An error message containing "Error: Server error: Validation failed" (or similar from the error.message) should be visible on the screen.

Explanation: When the mutation is executed with variables: { name: 'Broken Item' }, MockedProvider matches the request and returns the defined error. The component's useMutation hook will then populate its error state, causing the error message to be displayed.

Example 3: Asserting Variables

Test Setup (Conceptual):

// src/components/AddItemForm.test.tsx (continued)

// Test that explicitly checks variables
test('calls mutation with correct variables', async () => {
  render(
    <MockedProvider mocks={successMocks} addTypename={false}>
      <AddItemForm onItemAdded={mockOnItemAdded} />
    </MockedProvider>
  );

  const inputElement = screen.getByPlaceholderText('Enter item name');
  fireEvent.change(inputElement, { target: { value: 'Test Item Variables' } });

  const submitButton = screen.getByRole('button', { name: /add item/i });
  fireEvent.click(submitButton);

  // Wait for the mutation to be processed and the UI to update
  await waitFor(() => {
    expect(mockOnItemAdded).toHaveBeenCalledTimes(1);
  });

  // Now, check the actual request that was made against the mock
  const mutationMock = successMocks.find(
    (mock) => mock.request.query === ADD_ITEM_MUTATION_DOC
  );

  expect(mutationMock).toBeDefined();
  expect(mutationMock!.request.variables).toEqual({ name: 'Test Item Variables' });
});

Input: User types "Test Item Variables" and clicks "Add Item".

Expected Output (during test execution):

• The test passes if successMocks (or a similar mock) was configured to expect { name: 'Test Item Variables' } and the actual mutation call matches this.

Explanation: This test goes beyond just checking component behavior. It verifies that the addItem function from useMutation was indeed called with the expected variables object. This is crucial for ensuring your component is correctly preparing data for the API.

Constraints

• Your solution must be written in TypeScript.
• You must use @apollo/client/testing and specifically the MockedProvider component.
• Tests should be written using @testing-library/react.
• The mocked responses should accurately reflect the GraphQL schema for addItem.
• Avoid making actual network requests.

Notes

• MockedProvider works by matching request objects (query and variables) against the mocks you provide. The first matching mock will be used.
• The result object in a MockedResponse should mirror the structure of your GraphQL response, including __typename fields for better Apollo Client integration.
• You can define multiple mocks for the same query to test different scenarios or to simulate sequential calls.
• Consider using jest.fn() to mock callbacks passed as props (like onItemAdded in the example).
• Remember to await operations that involve asynchronous updates, such as waiting for mutations to complete using waitFor.
• The addTypename={false} option in MockedProvider can sometimes simplify mock definitions by omitting __typename fields, but it's generally good practice to include them.