Package org.grpcmock

Class GrpcMock

java.lang.Object
org.grpcmock.GrpcMock
public final class GrpcMock extends Object
Main gRPC Mock class for managing the gRPC server.
Author:
Fadelis

  • Method Details

    • getPort

      public int getPort()
      Retrieve current port of the server.
      Throws:
      IllegalStateException - if the server has not yet been started.

    • getInProcessName

      public String getInProcessName()
      Retrieve the name of InProcessServer if one is used.
      Throws:
      GrpcMockException - if the server is not an in-process one.

    • start

      public GrpcMock start()
      Starts the gRPC mock server. Does not throw any exception if the server is already running.
      Throws:
      GrpcMockException - if the server is unable to start.

    • stop

      public GrpcMock stop()
      Stops the gRPC mock server via Server.shutdownNow().

    • register

      public <ReqT, RespT> void register(@Nonnull MethodStubBuilder<ReqT,RespT> methodStubBuilder)

      Register a gRPC method stub to the server.

      If given method is already registered, then configured scenarios will be appended to that method's stub.

    • verifyThat

      public <ReqT> void verifyThat(@Nonnull RequestPattern<ReqT> requestPattern, @Nonnull CountMatcher countMatcher)
      Verify that given RequestPattern is called a number of times satisfying the provided CountMatcher.
      Throws:
      GrpcMockVerificationError - if the verify step fails.

    • capturedRequestsFor

      public <ReqT> List<CapturedRequest<ReqT>> capturedRequestsFor(@Nonnull RequestPattern<ReqT> requestPattern)
      Return all CapturedRequest that match the provided request pattern.

    • resetAll

      public void resetAll()
      Removes all stubs defined from the mock server.

    • grpcMock

      public static GrpcMockBuilder grpcMock()
      Returns gRPC Mock builder initiated with a random port.

    • grpcMock

      public static GrpcMockBuilder grpcMock(int port)
      Returns gRPC Mock builder with the given port. If given port is 0, then a random free port will be selected.

    • inProcessGrpcMock

      public static InProcessGrpcMockBuilder inProcessGrpcMock(@Nonnull String name)
      Returns an in-process gRPC Mock builder with the given name.

    • inProcessGrpcMock

      public static InProcessGrpcMockBuilder inProcessGrpcMock()
      Returns an in-process gRPC Mock builder by generating a random name.

    • grpcMock

      public static GrpcMockBuilder grpcMock(@Nonnull io.grpc.ServerBuilder serverBuilder)
      Returns gRPC Mock builder using the provided gRPC ServerBuilder configuration. The user is responsible that the port used in the builder is available and free.

    • configureFor

      public static void configureFor(int port)
      Configure the global static gRPC Mock instance to use a new one with the provided port.

    • configureFor

      public static void configureFor(@Nonnull GrpcMock client)
      Configure the global static gRPC Mock instance to use the provided one.

    • getGlobalPort

      public static int getGlobalPort()
      Returns the port for the global static gRPC Mock instance.
      Throws:
      IllegalStateException - if the server has not yet been started.

    • getGlobalInProcessName

      public static String getGlobalInProcessName()
      Returns the name of InProcessServer if one is used for the global static gRPC Mock instance.
      Throws:
      GrpcMockException - if the server is not an in-process one.

    • resetMappings

      public static void resetMappings()
      Removes all stubs defined from the global mock server.

    • stubFor

      public static <ReqT, RespT> void stubFor(MethodStubBuilder<ReqT,RespT> methodStubBuilder)

      Register a gRPC method stub to the global gRPC mock server.

      If given method is already registered, then configured scenarios will be appended to that method's stub.

      When multiple stubs, satisfying the same request condition matching, are registered, the last one registered will be triggered.

      Parameters:
      methodStubBuilder - a method stub builder created through one of unaryMethod(io.grpc.MethodDescriptor<ReqT, RespT>), serverStreamingMethod(io.grpc.MethodDescriptor<ReqT, RespT>), clientStreamingMethod(io.grpc.MethodDescriptor<ReqT, RespT>) or bidiStreamingMethod(io.grpc.MethodDescriptor<ReqT, RespT>).

    • unaryMethod

      public static <ReqT, RespT> UnaryMethodStubBuilderStep<ReqT,RespT> unaryMethod(@Nonnull io.grpc.MethodDescriptor<ReqT,RespT> method)
      Returns a stub builder for MethodDescriptor.MethodType.UNARY method or MethodDescriptor.MethodType.SERVER_STREAMING method with a single response.

    • serverStreamingMethod

      public static <ReqT, RespT> ServerStreamingMethodStubBuilderStep<ReqT,RespT> serverStreamingMethod(@Nonnull io.grpc.MethodDescriptor<ReqT,RespT> method)
      Returns a stub builder for MethodDescriptor.MethodType.SERVER_STREAMING method.

    • clientStreamingMethod

      public static <ReqT, RespT> ClientStreamingMethodStubBuilderStep<ReqT,RespT> clientStreamingMethod(@Nonnull io.grpc.MethodDescriptor<ReqT,RespT> method)

      Returns a stub builder for MethodDescriptor.MethodType.CLIENT_STREAMING method or MethodDescriptor.MethodType.BIDI_STREAMING method with a single response at request stream completion.

    • bidiStreamingMethod

      public static <ReqT, RespT> BidiStreamingMethodStubBuilderStep<ReqT,RespT> bidiStreamingMethod(@Nonnull io.grpc.MethodDescriptor<ReqT,RespT> method)

      Returns a stub builder for MethodDescriptor.MethodType.BIDI_STREAMING method.

    • response

      public static <RespT> ObjectResponseActionBuilder<RespT> response(@Nonnull RespT responseObject)
      Returns a response action, which will send out the given response object via StreamObserver.onNext(V).

    • exception

      public static ExceptionResponseActionBuilder exception(@Nonnull Throwable exception)

      Returns a response action, which will send out the given exception via StreamObserver.onError(java.lang.Throwable).

      It not recommended to use this methods, because without a proper ServerInterceptor translating non-gRPC exceptions to gRPC ones It will be translated to Status.UNKNOWN type of exception without any message. The statusException(Status) should be used to define concrete gRPC errors.

    • statusException

      public static ExceptionResponseActionBuilder statusException(@Nonnull io.grpc.Status status)

      Returns a response action, which will send out a StatusRuntimeException with given Status via StreamObserver.onError(java.lang.Throwable).

    • stream

      public static <RespT> ObjectStreamResponseBuilderStep<RespT> stream(@Nonnull ObjectResponseActionBuilder<RespT> responseAction)

      Returns a stream response, which can respond with multiple ResponseAction.

    • stream

      public static <RespT> ObjectStreamResponseBuilderStep<RespT> stream(@Nonnull List<RespT> responses)

      Returns a stream response, which can respond with multiple ResponseAction.

      In order to configure a Delay for the actions see response(RespT) method.

      Parameters:
      responses - single response objects for the stream response. Will be returned in provided list order.

    • stream

      public static <RespT> ObjectStreamResponseBuilderStep<RespT> stream(@Nonnull RespT... responses)

      Returns a stream response, which can respond with multiple ResponseAction.

      In order to configure a Delay for the actions see response(RespT) method.

      Parameters:
      responses - single response objects for the stream response. Will be returned in provided array order.

    • stream

      public static <RespT> ExceptionStreamResponseBuildersStep<RespT> stream(@Nonnull ExceptionResponseActionBuilder responseAction)

      Returns a terminating stream response, which will respond with ResponseAction and terminate the call, since it will be StreamObserver.onError(java.lang.Throwable) response.

    • verifyThat

      public static <ReqT> void verifyThat(@Nonnull io.grpc.MethodDescriptor<ReqT,?> method)

      Verify that given method was called exactly once.

      This is the same as invoking verifyThat(method, times(1)).

      Throws:
      GrpcMockVerificationError - if the verify step fails.

    • verifyThat

      public static <ReqT> void verifyThat(@Nonnull RequestPatternBuilderStep<ReqT> requestPattern)

      Verify that given RequestPattern was called exactly once.

      This is the same as invoking verifyThat(requestPattern, times(1)).

      Throws:
      GrpcMockVerificationError - if the verify step fails.

    • verifyThat

      public static <ReqT> void verifyThat(@Nonnull io.grpc.MethodDescriptor<ReqT,?> method, @Nonnull CountMatcher countMatcher)

      Verify that given method was called number of times satisfying provided CountMatcher.

      Throws:
      GrpcMockVerificationError - if the verify step fails.

    • verifyThat

      public static <ReqT> void verifyThat(@Nonnull RequestPatternBuilderStep<ReqT> requestPattern, @Nonnull CountMatcher countMatcher)

      Verify that given RequestPattern was called number of times satisfying provided CountMatcher.

      Throws:
      GrpcMockVerificationError - if the verify step fails.

    • capturedRequestsFor

      public static <ReqT> List<CapturedRequest<ReqT>> capturedRequestsFor(@Nonnull RequestPatternBuilderStep<ReqT> requestPattern)
      Return all CapturedRequest that match the provided request pattern.

    • calledMethod

      public static <ReqT> RequestPatternBuilderStep<ReqT> calledMethod(@Nonnull io.grpc.MethodDescriptor<ReqT,?> method)
      Returns request pattern builder instance, used for verifying call count using verifyThat(RequestPatternBuilderStep, CountMatcher).

    • times

      public static CountMatcher times(int count)
      Called exactly the specified number of times.

    • never

      public static CountMatcher never()
      Never called.

    • atLeast

      public static CountMatcher atLeast(int count)
      Called the specified number of times or more.

    • atMost

      public static CountMatcher atMost(int count)
      Called the specified number of times or less.