Тестирование 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.UserServicegrpcurl доступен на 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.
| Инструмент | Формат | Стриминг | Когда удобен |
|---|---|---|---|
| grpcurl | CLI | Да | Скрипты, CI, быстрые проверки |
| BloomRPC | GUI | Да | Визуальное исследование (проект не развивается) |
| Postman | GUI | Да | Команды, уже использующие Postman |
| Evans | REPL | Да | Интерактивное изучение схемы |
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 | Числовое значение | Когда встречается |
|---|---|---|
| OK | 0 | Успешный вызов |
| CANCELLED | 1 | Вызов отменён клиентом |
| INVALID_ARGUMENT | 3 | Некорректные параметры запроса |
| NOT_FOUND | 5 | Ресурс не найден |
| ALREADY_EXISTS | 6 | Попытка создать дубликат |
| PERMISSION_DENIED | 7 | Недостаточно прав |
| UNAUTHENTICATED | 16 | Не передан или невалиден токен |
| UNAVAILABLE | 14 | Сервис временно недоступен |
| DEADLINE_EXCEEDED | 4 | Истёк таймаут вызова |
При ручной проверке обращайте внимание не только на код, но и на 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, а не в теле ответа.
- Считать стрим завершённым, когда закончились данные. Стрим может завершиться с ошибкой после отправки нескольких сообщений. Финальный статус нужно проверять отдельно.
- Не проверять поведение при отмене вызова. Клиент может отменить запрос через контекст - сервис должен корректно освобождать ресурсы, а не зависать.
- Запускать тесты против продакшн-сервера. Из-за бинарного протокола ошибки сложнее поймать без специфических инструментов - лучше держать тестовое окружение.
Чеклист: что проверить перед выходом в продакшн
- Все методы сервиса описаны в .proto и доступны через reflection или явный файл
- Каждый метод проверен на happy path и основные негативные сценарии
- Статус-коды ошибок соответствуют семантике gRPC, а не продублированы из HTTP
- Поля-опциональные в proto3 обрабатываются корректно при отсутствии значения
- Добавление нового поля в схему не ломает старых клиентов
- Стриминговые методы проверены на завершение с ошибкой и на разрыв соединения
- Авторизация через метаданные проверена: без токена - UNAUTHENTICATED, с истёкшим - тоже
- Таймауты работают: при медленном сервисе клиент получает DEADLINE_EXCEEDED, а не висит вечно
- Автотесты используют сгенерированный клиент, а не сырые HTTP/2-запросы
- Проверка совместимости схемы включена в 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-сервис: можно переиспользовать сгенерированный код из основного репозитория.