Getting started with Allure gRPC

Enrich your Allure Report test reports with the details of the calls your tests make via gRPC Java.

This page describes Allure gRPC 3.0.0 and newer, which requires Java 17 or newer.

Allure gRPC is compatible with all JVM-based Allure integrations, including Allure JUnit Jupiter, Allure TestNG, Allure Cucumber-JVM, and more.

To enable the integration in your project:

1. Make sure you have the Allure Report integration enabled for the test framework you use.

   See the instructions in the integration's documentation in Frameworks.

2. Add the Allure gRPC integration and the Protobuf JSON utilities to your project's dependencies.

   Allure gRPC uses protobuf-java-util to show the messages as JSON, but doesn't add it to your project. Use the same version as the protobuf-java library your project already uses.

   Maven

   <!-- Define the version of Allure you want to use via the allure.version property -->
   <properties>
       <allure.version>VERSION</allure.version>
   </properties>
   
   <!-- Add allure-bom to dependency management to ensure correct versions of all the dependencies are used -->
   <dependencyManagement>
       <dependencies>
           <dependency>
               <groupId>io.qameta.allure</groupId>
               <artifactId>allure-bom</artifactId>
               <version>${allure.version}</version>
               <type>pom</type>
               <scope>import</scope>
           </dependency>
       </dependencies>
   </dependencyManagement>
   
   <dependencies>
       <dependency>
           <groupId>io.qameta.allure</groupId>
           <artifactId>allure-grpc</artifactId>
           <scope>test</scope>
       </dependency>
       <dependency>
           <groupId>com.google.protobuf</groupId>
           <artifactId>protobuf-java-util</artifactId>
           <version>PROTOBUF_VERSION</version>
           <scope>test</scope>
       </dependency>
   </dependencies>

   Gradle (Kotlin)

   val allureVersion = "VERSION"
   
   dependencies {
       testImplementation(platform("io.qameta.allure:allure-bom:$allureVersion"))
       testImplementation("io.qameta.allure:allure-grpc")
       testImplementation("com.google.protobuf:protobuf-java-util:PROTOBUF_VERSION")
   }

   Gradle (Groovy)

   def allureVersion = "VERSION"
   
   dependencies {
       testImplementation platform("io.qameta.allure:allure-bom:$allureVersion")
       testImplementation "io.qameta.allure:allure-grpc"
       testImplementation "com.google.protobuf:protobuf-java-util:PROTOBUF_VERSION"
   }

3. Register an instance of AllureGrpc as a client interceptor, either on the channel or on a stub.

   The example below shows usage of Allure gRPC in a JUnit Jupiter test. It uses the gRPC health checking service, so replace the address and the stub with your own.

   import io.grpc.ManagedChannel;
   import io.grpc.ManagedChannelBuilder;
   import io.grpc.health.v1.HealthCheckRequest;
   import io.grpc.health.v1.HealthCheckResponse;
   import io.grpc.health.v1.HealthGrpc;
   import io.qameta.allure.grpc.AllureGrpc;
   import org.junit.jupiter.api.Test;
   
   import static org.junit.jupiter.api.Assertions.assertEquals;
   
   class TestOrderService {
   
       @Test
       void testServiceIsServing() {
           ManagedChannel channel = ManagedChannelBuilder.forAddress("localhost", 8080)
                   .intercept(new AllureGrpc())
                   .usePlaintext()
                   .build();
           try {
               HealthCheckResponse response = HealthGrpc.newBlockingStub(channel)
                       .check(HealthCheckRequest.newBuilder().setService("shop.Orders").build());
               assertEquals(HealthCheckResponse.ServingStatus.SERVING, response.getStatus());
           } finally {
               channel.shutdownNow();
           }
       }
   }

   To add the interceptor to a single stub instead, use withInterceptors():

   HealthGrpc.newBlockingStub(channel).withInterceptors(new AllureGrpc())

   Some aspects of the AllureGrpc behavior can be affected via its configuration methods.

4. Run your tests and generate a test report the same way as you would do usually.

What the report shows

Allure gRPC adds a step for each gRPC call made during a test or a fixture, for example, “Send unary gRPC request to localhost:8080/grpc.health.v1.Health/Check”. The step name contains the type of the call (unary, client_streaming, server_streaming or bidi_streaming), the server address and the full name of the method.

The step contains a “gRPC exchange” HTTP exchange attachment with:

• the request and response messages, converted to JSON (for streaming calls, all messages of the stream, in order);
• the request metadata, and the response headers and trailers, including grpc-status and grpc-message;
• the start and end time of the call.

Repeated metadata values are kept in their original order. Values of binary metadata keys (the ones ending with -bin) are shown Base64-encoded. By default, the authorization metadata value is replaced with a placeholder.

By default, if a call ends with a non-zero gRPC status code, the step is marked as failed. See Step status to change this.

A call is added to the report when it ends. If a streaming call is still open when the test ends, its step has no status and no attachment, so make sure that your tests complete or cancel their streaming calls.

Calls made while no test or fixture is running are not added to the report.

In Allure gRPC 2.x, the request and the response are added as two separate attachments.