Getting started with Allure OkHttp

Enrich your Allure Report test reports with the detailed information about the HTTP requests performed via OkHttp.

This page describes Allure OkHttp 3.0.0 and newer, which requires Java 17 or newer. It works with OkHttp 3, 4 and 5.

Allure OkHttp 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 OkHttp integration to your project's dependencies.

   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-okhttp3</artifactId>
           <scope>test</scope>
       </dependency>
   </dependencies>

   Gradle (Kotlin)

   val allureVersion = "VERSION"
   
   dependencies {
       testImplementation(platform("io.qameta.allure:allure-bom:$allureVersion"))
       testImplementation("io.qameta.allure:allure-okhttp3")
   }

   Gradle (Groovy)

   def allureVersion = "VERSION"
   
   dependencies {
       testImplementation platform("io.qameta.allure:allure-bom:$allureVersion")
       testImplementation "io.qameta.allure:allure-okhttp3"
   }

3. Register an instance of AllureOkHttp3 as an interceptor of the OkHttp client that your tests use.

   The example below shows usage of Allure OkHttp in a JUnit Jupiter test.

   import io.qameta.allure.okhttp3.AllureOkHttp3;
   import okhttp3.OkHttpClient;
   import okhttp3.Request;
   import okhttp3.Response;
   import org.junit.jupiter.api.Test;
   
   import static org.junit.jupiter.api.Assertions.assertEquals;
   
   class TestMyWebsite {
   
       static OkHttpClient client = new OkHttpClient.Builder()
               .addInterceptor(new AllureOkHttp3())
               .build();
   
       @Test
       void testSomeRequest() throws Exception {
           Request request = new Request.Builder()
                   .url("https://jsonplaceholder.typicode.com/todos/1")
                   .build();
   
           try (Response response = client.newCall(request).execute()) {
               assertEquals(200, response.code());
           }
       }
   }

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

What the report shows

Each request made during a test or a fixture, including the ones made with enqueue(), is added to the test results as a single HTTP exchange attachment called “HTTP exchange”. It contains:

• the request method, URL, headers and body;
• the response status, headers and body;
• the start and end time of the request;
• the error details, if the request fails, for example, because the server can't be reached.

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

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

Server-sent events

To work with server-sent events, OkHttp provides the okhttp-sse library. Its event source listener runs on OkHttp's own threads, which don't know which test is running. So if your listener adds steps or attachments, for example, for each received event, they get lost or may end up in a different test.

To keep them in the test that opens the event source, create the event source factory via AllureEventSources.createFactory() instead of EventSources.createFactory(). AllureEventSources requires OkHttp 5 or newer.

import io.qameta.allure.Allure;
import io.qameta.allure.okhttp3.AllureEventSources;
import io.qameta.allure.okhttp3.AllureOkHttp3;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.sse.EventSource;
import okhttp3.sse.EventSourceListener;
import org.junit.jupiter.api.Test;

import java.util.concurrent.CountDownLatch;
import java.util.concurrent.TimeUnit;

class TestOrderEvents {

    static OkHttpClient client = new OkHttpClient.Builder()
            .addInterceptor(new AllureOkHttp3())
            .build();

    static EventSource.Factory eventSourceFactory = AllureEventSources.createFactory(client);

    @Test
    void testOrderEvents() throws Exception {
        CountDownLatch closed = new CountDownLatch(1);

        EventSource eventSource = eventSourceFactory.newEventSource(
                new Request.Builder().url("https://example.com/orders/events").build(),
                new EventSourceListener() {
                    @Override
                    public void onEvent(EventSource source, String id, String type, String data) {
                        Allure.step("Received event " + type);
                        Allure.attachment("Event " + id, data);
                    }

                    @Override
                    public void onClosed(EventSource source) {
                        closed.countDown();
                    }
                });

        closed.await(10, TimeUnit.SECONDS);
        eventSource.cancel();
    }
}

The factory remembers the running test or fixture each time newEventSource() is called. This means that you can create the client and the factory once and share them between tests, as in the example above.

The HTTP exchange attachment of an event source contains the request and the response headers, but not the events themselves. To see the events in the report, add them from your listener, as shown above.

Configuration

Configure the HTTP exchange attachment

• configureHttpExchange(Consumer<HttpExchange.Builder> exchangeCustomizer)

Use configureHttpExchange() to control what the HTTP exchange attachment contains. The method returns the interceptor, so you can call it right after new AllureOkHttp3(). If you call it again, the new settings replace the previous ones.

The following methods are available on the builder:

• redactHeader(String name) - replace the value of the given request or response header with a placeholder. The name is not case-sensitive.
• redactCookie(String name) - replace the value of the given cookie with a placeholder. Allure shows the cookies from the Cookie and Set-Cookie headers separately from the other headers.
• setMaxBodySize(long maxBodySize) - the maximum number of bytes of a request or response body to keep. Longer bodies are truncated and marked as truncated in the report. Defaults to 1 MiB.

By default, the values of the Authorization and Proxy-Authorization headers are replaced with a placeholder.

import io.qameta.allure.okhttp3.AllureOkHttp3;
import okhttp3.OkHttpClient;

static OkHttpClient client = new OkHttpClient.Builder()
        .addInterceptor(new AllureOkHttp3()
                .configureHttpExchange(exchange -> exchange
                        .redactHeader("X-Api-Key")
                        .redactCookie("SESSION")
                        .setMaxBodySize(64 * 1024)))
        .build();