How to Mock gRPC APIs

Developing APIs can be a complex process, particularly when you want to ensure they perform as expected under various real-world conditions. API mocking offers a streamlined, effective way to simulate these conditions during the testing phase. But how can you mock gRPC APIs, which are inherently more complex due to their use of protocol buffers for data transfer?

This post covers the differences between HTTP and gRPC mocking protocols, plus steps and considerations for implementing a gRPC mock server using Speedscale’s production traffic replication, a technique that uses actual user interaction data to create a highly realistic mock server.

HTTP and gRPC mocking

gRPC uses HTTP/2 with protobuf messages in its common native transport. Many HTTP APIs instead use JSON or XML. This is a difference in API conventions and message encoding, not a claim that gRPC is independent of HTTP. See the gRPC core concepts.

gRPC defines service methods and typed messages, commonly through protobuf. A mock must account for the method, request and response messages, metadata, and terminal gRPC status. Streaming methods add ordering and lifecycle requirements.

However, the use of protocol buffers presents challenges when it comes to mocking. Since it’s not as readily interpretable or manipulable as JSON or XML, a gRPC API requires a more sophisticated approach to decode and encode messages, making a gRPC mock server more complex.

The importance of realistic mock servers

Despite the complexities of simulating and mocking gRPC APIs, the importance of having realistic mock servers cannot be overstated. Mock servers play a crucial role in the software development lifecycle, enhancing the efficiency, cost-effectiveness, and overall quality of your software.

efficient and realistic mock servers can significantly improve the agility of your development teams, as they allow teams to work independently, when fixing a simple bug, and collaboratively, when developing a new feature. Realistic mock servers have proven beneficial in various use cases. For instance, they can help in detecting bugs that would only surface under real-world conditions.

What is production traffic replication?

Production traffic replication imitates real user interactions by capturing user data in a live environment and then replaying it in a testing environment.

For example, if you have an online bookstore, conventional test scenarios might cover common use cases like searching for a book, adding it to the cart, and checking out. Conventional test scenarios, however, may not account for real-world complexities, such as: multiple users accessing the site concurrently, searching for unavailable or out-of-stock books, or unexpectedly abandoning transactions mid-funnel. A mock server replicating production traffic captures these use cases, providing a more accurate model of your service under real-world conditions.

Step 1: Capture traffic

Follow the traffic replay tutorial for a supported capture setup.

When capturing traffic, there are a few considerations to keep in mind:

The recorded traffic selection

Use a varied sample, beyond basic request types

Be sure to get a varied sample of your production traffic. For example, if your gRPC service facilitates different procedural calls or varying message structures, include them in your recorded traffic. The power of traffic replication lies in the accurate simulation of real-world conditions, so don’t restrict your selection to just common user operations or basic request types.

Use a longer sample, but not too long

The duration of your recorded traffic also plays a key role in building representative mock servers. If it’s too short, you might miss out on variations in usage patterns, but if it’s too long, you might drown in a sea of data. You’ll need to strike a balance to ensure your mock service accurately mirrors your live service.

Leverage snapshots to experiment easily

Speedscale captures traffic continuously, allowing you to focus on the amount of traffic to store in a snapshot, with the possibility of creating snapshots with overlapping traffic. This means you can experiment with different snapshots. Mock servers use a snapshot-id to determine which traffic should be used, so you can easily switch. Filters to narrow down traffic to just the calls you’d like to include in the snapshots are also available.

Protect captured data and verify TLS visibility

Configure and test capture redaction rules for credentials and sensitive payloads. Restrict access to recordings and inspect exported copies. Storage architecture alone does not sanitize traffic or establish compliance.

Check the current eBPF capture requirements for your kernel, architecture, and runtime. Supported JVM traffic uses a Java agent, which requires a JVM restart and new pods. For local traffic, configure the proxymock proxy workflow. Verify decoded exchanges with the actual capture mode.

Step 2: Create a mock gRPC server

In gRPC, correctly decoding protobuf messages is crucial. Improper decoding can result in a less representative mock server, potentially leading to inaccurate testing results. If your gRPC service employs nested protobuf messages, ensure the structure is decoded correctly so the mock maintains identical behavior in your mock service.

While most gRPC mock servers rely on the service definition from your .proto files to understand your gRPC service’s structure, Speedscale decodes gRPC into a general-purpose JSON format, eliminating access needs to any .proto file. This grants greater flexibility when filtering out specific transactions for testing, as well as reducing the complexity of creating mock servers.

Use configured response delays to test how the client handles slower replies. A delay does not reproduce packet loss, HTTP/2 flow control, or every streaming interaction. Test those mechanisms with a controllable real server when they are the subject.

Step 3: Integrate with your test environment

The service under test can now interact with this mock gRPC server as if it were the actual service, providing an environment that closely mirrors your production setup and the behavior of actual users. Next, ensure that your test environment’s network setup allows for communication with the gRPC mock server. This usually involves configuring network rules or setting up service discovery to locate the mock server. If you’re running services in Kubernetes, Speedscale automates this process.

For Kubernetes routing considerations, see mocking APIs within Kubernetes.

Step 4: Test and iterate

You can now start testing gRPC APIs by executing your usual suite of tests against the gRPC mock server. At this point, there may be mock functionality or API usage highlighted by your traffic capture that’ll lead you to consider adding new test cases.

Also, make sure to implement logging and monitoring for your test environment. It’s rarely enough to know that something is broken; you’ll need to determine the cause of the issue in order to fix it. This especially comes into play during performance testing, which involves testing your service under varying levels of load and observing that behavior.

Review the fixture, matching rules, and assertions as the live service changes. Recording more traffic or switching the snapshot ID does not by itself update expected behavior or validate newly introduced contract requirements.

Remember, the goal is to make your test environment as close to the production environment as possible. This means the traffic should be similar, the behaviors should be consistent, and the responses should be representative of what users would actually experience. If you need to test cases that are not in production already, use recorded traffic as the foundation and modify it. By doing this, you ensure that your service is ready to handle the real world.

See gRPC with Go for another application-side example.

Run this workflow with an LLM

Give this prompt to a coding assistant with access to your project and this article. Supply environment-specific values it cannot discover.

Read https://speedscale.com/blog/mock-grpc-apis/ and inspect my project instructions first. Create a local mock gRPC dependency from a representative recorded exchange for my client. Verify protocol and TLS visibility, preserve the proto and recorded response, prevent live fallback, and test success, non-OK status, and client deadline behavior. Check installed tool help before adapting commands. Report the checks actually run, their results, and anything you could not verify.