Allure plugin for Gradle

Gradle projects plugins for building Allure reports for TestNG, JUnit4, JUnit5, Cucumber JVM, 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 downloading allure-commandline for building the report
    mavenCentral()
}

Kotlin DSL:

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

repositories {
    // Repository is needed for downloading allure-commandline for building the report
    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 = "2.34.1"
}

Kotlin DSL:

allure {
    version = "2.34.1"
}

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

allure {
    version.set("2.34.1")
    adapter {
        // Configure version for io.qameta.allure:allure-* adapters
        // It defaults to allure.version
        allureJavaVersion.set("2.29.1")
        aspectjVersion.set("1.9.22.1")

        // 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"))
        frameworks {
            junit5 {
                // Defaults to allureJavaVersion
                adapterVersion.set("...")
                enabled.set(true)
                // Enables allure-junit4 default test listeners via META-INF/services/...
                autoconfigureListeners.set(true)
            }
            junit4 {
                // same as junit5
            }
            testng {
                // same as junit5
            }
            spock
            cucumberJvm
            // Alternative syntax: cucumberJvm(2) {...}
            cucumber2Jvm
            cucumber3Jvm
            cucumber4Jvm
            cucumber5Jvm
            cucumber6Jvm
        }
    }
}

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

You could add a folder with custom results via allureRawResultElements Gradle configuration.

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 JUnit4, JUnit5, 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)
            }
        }
    }
}

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

// allure-aggregate-report requires allure-commandline, so we need a repository here
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 generation to open without serving.
        singleFile = true
    }
}

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-commandline download

Allure download is handled with io.qameta.allure-download plugin which adds allureDownload 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-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 {
    // This configures the common Allure version, so it is used for commandline as well
    version.set("2.34.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

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

Downloads and unpacks allure-commandline

Extensions:

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

  commandline extension for allure

Configurations:

• allureCommandline

  A configuration to resolve allure-commandline zip

Tasks:

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

  Retrieves and unpacks allure-commandline

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.0.0)
• 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.