gRPC API Testing Basics: Protobuf, Status Codes and Streaming

Inside large companies, most API calls never touch a browser: the order service talks to pricing, pricing talks to inventory, inventory talks to the warehouse, millions of times a minute. Many of these internal calls use gRPC because it’s fast and strongly typed. If you test microservices, you’ll meet it sooner or later. This lesson explains gRPC from a tester’s angle and walks through real calls to a public gRPC test server, including streaming and deadlines.

Why gRPC Exists (REST vs gRPC)

The .proto Contract

We’ll test the public grpcb.in test server (plaintext on grpcb.in:9000, TLS on grpcb.in:9001). Its hello service is defined like this:

syntax = "proto3";
package hello;

service HelloService {
  rpc SayHello (HelloRequest) returns (HelloResponse);                // unary
  rpc LotsOfReplies (HelloRequest) returns (stream HelloResponse);    // server streaming
}

message HelloRequest  { string greeting = 1; }
message HelloResponse { string reply = 1; }

Key points for testers:

• Each field has a number (= 1). The number, not the name, is what goes on the wire. Changing or reusing numbers breaks clients.
• In proto3, missing fields get default values (empty string, 0, false). An API can’t tell “not sent” from “sent empty” unless it uses wrappers or optional. Test how the service treats defaults.
• Code generators create typed clients in Java, Go, Python, TypeScript and more from this file.

The Four Types of gRPC Calls

gRPC Status Codes (Know These for Interviews)

Just like 4xx vs 5xx in REST, invalid client input should give INVALID_ARGUMENT, never INTERNAL or UNKNOWN.

Calling gRPC Manually

Postman

1. New → gRPC. Server URL: grpcb.in:9000 (TLS off).
2. Choose Using server reflection (grpcb.in supports it) or import the .proto file.
3. Select hello.HelloService / SayHello, message {"greeting": "Asha"}, click Invoke.
4. Response: {"reply": "hello Asha"} with status 0 OK.

grpcurl (command line)

# List services via server reflection
grpcurl -plaintext grpcb.in:9000 list

# Describe a service
grpcurl -plaintext grpcb.in:9000 describe hello.HelloService

# Unary call
grpcurl -plaintext -d '{"greeting": "Asha"}' grpcb.in:9000 hello.HelloService/SayHello

# Metadata (gRPC's headers), e.g. auth
grpcurl -plaintext -H "authorization: Bearer <token>" -d '{}' my-service:50051 orders.OrderService/ListOrders

Automating gRPC Tests with Playwright + grpc-js

Playwright’s runner, fixtures and reports work for any async test, so you can drive gRPC with the official Node client. Install it in your project:

npm install -D @grpc/grpc-js @grpc/proto-loader

Save the .proto above as hello.proto in the project root, then:

import { test, expect } from '@playwright/test';
import * as grpc from '@grpc/grpc-js';
import * as loader from '@grpc/proto-loader';

const pkg: any = grpc.loadPackageDefinition(loader.loadSync('hello.proto'));
const client = new pkg.hello.HelloService('grpcb.in:9000', grpc.credentials.createInsecure());
const deadline = (ms: number) => new Date(Date.now() + ms);

function sayHello(greeting: string, ms = 8_000): Promise<{ reply: string }> {
  return new Promise((resolve, reject) =>
    client.SayHello({ greeting }, { deadline: deadline(ms) }, (err: grpc.ServiceError | null, res: any) =>
      err ? reject(err) : resolve(res)));
}

test('unary call returns the expected reply', async () => {
  expect(await sayHello('Asha')).toEqual({ reply: 'hello Asha' });
});

test('server streaming returns several messages', async () => {
  const replies: string[] = await new Promise((resolve, reject) => {
    const got: string[] = [];
    const stream = client.LotsOfReplies({ greeting: 'Asha' }, { deadline: deadline(8_000) });
    stream.on('data', (m: any) => got.push(m.reply));
    stream.on('error', reject);
    stream.on('end', () => resolve(got));
  });
  expect(replies.length).toBeGreaterThan(1);
  for (const r of replies) expect(r).toBe('hello Asha');
});

test('a too-short deadline fails with DEADLINE_EXCEEDED', async () => {
  const err = await sayHello('Asha', 1).catch((e: grpc.ServiceError) => e);
  expect((err as grpc.ServiceError).code).toBe(grpc.status.DEADLINE_EXCEEDED);   // 4
});

When written, this returned hello Asha for the unary call, 10 messages from the stream, and status code 4 for the 1 ms deadline. Public test servers can be slow or offline, so for your own services run tests against a test environment you control.

gRPC Test Checklist

Breaking vs Safe .proto Changes

Tools like buf breaking check these rules automatically in CI, the gRPC equivalent of OpenAPI diff tools from the OpenAPI lesson.

Tools for gRPC Testing

• Postman: gRPC requests with reflection or .proto import, streaming support.
• grpcurl: cURL-like command-line client.
• Kreya, Insomnia: GUI clients.
• Code: grpc-js (TypeScript), grpcio (Python), grpc-java; run them in Playwright, pytest or JUnit.
• ghz, k6: load testing.
• buf: linting and breaking-change detection.

Interview Questions: gRPC Testing