---
title: Migrating to Allure Java 3
description: How to upgrade your Java, Kotlin, Groovy or Scala test project from Allure Java 2.x to Allure Java 3 — new requirements, removed modules and their replacements, and behavior changes.
---

# 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:**
```xml
<properties>
    <allure.version>3.0.0</allure.version>
</properties>
```

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

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

If you use the [Allure Gradle plugin](/docs/integrations-gradle/) 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](/docs/integrations-gradle/#using-allure-java-3):

```kts
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](/docs/junit-jupiter/)                                                                                  |
| `allure-junit5-assert`                                                     | `allure-jupiter-assert`                                                                                                                      |
| `allure-cucumber4-jvm`<br>`allure-cucumber5-jvm`<br>`allure-cucumber6-jvm` | Upgrade to Cucumber-JVM 7 and use `allure-cucumber7-jvm`, see [Cucumber-JVM](/docs/cucumberjvm/)                                             |
| `allure-jbehave` (JBehave 4)                                               | Upgrade to JBehave 5 and use `allure-jbehave5`, see [JBehave](/docs/jbehave/)                                                                |
| `allure-spock` (Spock 1)                                                   | Upgrade to Spock 2 and use `allure-spock2`, see [Spock](/docs/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](/docs/attachments/#http-exchanges) 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()`<br>`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](#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](/docs/attachments/#http-exchanges). 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](/docs/restassured-configuration/), 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](/docs/how-it-works-test-identifiers/) differently, which affects [history and retries](/docs/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:

  ```java
  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](/docs/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](/docs/attachments/#http-exchanges) with header, cookie, query and form parameter redaction.
- Support for [JUnit 6](/docs/junit-jupiter/).
- The `@Flaky` and `@Muted` annotations now work with [JUnit 4](/docs/junit4-reference/#flaky).