How do I mock a gRPC service in tests?

Record your service once while it calls the real dependency with Keploy. It captures the HTTP/2 exchange — serialised request, response, status code, and trailers — then replays it during tests, so no stub service implementation is needed.

Is Keploy an alternative to an in-process gRPC stub server?

For integration tests, yes. A stub server returns whatever your hand-written implementation says, and drifts as the upstream proto changes. Keploy replays the real response bytes, so re-recording surfaces contract changes as diffs.

Can Keploy test gRPC error statuses and retries?

Yes. Status codes and trailing metadata are recorded with each call, so a DEADLINE_EXCEEDED or RESOURCE_EXHAUSTED response your dependency actually returned replays on test runs — exercising retry and fallback logic that stubs usually skip.

Does Keploy support gRPC streaming?

Server-streaming and client-streaming calls record as ordered frame sequences and replay in that order. Bidirectional streaming with interleaved frames is partially supported today — check the repository for the current state before relying on it.

Does Keploy work with grpc-java, grpc-go, and grpc-js?

Yes, and identically. Capture happens at the HTTP/2 frames beneath the generated client, so grpc-java, grpc-go, @grpc/grpc-js, and grpcio all record and replay the same exchanges regardless of the language or codegen version.

Do I need to regenerate my protos for Keploy?

No. Keploy records the serialised bytes on the wire rather than decoding them through your generated types, so nothing in your proto pipeline, buf configuration, or codegen step changes to record or replay a call.

Keploy as a gRPC testing framework

Keploy tests gRPC services by recording the HTTP/2 frames between client and server, capturing the serialised Protobuf messages and status codes exchanged, then replaying them during tests. There is no stub server to run and no mock service implementation to generate and maintain.

Generate gRPC tests free

keploy record -c "./orders-service"

18.4K+

1.2M+300M+mocks createdSlack

What Keploy gives a gRPC team

Captured as HTTP/2 frames

Keploy reads the framed gRPC exchange beneath your generated client, recording the method path, request metadata, serialised messages, status code, and trailing metadata together.

Below grpc-java, grpc-go, grpc-js, grpcio
Serialised Protobuf captured verbatim
Status codes and trailers preserved
Streaming replays as an ordered sequence

Try Keploy for free Explore the docs

The problem

Why gRPC integration tests slow teams down

The friction is rarely the assertions. It is everything around them — spinning up dependencies, keeping mocks honest, and repairing tests after every refactor.

Book a call Explore the docs

Three ways to do it

Testing gRPC: by hand, with In-process stub server, or with Keploy

A stub server returns whatever your hand-written implementation says, and drifts the moment the upstream proto changes. Keploy replays the real response bytes, so re-recording surfaces the change.

By hand

In-process stub server

With Keploy

Select any row for the full comparison, with code.

Get started Book a call

Same coverage, three costs

What you write for gRPC vs what Keploy records

All three produce the same assertion. Only the third still passes after the next refactor without anyone editing it.

By hand2–4 hours

fake_payments_service.go

hand-written

// Hand-written stub implementing another team's generated interface.

package testsupport

import (

"context"

pb "github.com/acme/payments/gen/paymentspb"

)

type FakePaymentsServer struct {

pb.UnimplementedPaymentsServer

}

func (FakePaymentsServer) Authorize(

ctx context.Context, req *pb.AuthorizeRequest,

) (*pb.AuthorizeResponse, error) {

// Always OK. Retry, fallback, and deadline paths never run.

return &pb.AuthorizeResponse{

Status: pb.Status_AUTHORIZED,

ChargeId: "ch_1",

// A field the payments team added last sprint is simply absent.

}, nil

}

This compiles against your checked-in proto, so it keeps passing after the payments team adds a required field your code now reads.

In-process stub server1–2 hours

orders_grpc_test.go

tool-assisted

// In-process stub server on a bufconn channel.

package orders

import (

"context"

"testing"

"google.golang.org/grpc"

"google.golang.org/grpc/test/bufconn"

)

func TestConfirmOrder(t *testing.T) {

lis := bufconn.Listen(1024 * 1024)

srv := grpc.NewServer()

pb.RegisterPaymentsServer(srv, FakePaymentsServer{})

go srv.Serve(lis)

defer srv.Stop()

conn, _ := grpc.DialContext(context.Background(), "bufnet",

grpc.WithContextDialer(dialer(lis)), grpc.WithInsecure())

defer conn.Close()

svc := NewOrderService(pb.NewPaymentsClient(conn))

order, err := svc.Confirm(context.Background(), "ord_1")

if err != nil || order.State != "CONFIRMED" {

t.Fatalf("got %v err %v", order, err)

}

Clean and fast — and the response still comes from FakePaymentsServer, so the test can only be as accurate as that hand-maintained stub.

With Keploy~5 minutes

mocks.yaml

auto-generated

# Recorded with: keploy record -c './orders-service'

# The real gRPC exchange, captured as HTTP/2 frames.

version: api.keploy.io/v1beta1

kind: gRPC

name: mock-6

spec:

request:

method: "/acme.payments.Payments/Authorize"

metadata:

content-type: "application/grpc"

authorization: "Bearer <captured>"

# The serialised Protobuf message, exactly as sent.

body_base64: "CgdvcmRfMRIHdG9rXzEyMxgY"

response:

status_code: 0

status_message: "OK"

body_base64: "CAESBWNoXzEaCkFVVEhPUklaRUQ="

trailers:

grpc-status: "0"

x-payments-region: "us-west-2"

The Protobuf bytes and the trailing metadata are what the real payments service returned, so a proto change shows up as a diff on the next re-record.

Times are estimates for authoring one endpoint’s coverage from scratch, not measurements.

Explore the docs Request a trial

Keploy vs the alternatives

gRPC testing tools, compared

The options a team on service and platform integrations actually reaches for, and where each one genuinely wins. Select a row for the full comparison.

Keploy

WireMock

LocalStack

Mountebank

Hoverfly

Postman

SmartBear ReadyAPI

Best in classStrongPartialNot covered

Assessments reflect each tool’s documented behaviour, not benchmark measurements.

Request a trial Book a call

How it works

Record your gRPC app once, replay it forever

Keploy sits below your gRPC process at the network layer. It watches the calls your app already makes, then serves them back on replay so tests run with no dependencies attached.

Your gRPC appGET/api/v1/orders/{id}200

RecordingKeploy proxyeBPF · userspace

Gogoogle.golang.org/grpc clients and servers

Javagrpc-java and grpc-spring-boot-starter

Node.js@grpc/grpc-js

Pythongrpcio

+4 more gRPC clients

An example shape of a captured call. Your own endpoints and dependencies come from your real traffic, so nothing here has to be written by hand.

Try Keploy for free Request a trial

Mock coverage

gRPC clients Keploy records, driver by driver

Keploy captures gRPC at the wire protocol, so 5 of these 8 clients need no adapter, no test double, and no gRPC instance in CI.

Auto-mocked
GoView page
google.golang.org/grpc clients and servers
Auto-mocked
JavaView page
grpc-java and grpc-spring-boot-starter
Auto-mocked
Node.jsView page
@grpc/grpc-js
Auto-mocked
PythonView page
grpcio
Auto-mocked
Spring BootView page
gRPC services alongside HTTP endpoints
Partial
gRPC-Web
Browser calls proxied over HTTP/1.1
Partial
Bidirectional streaming
Interleaved client and server frame sequences
Partial
.NET
Grpc.Net.Client and ASP.NET Core gRPC

Explore the docs Book a call

Quick start

Your first gRPC test suite in under five minutes

Every command below runs against your existing gRPC service. Nothing in your source tree changes.

1
1Install the Keploy CLI
One binary on the recording machine. No interceptor is registered and no proto is regenerated.
curl -sSL https://keploy.io/install.sh | bash
2
2Record with your dependencies reachable
Run the service as usual against real downstream gRPC services. Requests, responses, statuses, and trailers are captured.
keploy record -c "./orders-service"
3
3Exercise the RPCs that matter
Drive the service through its own API, or call it directly with grpcurl. Both record the downstream calls it makes.
grpcurl -plaintext -d '{"order_id":"ord_1"}' localhost:50051 acme.orders.Orders/Confirm
4
4Replay with dependencies switched off
Take the downstream services offline and run the suite. If replay passes, every RPC your code makes is answered by a recorded mock.
keploy test -c "./orders-service" --delay 10