gRPC Mock

Because GrpcMock uses ThreadLocal for its static API, calling stubFor() or verifyThat() from a thread different from the one that initialized the test will result in UNIMPLEMENTED errors.

To fix this, you must use an explicit GrpcMock instance instead of static methods:

Option 1: Use the instance directly

• In Spring Boot: @Autowire the GrpcMock instance.
• In other setups: Create it via new GrpcMock.Builder()...build().start().
• Call grpcMock.register(...) and grpcMock.verifyThat(...) directly.

Option 2: Use configureFor(instance)

• Call configureFor(grpcMockInstance) at the start of your test method or in @BeforeEach. This allows you to continue using the static stubFor() and verifyThat() DSL.

// Option 1: Direct instance usage
@Test
void should_test_something() {
  grpcMock.register(unaryMethod(SimpleServiceGrpc.getUnaryRpcMethod())
        .willReturn(response));
  
  grpcMock.verifyThat(calledMethod(SimpleServiceGrpc.getUnaryRpcMethod()).build(), CountMatcher.once());
}

// Option 2: Using configureFor
@Test
void should_test_something() {
  configureFor(grpcMock);
  stubFor(unaryMethod(SimpleServiceGrpc.getUnaryRpcMethod())
        .willReturn(response));
}

To use gRPC Mock in Spring Boot, add the grpcmock-spring-boot dependency. Enable it by annotating your test class with @AutoConfigureGrpcMock.

Port Configuration:

• Setting the port to 0 (default recommended) selects a random port, which improves test speed and avoids conflicts. Access this port via the ${grpcmock.server.port} property to build your ManagedChannel.
• To use an In-Process server, use @AutoConfigureGrpcMock(useInProcessServer = true). Access the in-process name via ${grpcmock.server.name}.

Example (Random Port):

@SpringJUnitConfig
@SpringBootTest(classes = Application.class, webEnvironment = WebEnvironment.NONE)
@AutoConfigureGrpcMock
class TestClass {

  @Value("${grpcmock.server.port}")
  private int grpcMockPort;

  private ManagedChannel channel;

  @BeforeEach
  void setupChannel() {
    channel = ManagedChannelBuilder.forAddress("localhost", grpcMockPort)
        .usePlaintext()
        .build();
  }
}

<dependency>
  <groupId>org.grpcmock</groupId>
  <artifactId>grpcmock-spring-boot</artifactId>
  <version>1.0.0</version>
</dependency>

Use verifyThat() to assert that specific methods were called with expected parameters and frequency.

• Use calledMethod(method) to specify the method being verified.
• Use .withStatusOk(), .withHeader(), or .withRequest() to match the invocation details.
• Use times(n) or never() to verify the count.
• For streaming, use .withNumberOfRequests(n) and .withRequestAtIndex(index, request) to verify specific messages in a stream.

// Verify exact count and parameters
verifyThat(
    calledMethod(getUnaryRpcMethod())
        .withStatusOk()
        .withHeader("header-1", "value-1")
        .withRequest(request),
    times(3));

// Verify method was never called
verifyThat(getUnaryRpcMethod(), never());

// Verify client streaming request sequence
verifyThat(
    calledMethod(getClientStreamingRpcMethod())
        .withNumberOfRequests(2)
        .withFirstRequest(request)
        .withRequestAtIndex(1, request2));

For bidirectional streaming, stubs are selected on the first request message. Use bidiStreamingMethod() and willProxyTo() to implement custom logic. The willProxyTo method provides a responseObserver that you can use to react to incoming requests and send back responses manually.

stubFor(bidiStreamingMethod(SimpleServiceGrpc.getBidiStreamingRpcMethod())
    .withHeader("header-1", "value-1")
    .withFirstRequest(req -> req.getRequestMessage().endsWith("1"))
    .willProxyTo(responseObserver -> new StreamObserver<SimpleRequest>() {
        @Override
        public void onNext(SimpleRequest request) {
          SimpleResponse response = SimpleResponse.newBuilder()
            .setResponseMessage(request.getRequestMessage())
            .build();
          responseObserver.onNext(response);
        }
        
        @Override
        public void onError(Throwable error) {
          // handle error
        }
        
        @Override
        public void onCompleted() {
          responseObserver.onCompleted();
        }
    }));

When using the Spring Boot integration, you can configure the GrpcMock server via the AutoConfigureGrpcMock annotation. The following configuration options are supported:

• In-Process Server: Use useInProcessServer() to switch from a network-based server to an in-process server.
• Server Name: If using an in-process server, provide a name() to identify it.
• Port: Specify a fixed port using port(). Use 0 for dynamic port assignment.
• Interceptors: Provide an array of interceptors() (classes extending ServerInterceptor) which will be instantiated using their default no-args constructor.
• Executor:
  • Provide a executorBeanName() to use an existing Spring bean of type Executor.
  • Alternatively, specify executorThreadCount() to create a new fixed thread pool.
• Transport Security: Provide certChainFile() and privateKeyFile() to enable TLS. Both must be provided if one is specified.

Note: If certChainFile and privateKeyFile are both provided, the server will use transport security.