Migrating to Allure Java 3

Allure Java 3.0 is a major release of the Allure integrations for JVM test frameworks (JUnit, TestNG, Cucumber-JVM, Spock, ScalaTest, Karate and others). It raises the minimum Java version, removes several legacy modules and Runtime API methods, changes how HTTP requests are recorded and how tests are identified in the report history.

This guide lists everything you may need to change when upgrading from Allure Java 2.x.

TIP

You do not need to change your Allure Report version. Results produced by Allure Java 3 can be viewed in both Allure Report 3 and Allure Report 2.

1. Check the requirements

Allure Java 3 requires Java 17 or newer. The allure-karate and allure-jooq modules require Java 21 or newer.

Some framework integrations also require newer framework versions:

• TestNG: 7.10 or newer.
• Karate: Karate 2 (io.karatelabs:karate-core). Allure Java 3 no longer supports Karate 1.

If your tests run on an older Java or framework version, keep using Allure Java 2.x until you can upgrade.

2. Update the dependency version

If you use allure-bom, update its version. All Allure modules will be upgraded together.

Maven

<properties>
    <allure.version>3.0.0</allure.version>
</properties>

Gradle (Kotlin)

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

Gradle (Groovy)

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

If you use the Allure Gradle plugin to add the adapters, it still uses Allure Java 2.x by default. Use plugin version 4.3.0 or newer and opt in to Allure Java 3 explicitly, see Using Allure Java 3:

allure {
    adapter {
        allureJavaVersion.set("3.0.0")
    }
}

3. Replace removed modules

The following modules are no longer published in Allure Java 3. If your project depends on any of them, replace it as shown below.

Removed module	Replacement
allure-junit5	allure-jupiter, see JUnit Jupiter
allure-junit5-assert	allure-jupiter-assert
allure-cucumber4-jvm allure-cucumber5-jvm allure-cucumber6-jvm	Upgrade to Cucumber-JVM 7 and use allure-cucumber7-jvm, see Cucumber-JVM
allure-jbehave (JBehave 4)	Upgrade to JBehave 5 and use allure-jbehave5, see JBehave
allure-spock (Spock 1)	Upgrade to Spock 2 and use allure-spock2, see Spock
allure-okhttp (OkHttp 2)	Upgrade to OkHttp 3 or newer and use allure-okhttp3
allure-attachments	No replacement needed. HTTP integrations now produce HTTP exchange attachments without it
allure-test-filter	No replacement needed. Test plan support is now part of allure-java-commons, which every adapter already depends on. Remove the dependency
allure-reader	No replacement

4. Replace removed Runtime API methods

Several methods of the Allure class and its lifecycle were removed. Replace them as shown below.

Removed method	Replacement
Allure.addAttachment(name, content)	Allure.attachment(name, content)
Allure.addAttachment(name, type, content)	Allure.attachment(name, type, content)
Allure.addAttachment(name, type, content, fileExtension)	Allure.attachment(name, type, content, AttachmentOptions.withFileExtension(fileExtension))
Allure.addByteAttachmentAsync() Allure.addStreamAttachmentAsync()	Allure.attachmentAsync(name, type, body), where body is a CompletionStage of an InputStream
Allure.addDescription(description)	Allure.description(description)
Allure.addDescriptionHtml(descriptionHtml)	Allure.descriptionHtml(descriptionHtml)
Allure.addLabels(labels...)	Allure.label(name, value) for each label
Allure.addLinks(links...)	Allure.link(name, type, url) for each link
Allure.getLifecycle().updateTestCase(update)	Allure.getLifecycle().updateTest(update)

The lower-level AllureLifecycle methods that take UUIDs, such as startStep(uuid, result), stopStep(uuid) or getCurrentTestCase(), were replaced with methods that take an AllureExternalKey. They are mostly used by custom integrations, see For integration authors.

5. Review behavior changes

HTTP requests are recorded as HTTP exchanges

All HTTP client integrations (REST Assured, OkHttp, Apache HttpClient, Spring Web, JAX-RS and others) now record each request and its response as a single HTTP exchange attachment. Allure Report shows it as an interactive request/response viewer.

In Allure Java 2.x, these integrations produced two separate HTML attachments rendered by FreeMarker templates. The templates and the methods for customizing them, such as setRequestTemplate() and setResponseTemplate() in Allure REST Assured, were removed. To control sensitive data and body sizes, use configureHttpExchange() instead.

Attachments are wrapped in steps

Attachments added via the Runtime API, such as Allure.attachment(), now appear in the report as a step with the attachment's name, placed in the order the attachments were created relative to other steps.

Test history

Allure Java 3 calculates test identifiers differently, which affects history and retries in two ways:

• History may start over after the upgrade. Tests run with JUnit 4, TestNG and JBehave get new identifiers, so the first report generated after the upgrade shows them as new tests, without their previous history. Tests run with JUnit Jupiter, Cucumber-JVM and Spock keep their history. This happens in both Allure Report 3 and Allure Report 2.

• Runtime parameters now affect the test's identity. Parameters added via Allure.parameter() are now taken into account, together with the parameters provided by the test framework. If a parameter's value changes between runs, such as a timestamp or a random ID, the test is treated as a new test on every run. Mark such parameters as excluded:

  Allure.parameter("startedAt", startedAt, true);

Test plan environment variable

The legacy AS_TESTPLAN_PATH environment variable is no longer supported. Use ALLURE_TESTPLAN_PATH to point Allure to a test plan file.

Results directory cleanup

The allure.results.clean.before.run and allure.results.clean.only.once configuration properties were removed. Allure Java no longer deletes existing files in the results directory. Use your build tool to clean it, for example, mvn clean or gradle clean.

Jakarta APIs

allure-servlet-api and allure-jax-rs now use the jakarta.* APIs instead of javax.*. If your project still uses javax.servlet or javax.ws.rs, migrate it to Jakarta EE before upgrading.

For integration authors

If you develop your own Allure integration on top of allure-java-commons, note that the AllureLifecycle API was reworked. Methods that identified tests, steps, fixtures and containers by UUID strings were removed. They were replaced with methods that take an AllureExternalKey, and test containers were replaced with scopes (registerScope(), addTestToScope() and writeScope()). The format of the result files written to disk is unchanged.

6. Explore what's new

Allure Java 3 also brings new features, including:

• Global errors and attachments — failures in fixtures and lifecycle hooks are reported for the whole test run instead of creating artificial test results, and you can report your own via Allure.globalError().
• HTTP exchange attachments with header, cookie, query and form parameter redaction.
• Support for JUnit 6.
• The @Flaky and @Muted annotations now work with JUnit 4.