qa

Тестирование gRPC-сервисов: как проверять protobuf-контракты, стриминг и ошибки вручную и в автотестах

читать
11–14 мин
опубликована
разделов
11

Коротко:

  • gRPC использует бинарный протокол и строгую схему - это меняет подход к тестированию по сравнению с REST.
  • Для ручных проверок подходят grpcurl, Postman, Evans и Kreya.
  • Protobuf-контракт нужно проверять отдельно: совместимость схем, обязательные поля и поведение при добавлении новых полей.
  • Стриминг проверяют иначе, чем обычные unary-вызовы: важны порядок сообщений, поведение при обрыве и таймауты.
  • Статус-коды gRPC не совпадают с HTTP - их нужно знать и проверять целенаправленно.
  • Автотесты строят на основе сгенерированных клиентов из .proto-файлов, а не сырых HTTP-запросов.

Чем gRPC отличается от REST с точки зрения тестировщика

REST-сервис можно открыть в браузере, отправить curl-запрос и сразу прочитать JSON-ответ. С gRPC так не выйдет: протокол работает поверх HTTP/2, данные сериализуются в бинарный формат protobuf, а для вызова нужен специальный клиент, который умеет читать .proto-схему.

Это означает другой набор инструментов и другие точки проверки. Тестировщик работает не с произвольными полями JSON, а со строго типизированными сообщениями, где каждое поле имеет номер, тип и правила совместимости. Изменить сигнатуру метода или переименовать поле - уже потенциальный breaking change.

Ещё одна особенность - четыре типа вызовов. Unary (один запрос, один ответ) похож на обычный API-вызов. Но server streaming, client streaming и bidirectional streaming - это совсем другие сценарии, у каждого из которых свои классы ошибок.

Инструменты для ручной работы

Прежде чем писать автотесты, полезно поработать с сервисом вручную: понять, что вообще возвращается, как выглядят ошибки и где схема расходится с ожиданиями.

grpcurl

Утилита командной строки, аналог curl для gRPC. Позволяет вызывать методы, смотреть список доступных сервисов и читать схему - при условии, что сервер включил server reflection или вы передаёте .proto-файл явно.

Пример вызова unary-метода с явным указанием схемы:

grpcurl -plaintext -proto user.proto -d '{"user_id": 42}' localhost:50051 user.UserService/GetUser

Если сервер поддерживает reflection, флаг -proto не нужен. Флаг -plaintext отключает TLS - полезно в локальной среде. Для production-сервисов с TLS его убирают и при необходимости добавляют сертификат через -cacert.

Чтобы посмотреть список методов сервиса:

grpcurl -plaintext localhost:50051 describe user.UserService

grpcurl доступен на GitHub: github.com/fullstorydev/grpcurl.

BloomRPC

Графический клиент с интерфейсом, напоминающим Postman. Загружаете .proto-файл, выбираете сервис и метод, заполняете JSON-тело запроса и нажимаете «Play». BloomRPC показывает ответ, время выполнения и статус-код.

Для стриминговых методов клиент умеет отправлять несколько сообщений подряд и отображать поток ответов в реальном времени. Это удобно на этапе первичного изучения поведения сервиса.

Важное ограничение: проект BloomRPC больше не развивается. Для команд, которым нужен актуально поддерживаемый инструмент, есть альтернатива - Kreya или плагин gRPC в Postman.

Postman

Начиная с версии 9.7, Postman поддерживает gRPC-вызовы. Импортируете .proto-файл или подключаетесь к серверу с включённым reflection, и работаете через привычный интерфейс. Удобно, если команда уже использует Postman для REST и GraphQL и не хочет держать ещё один инструмент.

Evans

Интерактивный REPL-клиент для gRPC - можно в реальном времени вводить поля, вызывать методы и видеть ответы без написания JSON вручную. Хорошо подходит для первичного исследования незнакомого сервиса. Репозиторий: github.com/ktr0731/evans.

ИнструментФорматСтримингКогда удобен
grpcurlCLIДаСкрипты, CI, быстрые проверки
BloomRPCGUIДаВизуальное исследование (проект не развивается)
PostmanGUIДаКоманды, уже использующие Postman
EvansREPLДаИнтерактивное изучение схемы

Protobuf-контракт: что проверять и почему это отдельная задача

В REST-мире контракт часто живёт в OpenAPI-спецификации, которую могут забыть обновить. В gRPC контракт - это сам .proto-файл: из него генерируются клиент и сервер. Это делает схему источником истины, но не защищает автоматически от проблем совместимости.

Совместимость при изменениях схемы

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

  • Удаление поля или изменение его номера
  • Изменение типа поля (например, int32 на string)
  • Переименование метода в service-блоке
  • Изменение типа вызова (unary на streaming)

Для автоматической проверки совместимости используют buf - инструмент с командой buf breaking, которая сравнивает текущую схему с предыдущей версией и сообщает о breaking changes. Документация: buf.build/docs/breaking.

Что проверять в .proto-схеме вручную

  • Поля с пометкой optional или repeated - сервис должен корректно работать, если они отсутствуют в запросе
  • Enum-значения: что происходит, если клиент отправляет неизвестное значение
  • Вложенные сообщения: корректна ли валидация при отсутствии вложенного объекта
  • Соответствие между схемой и реальным поведением сервиса - иногда они расходятся

Внимание: Protobuf не поддерживает обязательные поля начиная с proto3. Все поля технически опциональны, и сервер получит нулевое значение для отсутствующего поля. Это значит, что валидация обязательности должна быть в бизнес-логике сервиса - и именно её нужно тестировать.

Статус-коды gRPC: не путать с HTTP

Одна из частых ошибок при первом знакомстве с протоколом - смешивать коды gRPC и HTTP. Транспортный уровень возвращает HTTP/2-статус, но логика приложения использует собственные коды из пространства google.rpc.Code.

Код gRPCЧисловое значениеКогда встречается
OK0Успешный вызов
CANCELLED1Вызов отменён клиентом
INVALID_ARGUMENT3Некорректные параметры запроса
NOT_FOUND5Ресурс не найден
ALREADY_EXISTS6Попытка создать дубликат
PERMISSION_DENIED7Недостаточно прав
UNAUTHENTICATED16Не передан или невалиден токен
UNAVAILABLE14Сервис временно недоступен
DEADLINE_EXCEEDED4Истёк таймаут вызова

При ручной проверке обращайте внимание не только на код, но и на message в ответе - там должно быть понятное описание ошибки. Хороший сервис возвращает INVALID_ARGUMENT с текстом «field user_id must be positive», а не просто код без пояснений.

Полная спецификация кодов: grpc.github.io/grpc/core/md_doc_statuscodes.html.

Как проверять unary-вызовы

Unary - это самый простой тип: один запрос, один ответ. Его проверяют так же, как обычный API-эндпоинт, только с учётом специфики протокола.

Чеклист для unary-метода:

  • Happy path: корректные данные возвращают ожидаемый ответ с кодом OK
  • Отсутствующие поля: сервис корректно обрабатывает пустые значения, возвращает INVALID_ARGUMENT или дефолтное поведение
  • Граничные значения: нулевые ID, очень длинные строки, отрицательные числа
  • Аутентификация: вызов без метаданных авторизации возвращает UNAUTHENTICATED, а не 500
  • Несуществующий ресурс: NOT_FOUND, а не паника сервера
  • Таймаут: при медленном сервисе клиент получает DEADLINE_EXCEEDED

Тестирование стриминга: где прячутся реальные баги

Стриминговые методы - это главная область, где gRPC сильно отличается от привычных API. Здесь важен не только конкретный ответ, но и поведение всего потока.

Server streaming

Клиент отправляет один запрос, сервер отвечает потоком сообщений. Пример: получение списка событий, экспорт данных, live-лента.

Что проверять:

  • Порядок сообщений - если важна сортировка, она должна соблюдаться
  • Поведение при пустом результате: сервер закрывает стрим с OK или возвращает ошибку?
  • Что происходит при разрыве соединения на середине потока
  • Таймаут: если сервер долго не отправляет следующее сообщение, срабатывает ли дедлайн клиента
  • Большой поток: нет ли утечки памяти при обработке тысяч сообщений

Client streaming

Клиент отправляет поток сообщений, сервер отвечает один раз. Пример: загрузка файла по частям, батчевая запись событий.

Особые точки проверки:

  • Сервер принимает частичные данные - что происходит, если клиент обрывает стрим, не завершив передачу
  • Порядок обработки: сервер агрегирует все сообщения до ответа или отвечает после каждого
  • Дублирующиеся сообщения в потоке

Bidirectional streaming

Оба участника одновременно отправляют и получают сообщения. Самый сложный тип с точки зрения тестирования.

Пример сценария: Чат-сервис. Клиент А отправил сообщение - клиент Б получил его через bidirectional stream. Проверяем: что происходит, когда клиент Б отключается в момент отправки? Получает ли клиент А ошибку? Через какое время? Какой код?

При проверке bidirectional streaming особенно важны гонки (race conditions): оба участника могут отправлять одновременно. Руками воспроизвести это сложно - это первый кандидат на автоматизацию.

Метаданные и заголовки

В gRPC метаданные - это аналог HTTP-заголовков. Через них передают токены авторизации, трейс-идентификаторы, локаль и другие параметры.

При проверке метаданных обращают внимание на:

  • Авторизационные заголовки: сервис читает authorization из метаданных, а не из тела запроса
  • Trailing metadata: некоторые сервисы возвращают дополнительные метаданные после завершения вызова - их тоже нужно проверять
  • Чувствительность к регистру ключей: в gRPC ключи метаданных приводятся к нижнему регистру

В grpcurl метаданные передаются через флаг -H:

grpcurl -plaintext -H 'authorization: Bearer mytoken' -d '{"user_id": 1}' localhost:50051 user.UserService/GetUser

Автотесты: структура и подходы

Для написания автоматических проверок используют клиентский код, сгенерированный из .proto-файла. Это надёжнее, чем собирать HTTP/2-запросы вручную: компилятор сразу проверит типы, и многие ошибки контракта всплывут ещё на этапе сборки.

Генерация клиента

Для Python используют grpcio-tools:

python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. user.proto

Это создаёт два файла: user_pb2.py (классы сообщений) и user_pb2_grpc.py (стаб клиента). Для Go, Java, TypeScript процесс аналогичный - protoc с соответствующим плагином.

Пример теста на Python с pytest

import grpc
import pytest
import user_pb2
import user_pb2_grpc

@pytest.fixture
def stub():
    channel = grpc.insecure_channel('localhost:50051')
    return user_pb2_grpc.UserServiceStub(channel)

def test_get_user_not_found(stub):
    with pytest.raises(grpc.RpcError) as exc_info:
        stub.GetUser(user_pb2.GetUserRequest(user_id=99999))
    assert exc_info.value.code() == grpc.StatusCode.NOT_FOUND

def test_get_user_invalid_id(stub):
    with pytest.raises(grpc.RpcError) as exc_info:
        stub.GetUser(user_pb2.GetUserRequest(user_id=0))
    assert exc_info.value.code() == grpc.StatusCode.INVALID_ARGUMENT

Обратите внимание: ошибки gRPC выбрасываются как исключения типа grpc.RpcError, а не возвращаются как объект ответа. Забыть об этом и не обернуть вызов в try/except - частая ошибка в первых тестах.

Тест стриминга в автотесте

def test_server_stream_order(stub):
    responses = list(stub.ListEvents(
        event_pb2.ListEventsRequest(user_id=1)
    ))
    timestamps = [r.created_at for r in responses]
    assert timestamps == sorted(timestamps)

Для bidirectional streaming тест обычно пишут через итератор входящих сообщений и генератор исходящих. Проверяют не только содержимое, но и количество полученных ответов и финальный статус стрима.

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

Когда сервис ещё не готов или нужно воспроизвести специфичный сценарий ошибки, поднимают мок-сервер. В Python удобен pytest-grpc или написание собственного servicer - класса, реализующего интерфейс из сгенерированного кода.

Для Go есть go-grpc-middleware с тестовыми утилитами, а библиотека google.golang.org/grpc/test/bufconn позволяет поднять сервер прямо в памяти без реального сетевого порта.

Типичные ошибки при проверке gRPC-сервисов

  • Проверять только код OK и игнорировать остальные статусы. Сервис может возвращать INTERNAL там, где должен быть INVALID_ARGUMENT - это баг обработки ошибок, который не виден в happy path.
  • Не тестировать поведение при устаревшей схеме. Если клиент использует старую версию .proto, а сервер уже обновлён, неизвестные поля должны игнорироваться. Это нужно проверять явно.
  • Пропускать проверку trailing metadata. Некоторые сервисы возвращают важную информацию (например, pagination token) именно в trailing metadata, а не в теле ответа.
  • Считать стрим завершённым, когда закончились данные. Стрим может завершиться с ошибкой после отправки нескольких сообщений. Финальный статус нужно проверять отдельно.
  • Не проверять поведение при отмене вызова. Клиент может отменить запрос через контекст - сервис должен корректно освобождать ресурсы, а не зависать.
  • Запускать тесты против продакшн-сервера. Из-за бинарного протокола ошибки сложнее поймать без специфических инструментов - лучше держать тестовое окружение.

Чеклист: что проверить перед выходом в продакшн

  1. Все методы сервиса описаны в .proto и доступны через reflection или явный файл
  2. Каждый метод проверен на happy path и основные негативные сценарии
  3. Статус-коды ошибок соответствуют семантике gRPC, а не продублированы из HTTP
  4. Поля-опциональные в proto3 обрабатываются корректно при отсутствии значения
  5. Добавление нового поля в схему не ломает старых клиентов
  6. Стриминговые методы проверены на завершение с ошибкой и на разрыв соединения
  7. Авторизация через метаданные проверена: без токена - UNAUTHENTICATED, с истёкшим - тоже
  8. Таймауты работают: при медленном сервисе клиент получает DEADLINE_EXCEEDED, а не висит вечно
  9. Автотесты используют сгенерированный клиент, а не сырые HTTP/2-запросы
  10. Проверка совместимости схемы включена в CI через buf или аналог

Итог

Тестирование gRPC-сервисов требует понимания трёх вещей: как работает протокол, как читать и проверять protobuf-схему, и чем отличаются типы вызовов. Большинство инструментов хорошо знакомы QA-инженерам по работе с REST - grpcurl и Postman закрывают ручные проверки так же, как curl и Postman для HTTP.

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

Если в проекте ещё нет проверки совместимости схемы в CI - добавьте buf breaking как первый шаг. Это дешевле, чем разбирать инцидент из-за переименованного поля в production.

часто задаваемые вопросы

Передайте .proto-файл явно через флаг -proto path/to/service.proto . Если схема зависит от других файлов, укажите директорию поиска через -import-path . Reflection удобен в разработке, но в production его часто отключают по соображениям безопасности - и это нормально.

BloomRPC создавался специально для gRPC и имеет более простой интерфейс для этой задачи. Postman - универсальный инструмент, который поддерживает REST, GraphQL и gRPC в одном месте. Если команда уже работает в Postman, проще добавить gRPC туда. BloomRPC больше не развивается, для новых проектов лучше выбрать Postman или Kreya.

Если reflection включён, grpcurl и Evans могут получить схему напрямую с сервера командой grpcurl -plaintext localhost:50051 list . Если reflection отключён и файл не отдают - это проблема документирования сервиса, которую стоит поднять на уровне команды.

В автотесте создайте контекст с отменой ( context.WithCancel в Go или context с таймаутом в Python), вызовите метод и отмените контекст до получения ответа. Проверьте, что сервис не оставляет открытых транзакций, горутин или соединений с базой.

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

Установите buf и добавьте шаг buf breaking --against '.git#branch=main' в ваш пайплайн. При любом breaking change в .proto сборка упадёт до мержа. Это ловит проблемы совместимости раньше, чем они дойдут до клиентов.

Обычно выбирают тот, на котором написан сам сервис или уже есть тестовая инфраструктура команды. Python с pytest и grpcio-tools - хороший вариант для быстрого старта. Go удобен, если тестируете Go-сервис: можно переиспользовать сгенерированный код из основного репозитория.

ещё полезные статьи