examples: unit test examples for users

Demonstrate unit testing gRPC clients and servers with `InProcessTransport`.

Author: dapengzhang0

examples/README.md

@@ -44,3 +44,23 @@ $ mvn exec:java -Dexec.mainClass=io.grpc.examples.helloworld.HelloWorldServer
 $ # In another terminal run the client
 $ mvn exec:java -Dexec.mainClass=io.grpc.examples.helloworld.HelloWorldClient
 ```
+
+Unit test examples
+==============================================
+
+Examples for unit testing gRPC clients and servers are located in [examples/src/test](src/test).
+
+In general, we DO NOT allow overriding the client stub.
+We encourage users to leverage `InProcessTransport` as demonstrated in the examples to
+write unit tests. `InProcessTransport` is light-weight and runs the server
+and client in the same process without any socket/TCP connection.
+
+For testing a gRPC client, create the client with a real stub
+using an
+[InProcessChannel](../core/src/main/java/io/grpc/inprocess/InProcessChannelBuilder.java),
+and test it against an
+[InProcessServer](../core/src/main/java/io/grpc/inprocess/InProcessServerBuilder.java)
+with a mock/fake service implementation.
+
+For testing a gRPC server, create the server as an InProcessServer,
+and test it against a real client stub with an InProcessChannel.

examples/build.gradle

@@ -28,6 +28,9 @@ dependencies {
   compile "io.grpc:grpc-netty:${grpcVersion}"
   compile "io.grpc:grpc-protobuf:${grpcVersion}"
   compile "io.grpc:grpc-stub:${grpcVersion}"
+
+  testCompile "junit:junit:4.11"
+  testCompile "org.mockito:mockito-core:1.9.5"
 }
 
 protobuf {

examples/pom.xml

@@ -28,6 +28,18 @@
       <artifactId>grpc-stub</artifactId>
       <version>${grpc.version}</version>
     </dependency>
+    <dependency>
+      <groupId>junit</groupId>
+      <artifactId>junit</artifactId>
+      <version>4.11</version>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.mockito</groupId>
+      <artifactId>mockito-core</artifactId>
+      <version>1.9.5</version>
+      <scope>test</scope>
+    </dependency>
   </dependencies>
   <build>
     <extensions>

examples/src/main/java/io/grpc/examples/advanced/HelloJsonServer.java

@@ -61,11 +61,11 @@
 public class HelloJsonServer {
   private static final Logger logger = Logger.getLogger(HelloWorldServer.class.getName());
 
-  /* The port on which the server should run */
-  private int port = 50051;
   private Server server;
 
   private void start() throws IOException {
+    /* The port on which the server should run */
+    int port = 50051;
     server = ServerBuilder.forPort(port)
         .addService(new GreeterImpl())
         .build()

examples/src/main/java/io/grpc/examples/errorhandling/DetailErrorSample.java

@@ -86,11 +86,10 @@ public static void main(String[] args) throws Exception {
     new DetailErrorSample().run();
   }
 
-  private Server server;
   private ManagedChannel channel;
 
   void run() throws Exception {
-    server = ServerBuilder.forPort(0).addService(new GreeterGrpc.GreeterImplBase() {
+    Server server = ServerBuilder.forPort(0).addService(new GreeterGrpc.GreeterImplBase() {
       @Override
       public void sayHello(HelloRequest request, StreamObserver<HelloReply> responseObserver) {
         Metadata trailers = new Metadata();

examples/src/main/java/io/grpc/examples/errorhandling/ErrorHandlingClient.java

@@ -67,11 +67,11 @@ public static void main(String [] args) throws Exception {
     new ErrorHandlingClient().run();
   }
 
-  private Server server;
   private ManagedChannel channel;
 
   void run() throws Exception {
-    server = ServerBuilder.forPort(0).addService(new GreeterGrpc.GreeterImplBase() {
+    // Port 0 means that the operating system will pick an available port to use.
+    Server server = ServerBuilder.forPort(0).addService(new GreeterGrpc.GreeterImplBase() {
       @Override
       public void sayHello(HelloRequest request, StreamObserver<HelloReply> responseObserver) {
         responseObserver.onError(Status.INTERNAL

examples/src/main/java/io/grpc/examples/header/HeaderClientInterceptor.java

@@ -31,6 +31,8 @@
 
 package io.grpc.examples.header;
 
+import com.google.common.annotations.VisibleForTesting;
+
 import io.grpc.CallOptions;
 import io.grpc.Channel;
 import io.grpc.ClientCall;
@@ -49,7 +51,8 @@ public class HeaderClientInterceptor implements ClientInterceptor {
 
   private static final Logger logger = Logger.getLogger(HeaderClientInterceptor.class.getName());
 
-  private static Metadata.Key<String> customHeadKey =
+  @VisibleForTesting
+  static final Metadata.Key<String> CUSTOM_HEADER_KEY =
       Metadata.Key.of("custom_client_header_key", Metadata.ASCII_STRING_MARSHALLER);
 
   @Override
@@ -60,13 +63,13 @@ public <ReqT, RespT> ClientCall<ReqT, RespT> interceptCall(MethodDescriptor<ReqT
       @Override
       public void start(Listener<RespT> responseListener, Metadata headers) {
         /* put custom header */
-        headers.put(customHeadKey, "customRequestValue");
+        headers.put(CUSTOM_HEADER_KEY, "customRequestValue");
         super.start(new SimpleForwardingClientCallListener<RespT>(responseListener) {
           @Override
           public void onHeaders(Metadata headers) {
             /**
              * if you don't need receive header from server,
-             * you can use {@link io.grpc.stub.MetadataUtils attachHeaders}
+             * you can use {@link io.grpc.stub.MetadataUtils#attachHeaders}
              * directly to send header
              */
             logger.info("header received from server:" + headers);

examples/src/main/java/io/grpc/examples/header/HeaderServerInterceptor.java

@@ -31,6 +31,8 @@
 
 package io.grpc.examples.header;
 
+import com.google.common.annotations.VisibleForTesting;
+
 import io.grpc.ForwardingServerCall.SimpleForwardingServerCall;
 import io.grpc.Metadata;
 import io.grpc.ServerCall;
@@ -46,7 +48,8 @@ public class HeaderServerInterceptor implements ServerInterceptor {
 
   private static final Logger logger = Logger.getLogger(HeaderServerInterceptor.class.getName());
 
-  private static Metadata.Key<String> customHeadKey =
+  @VisibleForTesting
+  static final Metadata.Key<String> CUSTOM_HEADER_KEY =
       Metadata.Key.of("custom_server_header_key", Metadata.ASCII_STRING_MARSHALLER);
 
 
@@ -59,7 +62,7 @@ public <ReqT, RespT> ServerCall.Listener<ReqT> interceptCall(
     return next.startCall(new SimpleForwardingServerCall<ReqT, RespT>(call) {
       @Override
       public void sendHeaders(Metadata responseHeaders) {
-        responseHeaders.put(customHeadKey, "customRespondValue");
+        responseHeaders.put(CUSTOM_HEADER_KEY, "customRespondValue");
         super.sendHeaders(responseHeaders);
       }
     }, requestHeaders);

examples/src/main/java/io/grpc/examples/helloworld/HelloWorldClient.java

@@ -50,11 +50,15 @@ public class HelloWorldClient {
 
   /** Construct client connecting to HelloWorld server at {@code host:port}. */
   public HelloWorldClient(String host, int port) {
-    channel = ManagedChannelBuilder.forAddress(host, port)
+    this(ManagedChannelBuilder.forAddress(host, port)
         // Channels are secure by default (via SSL/TLS). For the example we disable TLS to avoid
         // needing certificates.
-        .usePlaintext(true)
-        .build();
+        .usePlaintext(true));
+  }
+
+  /** Construct client for accessing RouteGuide server using the existing channel. */
+  HelloWorldClient(ManagedChannelBuilder<?> channelBuilder) {
+    channel = channelBuilder.build();
     blockingStub = GreeterGrpc.newBlockingStub(channel);
   }
 

examples/src/main/java/io/grpc/examples/helloworld/HelloWorldServer.java

@@ -44,11 +44,11 @@
 public class HelloWorldServer {
   private static final Logger logger = Logger.getLogger(HelloWorldServer.class.getName());
 
-  /* The port on which the server should run */
-  private int port = 50051;
   private Server server;
 
   private void start() throws IOException {
+    /* The port on which the server should run */
+    int port = 50051;
     server = ServerBuilder.forPort(port)
         .addService(new GreeterImpl())
         .build()
@@ -89,7 +89,7 @@ public static void main(String[] args) throws IOException, InterruptedException
     server.blockUntilShutdown();
   }
 
-  private class GreeterImpl extends GreeterGrpc.GreeterImplBase {
+  static class GreeterImpl extends GreeterGrpc.GreeterImplBase {
 
     @Override
     public void sayHello(HelloRequest req, StreamObserver<HelloReply> responseObserver) {