TL;DR

  • Тестирование GraphQL: Валидация запросов, мутаций, подписок и схемы на едином endpoint
  • Ключевое отличие от REST: HTTP 200 не означает успех — всегда проверяй поле errors
  • Критичные тесты: Валидация схемы, авторизация на уровне полей, лимиты сложности, обнаружение N+1
  • Инструменты: Apollo MockedProvider, Jest, MSW, Insomnia, k6
  • State of JS 2024: GraphQL используют 44% опрошенных разработчиков; рост 8% год к году
  • Лучшая практика: Проверяй изменения схемы на breaking changes перед деплоем

Время чтения: 14 минут

GraphQL стал доминирующим гибким языком запросов к API, принципиально изменив подход клиентов к запросам данных с серверов. По данным опроса State of JavaScript 2024, 44% опрошенных разработчиков используют GraphQL в своих проектах — с ростом примерно на 8% в год с 2022 года. На GitHub эталонная реализация graphql-js превышает 19 000 звёзд, а Apollo Client в одиночку имеет более 19 000 звёзд и 10 миллионов еженедельных загрузок через npm. Тестирование GraphQL API требует принципиально других подходов, чем REST: GraphQL использует единый endpoint для всех операций, позволяет клиентам точно указывать нужные данные, и может вернуть HTTP 200 с ошибками в теле ответа. Это означает что традиционные допущения о тестировании API — “200 значит успех, 4xx значит ошибка” — неприменимы. Это руководство охватывает полный ландшафт тестирования GraphQL: от базовых тестов запросов до валидации схемы, побочных эффектов мутаций, подписок реального времени и тестирования производительности с анализом сложности запросов.

GraphQL стал популярной альтернативой REST API, предлагая гибкую выборку данных и строгую типизацию. Однако тестирование GraphQL API требует других подходов, чем традиционное REST тестирование. Это подробное руководство охватывает всё что нужно знать об эффективном тестировании GraphQL API.

Основы тестирования GraphQL

Тестирование GraphQL отличается от тестирования REST API в нескольких ключевых аспектах. В отличие от REST, где каждая конечная точка возвращает фиксированную структуру данных, GraphQL позволяет клиентам запрашивать именно те данные, которые им нужны, через единственную конечную точку. Эта гибкость создает уникальные задачи тестирования.

Ключевые отличия от тестирования REST

АспектТестирование RESTТестирование GraphQL
Конечные точкиМножество конечных точекЕдинственная конечная точка
Структура данныхФиксированная на конечную точкуДинамическая на запрос
Over-fetchingЧастая проблемаУстранена дизайном
Under-fetchingТребует множественных запросовРешается одним запросом
ВерсионированиеВерсии на основе URLЭволюция схемы
Обработка ошибокHTTP-коды статусаВозможен частичный успех

Природа единственной конечной точки GraphQL означает, что традиционное тестирование HTTP-кодов статуса менее релевантно. Запрос GraphQL может вернуть HTTP 200 даже с ошибками в данных ответа.

«GraphQL ломает допущение что HTTP 200 означает успех. Каждый тест GraphQL должен проверять поле errors в теле ответа — не только статус-код. Команды, которые пропускают это, получают тестовые suite дающие ложную уверенность: всё зелёное, но реальные ошибки остаются необнаруженными.» — Yuri Kan, Senior QA Lead

Стратегии тестирования запросов

Тестирование запросов формирует основу тестирования GraphQL. Запросы позволяют клиентам получать данные, и их тестирование обеспечивает корректную выборку данных и правильное разрешение полей.

Базовое тестирование запросов

Начните с простых тестов запросов, проверяющих базовую функциональность:

// Пример использования Jest и Apollo Client
import { ApolloClient, InMemoryCache, gql } from '@apollo/client';

describe('Тесты запросов пользователей', () => {
  let client;

  beforeAll(() => {
    client = new ApolloClient({
      uri: 'http://localhost:4000/graphql',
      cache: new InMemoryCache()
    });
  });

  test('должен получить пользователя по ID', async () => {
    const GET_USER = gql`
      query GetUser($id: ID!) {
        user(id: $id) {
          id
          name
          email
        }
      }
    `;

    const { data } = await client.query({
      query: GET_USER,
      variables: { id: '123' }
    });

    expect(data.user).toBeDefined();
    expect(data.user.id).toBe('123');
    expect(data.user.name).toBeTruthy();
    expect(data.user.email).toMatch(/^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$/);
  });
});

Тестирование вложенных запросов

Сила GraphQL заключается во вложенных запросах. Тестируйте глубокую вложенность запросов, чтобы убедиться, что резолверы работают корректно:

test('должен получить пользователя с вложенными постами и комментариями', async () => {
  const GET_USER_WITH_POSTS = gql`
    query GetUserWithPosts($id: ID!) {
      user(id: $id) {
        id
        name
        posts {
          id
          title
          comments {
            id
            content
            author {
              name
            }
          }
        }
      }
    }
  `;

  const { data } = await client.query({
    query: GET_USER_WITH_POSTS,
    variables: { id: '123' }
  });

  expect(data.user.posts).toBeInstanceOf(Array);
  expect(data.user.posts[0].comments).toBeInstanceOf(Array);
  expect(data.user.posts[0].comments[0].author.name).toBeDefined();
});

Тестирование производительности запросов

Тестируйте производительность запросов, особенно для сложных вложенных запросов, которые могут вызвать проблему N+1:

test('должен эффективно разрешать вложенные данные без N+1 запросов', async () => {
  const startTime = Date.now();

  const { data } = await client.query({
    query: GET_USER_WITH_POSTS,
    variables: { id: '123' }
  });

  const duration = Date.now() - startTime;

  // Должно завершиться менее чем за 500мс даже с вложенными данными
  expect(duration).toBeLessThan(500);
  expect(data.user.posts.length).toBeGreaterThan(0);
});

Тестирование мутаций

Мутации изменяют данные на стороне сервера. Тестирование мутаций требует проверки как немедленного ответа, так и побочных эффектов.

Тестирование мутаций создания 

test('должен создать нового пользователя', async () => {
  const CREATE_USER = gql`
    mutation CreateUser($input: UserInput!) {
      createUser(input: $input) {
        id
        name
        email
        createdAt
      }
    }
  `;

  const { data } = await client.mutate({
    mutation: CREATE_USER,
    variables: {
      input: {
        name: 'Иван Иванов',
        email: 'ivan@example.com',
        password: 'БезопасныйПароль123!'
      }
    }
  });

  expect(data.createUser.id).toBeDefined();
  expect(data.createUser.name).toBe('Иван Иванов');
  expect(data.createUser.email).toBe('ivan@example.com');
  expect(new Date(data.createUser.createdAt)).toBeInstanceOf(Date);
});

Тестирование мутаций обновления

Проверьте, что обновления работают корректно и возвращают обновленные данные:

test('должен обновить профиль пользователя', async () => {
  const UPDATE_USER = gql`
    mutation UpdateUser($id: ID!, $input: UserUpdateInput!) {
      updateUser(id: $id, input: $input) {
        id
        name
        bio
        updatedAt
      }
    }
  `;

  const { data } = await client.mutate({
    mutation: UPDATE_USER,
    variables: {
      id: '123',
      input: {
        name: 'Мария Иванова',
        bio: 'Обновленный текст биографии'
      }
    }
  });

  expect(data.updateUser.name).toBe('Мария Иванова');
  expect(data.updateUser.bio).toBe('Обновленный текст биографии');
});

Тестирование мутаций удаления

Тестируйте мутации удаления и проверяйте правильную очистку:

test('должен удалить пользователя и каскадно связанные данные', async () => {
  const DELETE_USER = gql`
    mutation DeleteUser($id: ID!) {
      deleteUser(id: $id) {
        success
        message
      }
    }
  `;

  const { data } = await client.mutate({
    mutation: DELETE_USER,
    variables: { id: '123' }
  });

  expect(data.deleteUser.success).toBe(true);

  // Проверить, что пользователь больше не существует
  const GET_USER = gql`
    query GetUser($id: ID!) {
      user(id: $id) {
        id
      }
    }
  `;

  await expect(
    client.query({ query: GET_USER, variables: { id: '123' } })
  ).rejects.toThrow();
});

Тестирование подписок

Подписки GraphQL обеспечивают обновления данных в реальном времени через WebSockets. Тестирование подписок требует других техник.

Тестирование WebSocket подписок 

import { WebSocketLink } from '@apollo/client/link/ws';
import { SubscriptionClient } from 'subscriptions-transport-ws';
import ws from 'ws';

test('должен получать обновления в реальном времени через подписку', (done) => {
  const wsClient = new SubscriptionClient(
    'ws://localhost:4000/graphql',
    { reconnect: true },
    ws
  );

  const NEW_MESSAGE_SUBSCRIPTION = gql`
    subscription OnNewMessage($channelId: ID!) {
      messageAdded(channelId: $channelId) {
        id
        content
        author {
          name
        }
        createdAt
      }
    }
  `;

  const observable = wsClient.request({
    query: NEW_MESSAGE_SUBSCRIPTION,
    variables: { channelId: 'channel-1' }
  });

  const subscription = observable.subscribe({
    next: (result) => {
      expect(result.data.messageAdded).toBeDefined();
      expect(result.data.messageAdded.content).toBeTruthy();
      subscription.unsubscribe();
      wsClient.close();
      done();
    },
    error: (error) => {
      done(error);
    }
  });

  // Вызвать мутацию для генерации события подписки
  setTimeout(() => {
    client.mutate({
      mutation: gql`
        mutation {
          sendMessage(channelId: "channel-1", content: "Тестовое сообщение") {
            id
          }
        }
      `
    });
  }, 100);
}, 10000);

Тестирование валидации схемы

Валидация схемы обеспечивает, что ваш GraphQL API поддерживает консистентные определения типов и следует лучшим практикам.

Линтинг схемы

Используйте GraphQL Inspector или аналогичные инструменты для валидации изменений схемы:

import { buildSchema } from 'graphql';
import { findBreakingChanges, findDangerousChanges } from 'graphql';

test('не должен вводить ломающие изменения схемы', () => {
  const oldSchema = buildSchema(oldSchemaSDL);
  const newSchema = buildSchema(newSchemaSDL);

  const breakingChanges = findBreakingChanges(oldSchema, newSchema);
  const dangerousChanges = findDangerousChanges(oldSchema, newSchema);

  expect(breakingChanges).toHaveLength(0);

  // Логировать опасные изменения для ревью
  if (dangerousChanges.length > 0) {
    console.warn('Обнаружены опасные изменения схемы:', dangerousChanges);
  }
});

Тестирование покрытия типов

Убедитесь, что все типы имеют правильные описания и обязательные поля:

test('должен иметь описания для всех типов и полей', () => {
  const schema = buildSchema(schemaSDL);
  const typeMap = schema.getTypeMap();

  Object.keys(typeMap).forEach(typeName => {
    // Пропустить встроенные типы
    if (typeName.startsWith('__')) return;

    const type = typeMap[typeName];

    if (type.description === undefined) {
      throw new Error(`Тип ${typeName} без описания`);
    }

    // Проверить описания полей для объектных типов
    if ('getFields' in type) {
      const fields = type.getFields();
      Object.keys(fields).forEach(fieldName => {
        if (!fields[fieldName].description) {
          throw new Error(`Поле ${typeName}.${fieldName} без описания`);
        }
      });
    }
  });
});

Мокирование ответов GraphQL

Мокирование необходимо для тестирования клиентских приложений без зависимости от работающего сервера.

Мокирование с Apollo Client 

import { MockedProvider } from '@apollo/client/testing';

const mocks = [
  {
    request: {
      query: GET_USER,
      variables: { id: '123' }
    },
    result: {
      data: {
        user: {
          id: '123',
          name: 'Иван Иванов',
          email: 'ivan@example.com'
        }
      }
    }
  }
];

test('должен отрендерить данные пользователя из замоканного запроса', async () => {
  const { getByText } = render(
    <MockedProvider mocks={mocks} addTypename={false}>
      <UserProfile userId="123" />
    </MockedProvider>
  );

  // Дождаться загрузки данных
  await waitFor(() => {
    expect(getByText('Иван Иванов')).toBeInTheDocument();
  });
});

Mock Service Worker (MSW) для GraphQL 

import { graphql } from 'msw';
import { setupServer } from 'msw/node';

const server = setupServer(
  graphql.query('GetUser', (req, res, ctx) => {
    const { id } = req.variables;

    return res(
      ctx.data({
        user: {
          id,
          name: 'Замоканный Пользователь',
          email: 'mock@example.com'
        }
      })
    );
  }),

  graphql.mutation('CreateUser', (req, res, ctx) => {
    const { input } = req.variables;

    return res(
      ctx.data({
        createUser: {
          id: 'новый-id',
          ...input,
          createdAt: new Date().toISOString()
        }
      })
    );
  })
);

beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

Тестирование обработки ошибок

GraphQL имеет уникальные характеристики обработки ошибок. Ошибки могут возникать на множестве уровней.

Тестирование ошибок на уровне полей 

test('должен корректно обрабатывать ошибки на уровне полей', async () => {
  const { data, errors } = await client.query({
    query: gql`
      query {
        user(id: "123") {
          id
          name
          restrictedField
        }
      }
    `
  });

  expect(errors).toBeDefined();
  expect(errors[0].path).toContain('restrictedField');
  expect(data.user.id).toBe('123');
  expect(data.user.name).toBeDefined();
  expect(data.user.restrictedField).toBeNull();
});

Тестирование сетевых ошибок 

test('должен обрабатывать сетевые ошибки', async () => {
  const errorLink = onError(({ networkError, graphQLErrors }) => {
    if (networkError) {
      console.log(`[Сетевая ошибка]: ${networkError}`);
    }
  });

  const clientWithErrorHandling = new ApolloClient({
    link: from([errorLink, httpLink]),
    cache: new InMemoryCache()
  });

  await expect(
    clientWithErrorHandling.query({
      query: GET_USER,
      variables: { id: 'invalid' }
    })
  ).rejects.toThrow();
});

Интеграционное тестирование с базами данных

Тестируйте резолверы GraphQL с реальными операциями базы данных:

import { MongoMemoryServer } from 'mongodb-memory-server';

describe('Интеграция GraphQL с базой данных', () => {
  let mongoServer;
  let db;

  beforeAll(async () => {
    mongoServer = await MongoMemoryServer.create();
    const uri = mongoServer.getUri();
    // Подключиться к MongoDB в памяти
  });

  afterAll(async () => {
    await mongoServer.stop();
  });

  test('должен сохранить данные пользователя', async () => {
    const { data } = await client.mutate({
      mutation: CREATE_USER,
      variables: { input: { name: 'Тестовый Пользователь', email: 'test@example.com' } }
    });

    // Проверить в базе данных
    const dbUser = await db.collection('users').findOne({ _id: data.createUser.id });
    expect(dbUser.name).toBe('Тестовый Пользователь');
  });
});

Лучшие практики и рекомендации

Чеклист тестирования

  • ✅ Тестировать все вариации запросов с разными комбинациями аргументов
  • ✅ Проверять побочные эффекты мутаций и сохранение данных
  • ✅ Тестировать поведение подписок в реальном времени и очистку
  • ✅ Валидировать изменения схемы на ломающие модификации
  • ✅ Консистентно мокировать внешние зависимости
  • ✅ Тестировать сценарии ошибок на уровне полей и запросов
  • ✅ Проверять правила авторизации и аутентификации
  • ✅ Тестировать пагинацию и паттерны соединений
  • ✅ Валидировать санитизацию и валидацию входных данных
  • ✅ Мониторить производительность и сложность запросов

Советы по тестированию производительности

Используйте анализ сложности запросов для предотвращения дорогих запросов:

import { createComplexityLimitRule } from 'graphql-validation-complexity';

const schema = makeExecutableSchema({
  typeDefs,
  resolvers
});

const complexityLimit = createComplexityLimitRule(1000);

test('должен отклонять чрезмерно сложные запросы', () => {
  const complexQuery = gql`...`; // Очень глубоко вложенный запрос

  const errors = validate(schema, parse(complexQuery), [complexityLimit]);

  expect(errors.length).toBeGreaterThan(0);
  expect(errors[0].message).toContain('превышает максимальную сложность');
});

Заключение

Тестирование GraphQL требует понимания уникальных характеристик протокола — единственные конечные точки, гибкие запросы, подписки в реальном времени и частичные ошибки. Реализуя комплексные стратегии тестирования для запросов, мутаций, подписок, валидации схемы и обработки ошибок, вы можете обеспечить надежность и производительность вашего GraphQL API.

Сосредоточьтесь на тестировании бизнес-логики в резолверах, валидации эволюции схемы и обеспечении правильной обработки ошибок на всех уровнях. Широко используйте мокирование для клиентских тестов и интеграционное тестирование для критических потоков данных. С этими практиками ваш GraphQL API будет надежным и поддерживаемым.

Смотрите также

FAQ

Что такое тестирование GraphQL?

Тестирование GraphQL — это процесс проверки корректной обработки GraphQL API запросов, мутаций и подписок. Отличается от REST тестирования тем, что GraphQL использует единый endpoint, возвращает динамические структуры данных на основе запроса клиента, и может вернуть HTTP 200 даже при наличии ошибок — требуя проверки поля errors в теле ответа для полного обнаружения ошибок.

Как тестирование GraphQL отличается от тестирования REST API?

REST тестирование проверяет фиксированные endpoints используя HTTP статус-коды как основной сигнал успеха/неудачи. GraphQL тестирование проверяет единый endpoint где форма ответа определяется запросом. Вложенная структура запросов GraphQL создаёт N+1 проблемы производительности, и валидация схемы является специфическим GraphQL требованием.

Какие инструменты используются для тестирования GraphQL?

Популярные инструменты: Apollo Client с MockedProvider для тестирования React компонентов, Jest с graphql-tag для unit тестов резолверов, Insomnia или GraphQL Playground для ручного исследования, MSW (Mock Service Worker) для интеграционных тестов, k6 с пользовательскими GraphQL запросами для нагрузочного тестирования. GraphQL Inspector проверяет изменения схемы на breaking modifications.

Что нужно тестировать в GraphQL API?

Тестируй все вариации запросов, побочные эффекты мутаций и сохранность данных, поведение подписок в реальном времени, изменения схемы на breaking modifications, правила авторизации (разрешения на уровне полей), обработку ошибок на уровне полей и запросов, валидацию входных данных, и лимиты сложности запросов для предотвращения дорогостоящих запросов.

Источники и дополнительное чтение