---
title: gRPC
description: Learn how to integrate Allure with gRPC Java to record each gRPC call as a step with its messages, metadata and status in your test report.
---

# Getting started with Allure gRPC

[![Allure gRPC latest version](https://img.shields.io/maven-central/v/io.qameta.allure/allure-grpc?style=flat "allure-grpc")](https://mvnrepository.com/artifact/io.qameta.allure/allure-grpc)

Enrich your [Allure Report](https://allurereport.org/docs/) test reports with the details of the calls your tests make via [gRPC Java](https://grpc.io/docs/languages/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](/docs/junit-jupiter/), [Allure TestNG](/docs/testng/), [Allure Cucumber-JVM](/docs/cucumberjvm/), 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](/docs/frameworks/).

1. 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:**
   ```xml
   <!-- 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):**
   ```kts
   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):**
   ```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"
   }
   ```

1. 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.

   ```java
   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()`:

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

   Some aspects of the `AllureGrpc` behavior can be affected via its [configuration methods](/docs/grpc-configuration/).

1. 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](/docs/attachments/#http-exchanges) 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](/docs/grpc-configuration/#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.