Skip to documentation

Guide · gRPC

Available

Mock the protobuf contract, not an HTTP-shaped approximation

DotMock compiles your descriptors once, validates every ProtoJSON message against them, and serves the same behavior over native gRPC and gRPC-Web.

In this guide

  • Import a canonical protobuf contract
  • Mock all four RPC modes
  • Model status, metadata, trailers, and state
  • Inspect, proxy, and replay real streams

Prerequisites

  • A gRPC DotMock workspace
  • A protobuf source or descriptor set
  • The workspace ID in $API_ID
On this page
  1. Compile the contract
  2. Author descriptor-valid transcripts
  3. Use the normal condition language
  4. Prove dry and live behavior
  5. Connect standard clients
  6. Proxy with managed TLS or mTLS

Compile the contract

Create a gRPC workspace and import multiple .proto files, a binary FileDescriptorSet, or its canonical protobuf JSON representation. Compatible method behavior survives contract updates; changed and removed signatures are archived for review.

bash
dotmock create api --type grpc --name "Users RPC" --from proto/
dotmock grpc services --api "$API_ID"

Author descriptor-valid transcripts

Every method keeps initial metadata, ordered response messages, trailing metadata, and final gRPC status separate. Unary methods return at most one message; streaming methods expose ordered transcripts and per-message timing.

  • Unary: one request, zero or one response message
  • Server streaming: one request, ordered response messages
  • Client streaming: ordered request messages, one response
  • Bidirectional: ordered inputs and outputs with after-request boundaries

Use the normal condition language

Cases are first-match-wins. Read message, messages, metadata, grpc, and visible state directly. Missing records and other failures are ordinary cases—not a special response mode.

javascript
!state.exists("users-by-id", message["userId"])
metadata["x-test-scenario"] == "rate-limit"
grpc.method == "GetUser" && message.userId == "usr_404"

Prove dry and live behavior

Safe tests execute real descriptor validation, matching, templating, and state actions in an isolated overlay. Live tests persist allowed state and create a decoded traffic record. Results keep headers, messages, trailers, status, and state diff separate.

bash
dotmock grpc test --api "$API_ID" --service users.v1.Users --method GetUser --from request.json
dotmock grpc test --api "$API_ID" --service users.v1.Users --method WatchUsers --from stream.json --live

Connect standard clients

The public gateway accepts native HTTP/2 gRPC and gRPC-Web. Workspace selection comes from the authority, while server reflection v1/v1alpha and grpc.health.v1 expose only that workspace's compiled services.

bash
grpcurl -plaintext users-rpc.localhost:7779 list
grpcurl -plaintext -d '{"userId":"usr_1"}' users-rpc.localhost:7779 users.v1.Users/GetUser

Proxy with managed TLS or mTLS

Configure a host:port target, server name, optional custom CA, and optional client certificate/key pair. Secrets are encrypted at rest, write-only in management responses, and never included in the public runtime document.