Gradle project plugins for building Allure reports for JBehave 4/5, JUnit 4/5/Platform, Karate, ScalaTest, TestNG, Cucumber JVM 4-7, and Spock tests.

allure-gradle plugin implements Allure data collecting (e.g. Test` tasks), and data reporting (both individual and aggregate reports).

Data collecting and reporting are split to different Gradle plugins, so you could apply the ones you need.

Note:

• allure-gradle 2.9+ requires Gradle 5.0+
• allure-gradle 2.11+ requires Gradle 6.0+
• allure-gradle 3.0+ requires Gradle 8.11+

The minimal configuration is as follows. It would configure test tasks to collect Allure results and add allureReport and allureServe tasks for report inspection.

Groovy DSL:

plugins {
    id'io.qameta.allure' version '<latest>'
}

repositories {
    // Repository is needed for allure-java adapter dependencies.
    // The default Allure 3 report runtime is provisioned automatically.
    mavenCentral()
}

Kotlin DSL:

plugins {
    id("io.qameta.allure") version "<latest>"
}

repositories {
    // Repository is needed for allure-java adapter dependencies.
    // The default Allure 3 report runtime is provisioned automatically.
    mavenCentral()
}

io.qameta.allure is a shortcut for io.qameta.allure-adapter + io.qameta.allure-report, so you could apply the plugins you need.

Groovy DSL:

allure {
    version = "3.4.1"
}

Kotlin DSL:

allure {
    version = "3.4.1"
}

allure.version selects the report runtime family:

• 3.x uses the default Allure 3 runtime provisioned by downloadAllure
• 2.x switches to the Allure 2 allure-commandline zip runtime

To build a report, and browse it use the following command:

./gradlew allureServe

Note: by default, allureServe does not execute tests, so if you want to execute the relevant tests and build report, use the following:

./gradlew allureReport --depends-on-tests

To build an aggregate report, and browse it, apply io.qameta.allure-aggregate-report plugin and use the following command:

./gradlew allureAggregateServe

If you need a report only, please use allureReport and allureAggregateReport.

By default, allureAggregate* aggregates data from the current project and its subprojects. However, you need to apply io.qameta.allure-adapter plugin to the relevant subprojects, so they provide Allure results.

Data collecting is implemented via io.qameta.allure-adapter Gradle plugin.

The values in the sample below are the defaults. The sample uses Kotlin DSL. In Groovy DSL you could use allureJavaVersion = "2.33.0", however, that is the only difference.

allure {
    version.set("3.4.1")
    adapter {
        // Configure version for io.qameta.allure:allure-* adapters
        // It defaults to the latest supported allure-java release
        allureJavaVersion.set("2.33.0")
        aspectjVersion.set("1.9.24")

        // Customize environment variables for launching Allure
        environment.put("JAVA_HOME", "/path/to/java_home")

        autoconfigure.set(true)
        autoconfigureListeners.set(true)
        aspectjWeaver.set(true)

        // By default, categories.json is detected in src/test/resources/../categories.json,
        // However, it would be better to put the file in a well-known location and configure it explicitly
        categoriesFile.set(layout.projectDirectory.file("config/allure/categories.json"))

        // Customize where adapter-managed test tasks write raw Allure results
        resultsDir.set(layout.buildDirectory.dir("custom-allure-results"))
        frameworks {
            junit4 {
                adapterVersion.set("...")
                enabled.set(true)
            }
            junit5 {
                // Defaults to allureJavaVersion
                adapterVersion.set("...")
                enabled.set(true)
                // Enables allure-junit5 default test listeners via META-INF/services/...
                autoconfigureListeners.set(true)
            }
            junitPlatform {
                autoconfigureListeners.set(true)
            }
            testng {
                adapterVersion.set("...")
                enabled.set(true)
                autoconfigureListeners.set(true)
            }
            jbehave
            jbehave5
            karate {
                autoconfigureListeners.set(true)
            }
            scalatest
            spock
            cucumber4Jvm
            cucumber5Jvm
            cucumber6Jvm
            cucumber7Jvm
        }
    }
}

By default, allure-gradle would detect all of them and apply all the listeners yielding 3 reports. If you need only one or two, specify the required ones via frameworks {...} block.

If you need to change where adapter-managed test tasks write raw results, configure allure.adapter.resultsDir:

allure {
    adapter {
        resultsDir.set(layout.buildDirectory.dir("custom-allure-results"))
    }
}

You can also add externally produced or additional result folders via allureRawResultElements Gradle configuration.

For report-only projects that do not apply io.qameta.allure-adapter, configure the report input instead:

dependencies {
    allureReport(files(layout.buildDirectory.dir("custom-allure-results")))
}

plugins {
    id("io.qameta.allure-adapter-base")
}

dependencies {
    allureRawResultElements(files(layout.buildDirectory.dir("custom-allure-results")))
    // or
    allureRawResultElements(files("$buildDir/custom-allure-results"))
}

// If the results are built with a task, you might want adding a dependency so aggregate report
// knows which tasks to run before building the report
allureRawResultElements.outgoing.artifact(file("...")) {
    builtBy(customTask)
}

allure-java comes with a set of default listeners for JUnit5, JUnit Platform, Karate, and TestNG. However, you might want to disable them and use your own ones.

Here's how you disable default listeners:

allure.adapter.frameworks.junit5.autoconfigureListeners.set(false)

An alternative syntax is as follows:

allure {
    adapter {
        frameworks {
            // Note: every time you mention an adapter, it is added to the classpath,
            // so refrain from mentioning unused adapters here
            junit5 {
                // Disable allure-junit5 default test listeners
                autoconfigureListeners.set(false)
            }
            testng {
                // Disable allure-testng default test listeners
                autoconfigureListeners.set(false)
            }
        }
    }
}

Suppose you have a couple of modules /module1/build.gradle.kts, /module2/build.gradle.kts that collect raw results for Allure:

// Each submodule
plugin {
    `java-library`
    id("io.qameta.allure-adapter")
}

allure {
    adapter {
        frameworks {
            junit5
        }
    }
}

// Each Test task will write raw data for Allure automatically

Here's how you can aggregate that in their parent project (e.g. root project):

/build.gradle.kts

plugin {
    id("io.qameta.allure-aggregate-report")
}

// Add repositories for adapter/test dependencies if the aggregated projects need them.
repositories {
    mavenCentral()
}

Browse report:

./gradlew allureAggregateServe

By default io.qameta.allure-aggregate-report would aggregate results from allprojects (==current project + its subprojects), however, you can configure the set of modules as follows:

// By default, aggregate-report aggregates allprojects (current + subprojects)
// So we want to exclude module3 since it has no data for Allure
configurations.allureAggregateReport.dependencies.remove(
        project.dependencies.register(project(":module3"))
)

// Removing the default allprojects:
configurations.allureAggregateReport.dependencies.clear()

// Adding a custom dependency
dependencies {
    allureAggregateReport(project(":module3"))
}

Report generation is implemented via io.qameta.allure-report Gradle plugin, so if you need reports, apply the plugin as follows:

plugins {
    id("io.qameta.allure-report")
}

By default, the report is produced into Gradle's default reporting folder under task.name subfolder:

$buildDir/reports/allure-report/allureReport $buildDir/reports/allure-report/allureAggregateReport

You could adjust the default location as follows:

plugins {
    id("io.qameta.allure-report") // the plugin is packaged with Gradle by default
}

// See https://docs.gradle.org/current/dsl/org.gradle.api.reporting.ReportingExtension.html
// Extension is provided via Gradle's `reporting-base` plugin
reporting {
    baseDir = "$buildDir/reports"
}

allure {
    report {
        // There might be several tasks producing the report, so the property
        // configures a base directory for all the reports
        // Each task creates its own subfolder there
        reportDir.set(project.reporting.baseDirectory.dir("allure-report"))

        // Enable single-file report generation.
        singleFile = true
    }
}

To enable it for a single invocation without changing the DSL, run ./gradlew allureReport --single-file=true.

By default, allureReport task will NOT execute tests. This enables trying new categories.json faster, however, if you need to see the latest results, the following might help:

• Execute tests separately: ./gradlew test
• Use --depends-on-tests as follows (the option should come after the task name): ./gradlew allureReport --depends-on-tests
• Configure allure.report.dependsOnTest.set(true)

allure {
    report {
        // By default, allureReport will NOT execute tests
        // If the tests are fast (e.g. UP-TO-DATE or FROM-CACHE),
        // then you might want configure dependsOnTests.set(true) so you always
        // get the latest report from allureReport
        dependsOnTests.set(false)
    }
}

Allure download is handled with io.qameta.allure-download plugin which adds downloadAllure task. Typically, applying io.qameta.allure-report is enough, however, you could use io.qameta.allure-download if you do not need reporting and you need just a fresh allure-commandline binary.

By default allure-gradle provisions Allure 3. The Allure 2 allure-commandline flow is available only when allure.version is set to a 2.x release.

For 2.x, allure-commandline is downloaded from Sonatype OSSRH (also known as Maven Central).

The plugin receives allure-commandline via io.qameta.allure:allure-commandline:$version@zip dependency.

If you have a customized version, you could configure it as follows:

allure {
    // Legacy runtime selection.
    version.set("2.38.1")

    commandline {
        // The following patterns are supported: `[group]`, `[module]`, `[version]`, `[extension]`
        // The patterns can appear severs times if you need
        // By default, downloadUrlPattern is NOT set.
        downloadUrlPattern.set("https://server/path/[group]/[module]-[version].[extension]")

        // groupId for allure-commandline
        group.set("io.qameta.allure")
        // module for allure-commandline
        module.set("allure-commandline")
        // extension for allure-commandline
        extension.set("zip")
    }
}

Note: if you configure downloadUrlPattern, then io.qameta.allure-download plugin configures an extra ivy repository with the provided URL, and it uses custom.io.qameta.allure:allure-commandline:... coordinates to identify custom distribution is needed.

If you use Gradle 6.2+, then the custom repository is configured with exclusive content filtering which means the repository would be used exclusively for custom.io.qameta.allure:allure-commandline.

If you use Gradle 5.1+, then the repository would be configured with regular filtering, so it would be slightly less secure and slightly less efficient.

allure-commandline is resolved via allureCommandline configuration, so you could configure local file as follows.

Remember: NEVER use relative paths in your build files since "current directory" does not exist in a multi-threaded project execution (see https://youtrack.jetbrains.com/issue/IDEA-265203#focus=Comments-27-4795223.0-0).

dependencies {
    // allureCommandline must resolve to a single zip file
    // You could use regular Gradle syntax to specify the dependency
    allureCommandline(files("/path/to/allure-commandline.zip"))
}

Most builds should use one of the end-user plugins:

• io.qameta.allure-adapter for optional raw-result collection and adapter autoconfiguration
• io.qameta.allure-report for report generation from configured raw results
• io.qameta.allure-aggregate-report for multi-project report generation

The base and download plugins are implementation building blocks for those public workflows.

Extensions:

• io.qameta.allure.gradle.base.AllureExtension

  allure extension for project

Extensions:

• io.qameta.allure.gradle.adapter.AllureAdapterExtension

  adapter extension for allure

Configurations:

• allureRawResultElements

  A consumable configuration that exposes the collect raw data for building the report

Tasks:

• copyCategories: io.qameta.allure.gradle.adapter.tasks.CopyCategories

  Copies categories.json to the raw results folders. See allure-framework/allure2#1236

Configures automatic collectint of raw data from test tasks, adds allure-java adapters to the classpath.

Configurations:

• allureAspectjWeaverAgent

  A configuration to declare AspectJ agent jar for data collecting

Provisions the selected report runtime into build/allure/commandline.

Extensions:

• io.qameta.allure.gradle.download.AllureCommandlineExtension

  commandline extension for Allure 2 runtime customization

Configurations:

• allureCommandline

  A configuration to resolve the Allure 2 allure-commandline zip

• allureNodeDistribution

  Internal configuration used for the provisioned Node.js runtime when allure.version is 3.x

• allure3Package

  Optional override for supplying a local Allure 3 package archive in tests or custom setups

Tasks:

• downloadAllure: io.qameta.allure.gradle.download.tasks.DownloadAllure

  Retrieves and assembles the selected report runtime

Applies reporting-base plugin and adds allure.report extension.

Extensions:

• io.qameta.allure.gradle.report.AllureReportExtension

  report extension for allure

Builds Allure report for the current project.

Configurations:

• allureReport

  Note: prefer exposing raw results via allureRawResultElements configuration rather than declaring them in allureReport configuration.

Tasks:

• allureReport: io.qameta.allure.gradle.report.tasks.AllureReport

  Builds Allure report for the current project

• allureServe: io.qameta.allure.gradle.report.tasks.AllureServe

  Launches a web server for browsing Allure report

Builds Allure aggregate report.

Configurations:

• allureAggregateReport

  A configuration for declaring projects to aggregate the results from. Each project exposes its raw results via allureRawResultElements configuration.

Tasks:

• allureAggregateReport: io.qameta.allure.gradle.report.tasks.AllureReport

  Builds Allure aggregate report

• allureAggregateServe: io.qameta.allure.gradle.report.tasks.AllureServe

  Launches a web server for browsing Allure aggregate report

The 3.x line targets modern Gradle and JVMs and aligns Spock with JUnit Platform:

• Minimal supported Gradle version: 8.11 (tested with 8.11.1, 8.14.3, 9.0.0)
• Java 17 and 21 are supported
• Spock 2 (Groovy 4) runs on JUnit Platform and should use the allure-spock2 adapter

When using Spock 2.x, ensure:

• JUnit Platform is enabled for your test task:

  Groovy DSL:

  test {
      useJUnitPlatform()
  }

• The Allure adapter for Spock 2 is on the classpath (the plugin auto-configures it when Spock is detected):

  io.qameta.allure:allure-spock2:<allureJavaVersion>

• If your environment is missing JUnit Platform at test runtime, add the launcher explicitly (some setups require this at runtime):

  dependencies {
      testRuntimeOnly "org.junit.platform:junit-platform-launcher"
  }

Example tests across engines now produce a single Allure attachment for consistency. For Spock 2:

import io.qameta.allure.Attachment
import io.qameta.allure.Step
import spock.lang.Specification

class SpockTest extends Specification {
    def "example"() {
        when:
        stepMethod()
        then:
        true
    }

    @Step("step")
    void stepMethod() { attachment() }

    @Attachment(value = "attachment", type = "text/plain")
    String attachment() { "<p>HELLO</p>" }
}

This mirrors the JUnit 4 sample and ensures Allure results contain one *attachment file per executed test across frameworks.