Gradle projects plugins for building Allure reports for TestNG, JUnit4, JUnit5, Cucumber JVM, and Spock tests.
allure-gradle
plugin implements Allure data collecting (e.g. Test` tasks), and data reporting (both individual and aggregate reports).
Data colecting 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+
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.
Groovy DSL:
allure {
value = "2.30.0"
}
Kotlin DSL:
allure {
value.set("2.30.0")
}
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.19.0"
, however, that is the only difference.
allure {
version.set("2.30.0")
adapter {
// Configure version for io.qameta.allure:allure-* adapters
// It defaults to allure.version
allureJavaVersion.set("2.28.0")
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
}
}
}
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.
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)
}
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)
}
}
}
}
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.create(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"))
}
}
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 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.30.0")
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"))
}
Extensions:
-
io.qameta.allure.gradle.base.AllureExtension
allure
extension forproject
Extensions:
-
io.qameta.allure.gradle.adapter.AllureAdapterExtension
adapter
extension forallure
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
Downloads and unpacks allure-commandline
Extensions:
-
io.qameta.allure.gradle.download.AllureCommandlineExtension
commandline
extension forallure
Configurations:
-
allureCommandline
A configuration to resolve
allure-commandline
zip
Tasks:
-
allureDownload: io.qameta.allure.gradle.download.tasks.DownloadAllure
Retrieves and unpacks
allure-commandline
Applies reporting-base
plugin and adds allure.report
extension.
Extensions:
-
io.qameta.allure.gradle.report.AllureReportExtension
report
extension forallure
Builds Allure report for the current project.
Configurations:
-
allureReport
Note: prefer exposing raw results via
allureRawResultElements
configuration rather than declaring them inallureReport
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