Allure plugin for Gradle

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.

Basic usage

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.

Configuring Allure version

Groovy DSL:

allure {
    version = "3.9.0"
}

Kotlin DSL:

allure {
    version = "3.9.0"
}

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

Building Allure report

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.

Customizing data collecting

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.35.2", however, that is the only difference.

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

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

        autoconfigure.set(true)
        autoconfigureListeners.set(true)
        autoconfigureJavadocDescriptions.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)
            }
            assertj
            jbehave
            jbehave5
            karate {
                autoconfigureListeners.set(true)
            }
            scalatest
            spock
            cucumber4Jvm
            cucumber5Jvm
            cucumber6Jvm
            cucumber7Jvm
        }
    }
}

What if I have both JUnit5, JUnit4, and CucumberJVM on the classpath?

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.

Adding custom results for reporting

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)
}

Using custom JUnit5 listeners instead of the default ones

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)
            }
        }
    }
}

Using custom Javadoc description processing

allure-gradle adds io.qameta.allure:allure-descriptions-javadoc to Java annotation processor configurations by default. Disable it when you configure description annotation processing manually:

allure.adapter.autoconfigureJavadocDescriptions.set(false)

Report generation

Aggregating results from multiple projects

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"))
}

Customizing report folders

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.

For Allure 3, you can provide a custom config file, for example to configure environments, custom grouping, report name, or theme:

allure {
    report {
        configFile.set(layout.projectDirectory.file("allurerc.mjs"))
    }
}

To use a custom Allure 3 config file for a single invocation, run ./gradlew allureReport --config-file=allurerc.mjs. When configFile is set, Allure 3-specific options such as singleFile, environments, grouping, report name, and theme should be configured in that file. The Gradle task still passes its reportDir as --output. In this mode, Gradle's singleFile property and the --single-file task option are ignored for Allure 3.

Running tests before building the report

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)
    }
}

Customizing Allure 2 allure-commandline download

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

Using local allure-commandline binary

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"))
}

Technical details

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.

io.qameta.allure-base plugin

Extensions:

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

  allure extension for project

io.qameta.allure-adapter-base plugin

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

io.qameta.allure-adapter plugin

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

io.qameta.allure-download plugin

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

io.qameta.allure-report-base plugin

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

Extensions:

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

  report extension for allure

io.qameta.allure-report plugin

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

io.qameta.allure-aggregate-report plugin

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

Compatibility and Spock 2 notes

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.5.1)
• Java 17 and 21 are supported
• Spock 2 (Groovy 4) runs on JUnit Platform and should use the allure-spock2 adapter

Using Spock 2 with Allure

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"
  }

Consistent attachments in examples

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.