How to Properly Make a Mock Throw an Error in Jest for GraphQL API Testing

Testing GraphQL APIs is critical to ensuring they handle both success and failure scenarios gracefully. Unlike REST APIs, GraphQL often returns errors within the response payload (even for HTTP 200 status codes), making error handling logic a key part of your application’s reliability.

Jest, a popular JavaScript testing framework, excels at isolating tests by mocking dependencies—including GraphQL resolvers, clients (e.g., Apollo Client), and external services. However, mocking errors correctly is non-trivial: you need to simulate realistic failure scenarios (e.g., validation errors, network issues, or database failures) and ensure your application responds as expected.

This guide will walk you through how to make mocks throw errors in Jest for GraphQL testing, with step-by-step examples for resolvers, clients, and common error types. By the end, you’ll be able to confidently test error handling in both server-side resolvers and client-side components.

Table of Contents#

  1. Prerequisites
  2. Understanding Mocks and Errors in Jest
  3. Setting Up Your Project for GraphQL Testing
  4. Mocking GraphQL Resolvers/Client in Jest
  5. Making Mocks Throw Errors: Step-by-Step
  6. Testing Error Handling in Your Application
  7. Best Practices for Mocking Errors in Jest
  8. Common Pitfalls and How to Avoid Them
  9. Conclusion
  10. References

Prerequisites#

  • Basic knowledge of JavaScript/TypeScript.
  • Familiarity with Jest (installation, test syntax).
  • Understanding of GraphQL concepts (schemas, resolvers, queries/mutations).
  • Node.js (v14+) and npm/yarn installed.

Understanding Mocks and Errors in Jest#

What is a Mock in Jest?#

A "mock" in Jest is a function or module that replaces a real dependency to control its behavior during testing. Mocks let you:

  • Simulate success/failure scenarios without hitting real databases/APIs.
  • Verify if functions are called with the right arguments.
  • Isolate tests from external systems (e.g., third-party services).

Why Throw Errors in Mocks?#

GraphQL APIs must handle errors like:

  • Invalid user input (e.g., missing required fields).
  • Authentication failures (e.g., "Unauthorized").
  • Server/database errors (e.g., "Connection failed").

By making mocks throw errors, you validate that your application:

  • Properly propagates errors to the client.
  • Displays user-friendly error messages.
  • Handles edge cases (e.g., retries on network failures).

Setting Up Your Project for GraphQL Testing#

Project Setup#

Let’s initialize a sample project with Jest and GraphQL dependencies. We’ll use:

  • apollo-server (for server-side resolvers).
  • @apollo/client (for client-side testing).
  • jest and ts-jest (for testing TypeScript).
# Initialize project
mkdir jest-graphql-mock-errors && cd jest-graphql-mock-errors
npm init -y
 
# Install dependencies
npm install graphql apollo-server @apollo/client
npm install --save-dev jest @types/jest ts-jest typescript @types/node

Configure Jest for TypeScript by creating jest.config.js:

// jest.config.js
module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  clearMocks: true, // Reset mocks between tests
};

Example GraphQL API Structure#

We’ll use a simple "User" API with:

  • A getUser query (fetches a user by ID).
  • A createUser mutation (creates a user with validation).

Schema (schema.ts):

// schema.ts
import { gql } from 'apollo-server';
 
export const typeDefs = gql`
  type User {
    id: ID!
    name: String!
    email: String!
  }
 
  input CreateUserInput {
    name: String!
    email: String!
  }
 
  type Query {
    getUser(id: ID!): User
  }
 
  type Mutation {
    createUser(input: CreateUserInput!): User
  }
`;

Resolvers (resolvers.ts):

// resolvers.ts
import { UserInputError } from 'apollo-server-errors';
 
// Mock database service (we’ll mock this in tests)
export const userService = {
  getUser: async (id: string) => {
    // Real implementation would fetch from a database
    return { id, name: 'John Doe', email: '[email protected]' };
  },
  createUser: async (input: { name: string; email: string }) => {
    if (!input.email.includes('@')) {
      throw new UserInputError('Invalid email format');
    }
    return { id: '1', ...input };
  },
};
 
export const resolvers = {
  Query: {
    getUser: async (_: any, { id }: { id: string }) => {
      return userService.getUser(id);
    },
  },
  Mutation: {
    createUser: async (_: any, { input }: { input: { name: string; email: string } }) => {
      return userService.createUser(input);
    },
  },
};

Mocking GraphQL Resolvers/Client in Jest#

Mocking a GraphQL Resolver#

Resolvers often depend on services (e.g., userService). To test resolver errors, mock these services to throw errors.

Example: Mocking userService
Use jest.mock to replace the real userService with a mock:

// __tests__/resolvers.test.ts
import { resolvers } from '../resolvers';
import { userService } from '../resolvers';
 
// Mock the entire userService module
jest.mock('../resolvers', () => ({
  ...jest.requireActual('../resolvers'), // Keep other exports
  userService: {
    getUser: jest.fn(),
    createUser: jest.fn(),
  },
}));
 
// Now, userService.getUser is a Jest mock function

Mocking a GraphQL Client (Apollo Client)#

Client-side code (e.g., React components) uses useQuery/useMutation from @apollo/client. Mock these hooks to return errors.

Example: Mocking useQuery

// __tests__/UserComponent.test.tsx
import { render, screen } from '@testing-library/react';
import { useQuery } from '@apollo/client';
import UserComponent from '../UserComponent';
 
// Mock @apollo/client
jest.mock('@apollo/client', () => ({
  ...jest.requireActual('@apollo/client'), // Keep other exports
  useQuery: jest.fn(),
}));
 
// Mock useQuery to return an error
(useQuery as jest.Mock).mockReturnValue({
  loading: false,
  error: new Error('Failed to fetch user'),
  data: null,
});

Making Mocks Throw Errors: Step-by-Step#

Throwing Basic Errors#

Use mockImplementation to make a mock function throw a basic Error.

Example: Resolver Service Throwing Basic Error

// In resolvers.test.ts
test('getUser resolver throws error when userService fails', async () => {
  // Mock userService.getUser to throw a basic error
  (userService.getUser as jest.Mock).mockImplementation(() => {
    throw new Error('Database connection failed');
  });
 
  // Call the resolver
  const result = await resolvers.Query.getUser({}, { id: '1' });
 
  // The resolver should propagate the error
  await expect(result).rejects.toThrow('Database connection failed');
});

Throwing Specific Error Types (e.g., UserInputError)#

GraphQL uses specific error types (e.g., UserInputError, AuthenticationError) from apollo-server-errors. Mock services to throw these for realistic testing.

Example: Throwing UserInputError

import { UserInputError } from 'apollo-server-errors';
 
test('createUser resolver throws UserInputError for invalid email', async () => {
  // Mock createUser to throw UserInputError
  (userService.createUser as jest.Mock).mockImplementation(() => {
    throw new UserInputError('Invalid email: missing @', {
      invalidArgs: ['email'], // Include additional context
    });
  });
 
  const result = resolvers.Mutation.createUser({}, { input: { name: 'John', email: 'invalid-email' } });
 
  await expect(result).rejects.toThrow(UserInputError);
  await expect(result).rejects.toHaveProperty('message', 'Invalid email: missing @');
});

Throwing Network Errors#

To simulate network failures (e.g., API unreachable), mock HTTP requests with tools like nock (for Node.js) or msw (for browser).

Example: Mocking Network Error with nock

import nock from 'nock';
import { ApolloClient, InMemoryCache, gql } from '@apollo/client';
 
test('Apollo Client throws network error on 500 response', async () => {
  // Mock a network request to the GraphQL endpoint
  nock('http://localhost:4000') // Match your Apollo Server URL
    .post('/graphql') // GraphQL endpoint
    .reply(500, { errors: [{ message: 'Internal Server Error' }] });
 
  // Create Apollo Client instance
  const client = new ApolloClient({
    uri: 'http://localhost:4000/graphql',
    cache: new InMemoryCache(),
  });
 
  // Execute query and expect error
  await expect(
    client.query({ query: gql`query { getUser(id: "1") { name } }` })
  ).rejects.toThrow('Internal Server Error');
});

Conditional Error Throwing#

Mock functions can throw errors only for specific inputs (e.g., invalid IDs).

Example: Throw Error for Invalid ID

test('getUser throws error for invalid ID', async () => {
  (userService.getUser as jest.Mock).mockImplementation((id: string) => {
    if (id === 'invalid-id') {
      throw new Error('User not found');
    }
    return { id, name: 'John Doe' }; // Return data for valid IDs
  });
 
  // Test invalid ID
  await expect(resolvers.Query.getUser({}, { id: 'invalid-id' })).rejects.toThrow('User not found');
 
  // Test valid ID (should return data)
  const validResult = await resolvers.Query.getUser({}, { id: 'valid-id' });
  expect(validResult).toEqual({ id: 'valid-id', name: 'John Doe' });
});

Conditional Error Throwing in Client Hooks#

For useQuery, return an error only for specific queries:

// In UserComponent.test.tsx
test('UserComponent displays error when fetch fails', () => {
  // Mock useQuery to throw error for a specific query
  (useQuery as jest.Mock).mockImplementation((query) => {
    if (query.definitions[0].name.value === 'getUser') {
      return { loading: false, error: new Error('User not found'), data: null };
    }
    return { loading: false, data: { ... }, error: null };
  });
 
  render(<UserComponent userId="invalid-id" />);
  expect(screen.getByText('User not found')).toBeInTheDocument();
});

Testing Error Handling in Your Application#

Testing Resolver Error Responses#

Apollo Server wraps resolver errors into the GraphQL response’s errors array. Use executeOperation to test this.

Example: Testing Resolver Error Response

import { ApolloServer } from 'apollo-server';
import { typeDefs } from '../schema';
import { resolvers } from '../resolvers';
 
test('GraphQL response includes error when resolver fails', async () => {
  // Setup Apollo Server with mocks
  const server = new ApolloServer({ typeDefs, resolvers });
 
  // Mock userService.getUser to throw
  (userService.getUser as jest.Mock).mockImplementation(() => {
    throw new UserInputError('Invalid user ID');
  });
 
  // Execute a query
  const result = await server.executeOperation({
    query: gql`query GetUser($id: ID!) { getUser(id: $id) { name } }`,
    variables: { id: 'invalid-id' },
  });
 
  // Assert errors are present
  expect(result.errors).toBeDefined();
  expect(result.errors![0].message).toBe('Invalid user ID');
  expect(result.data).toBeNull(); // Data is null on error
});

Testing Client-Side Error Handling#

For React components, use React Testing Library to verify error UI is rendered.

Example: Testing Error Display in a Component

// UserComponent.tsx
import { useQuery, gql } from '@apollo/client';
 
const GET_USER = gql`query GetUser($id: ID!) { getUser(id: $id) { name } }`;
 
const UserComponent = ({ userId }: { userId: string }) => {
  const { loading, error, data } = useQuery(GET_USER, { variables: { id: userId } });
 
  if (loading) return <div>Loading...</div>;
  if (error) return <div className="error">Error: {error.message}</div>;
  return <div>User: {data?.getUser.name}</div>;
};
 
export default UserComponent;

Test:

// UserComponent.test.tsx
test('displays error message when useQuery fails', () => {
  // Mock useQuery to return error
  (useQuery as jest.Mock).mockReturnValue({
    loading: false,
    error: new Error('User not found'),
    data: null,
  });
 
  render(<UserComponent userId="1" />);
  
  // Verify error message is displayed
  expect(screen.getByText('Error: User not found')).toBeInTheDocument();
});

Best Practices for Mocking Errors in Jest#

  1. Use Specific Error Types
    Throw UserInputError, AuthenticationError, etc., instead of generic Error to match real-world scenarios.

  2. Avoid Over-Mocking
    Only mock dependencies needed for the test. Over-mocking leads to brittle tests.

  3. Clean Up Mocks
    Use jest.clearAllMocks() in beforeEach to reset mocks between tests:

    beforeEach(() => {
  jest.clearAllMocks(); // Prevents cross-test contamination
});

  4. Test Multiple Error Scenarios
    Cover validation errors, network errors, and edge cases (e.g., empty inputs).

  5. Document Mock Behavior
    Add comments explaining why a mock throws an error (e.g., "Simulate database outage").

Common Pitfalls and How to Avoid Them#

  1. Forgetting to Mock Dependencies
    If you don’t mock userService, tests will call the real service (e.g., hitting a database). Always mock external dependencies.

  2. Not Clearing Mocks
    Mocks retain state between tests. Use jest.clearAllMocks() or jest.resetModules() to avoid leaks.

  3. Throwing Errors in Client Hooks
    Apollo Client’s useQuery does not throw errors—it returns an error object. Mock useQuery to return { error }, not throw.

  4. Ignoring Error Context
    GraphQL errors include extensions (e.g., code: "UNAUTHENTICATED"). Test these for full validation:

    expect(result.errors![0].extensions.code).toBe('UNAUTHENTICATED');

Conclusion#

Mocking errors in Jest is critical for testing GraphQL API reliability. By following this guide, you can:

  • Mock resolvers, services, and client hooks to simulate errors.
  • Test server-side error propagation and client-side error UI.
  • Avoid common pitfalls like over-mocking or stale mocks.

With these techniques, you’ll ensure your GraphQL API handles errors gracefully—delivering a robust experience to users.

References#

2026-02