A Gradle plugin that augments Gradle’s built-in test task with the ability to retry tests that have failed.
The plugin causes failed tests to be retried within the same task. After executing all tests, any failed tests are retried. The process repeats with tests that continue to fail until the maximum specified number of retries has been attempted, or there are no more failing tests.
By default, all failed tests passing on retry prevents the test task from failing. This mode prevents flaky tests from causing build failure. This setting can be changed so that flaky tests cause build failure, which can be used to identify flaky tests.
When something goes badly wrong and all tests start failing, it can be preferable to not keep retrying tests. This can happen for example if a disk fills up or a required database is not available. To avoid this, the plugin can be configured to stop retrying after a certain number of total test failures.
NOTE: Retrying tests alone is not a viable flaky test mitigation strategy. This plugin should only be used alongside processes for tracking and fixing discovered flaky tests.
Apply the plugin using one of the two methods described on the Gradle Plugin Portal, where the plugin is listed as org.gradle.test-retry. It is compatible with Gradle 5.0 and later versions.
By default, retrying is not enabled.
Retrying is configured per test task via the retry extension added to each task by the plugin.
test {
retry {
maxRetries = 2
maxFailures = 20
failOnPassedAfterRetry = true
failOnSkippedAfterRetry = true
}
}test {
retry {
maxRetries.set(2)
maxFailures.set(20)
failOnPassedAfterRetry.set(true)
failOnSkippedAfterRetry.set(true)
}
}You may find that local developer builds do not benefit much from retry behaviour, particularly when those tests are invoked via your IDE. In that case we recommend enabling retry only for CI builds.
boolean isCiServer = System.getenv().containsKey("CI")
test {
retry {
if (isCiServer) {
maxRetries = 2
maxFailures = 20
}
failOnPassedAfterRetry = true
failOnSkippedAfterRetry = true
}
}The retry extension is of the following type:
package org.gradle.testretry;
import org.gradle.api.Action;
import org.gradle.api.provider.Property;
import org.gradle.api.provider.SetProperty;
import org.gradle.api.tasks.testing.Test;
/**
* Allows configuring test retry mechanics.
* <p>
* This extension is added with the name 'retry' to all {@link Test} tasks.
*/
public interface TestRetryTaskExtension {
/**
* The name of the extension added to each test task.
*/
String NAME = "retry";
/**
* Whether tests that initially fail and then pass on retry should fail the task.
* <p>
* This setting defaults to {@code false},
* which results in the task not failing if all tests pass on retry.
* <p>
* This setting has no effect if {@link Test#getIgnoreFailures()} is set to true.
*
* @return whether tests that initially fails and then pass on retry should fail the task
*/
Property<Boolean> getFailOnPassedAfterRetry();
/**
* Whether tests that initially fail and then are skipped on retry should fail the task.
* <p>
* This setting defaults to {@code true} (for backward compatibility),
* which results in the task failing if any of tests skip on retry.
* <p>
* This setting has no effect if {@link Test#getIgnoreFailures()} is set to true.
*
* @return whether tests that initially fails and then are skipped on retry should fail the task
*/
Property<Boolean> getFailOnSkippedAfterRetry();
/**
* The maximum number of times to retry an individual test.
* <p>
* This setting defaults to {@code 0}, which results in no retries.
* Any value less than 1 disables retrying.
*
* @return the maximum number of times to retry an individual test
*/
Property<Integer> getMaxRetries();
/**
* The maximum number of test failures that are allowed before retrying is disabled.
* <p>
* The count applies to each round of test execution.
* For example, if maxFailures is 5 and 4 tests initially fail and then 3 again on retry,
* this will not be considered too many failures and retrying will continue (if maxRetries {@literal >} 1).
* If 5 or more tests were to fail initially then no retry would be attempted.
* <p>
* This setting defaults to {@code 0}, which results in no limit.
* Any value less than 1 results in no limit.
*
* @return the maximum number of test failures that are allowed before retrying is disabled
*/
Property<Integer> getMaxFailures();
/**
* The filter for specifying which tests may be retried.
*/
Filter getFilter();
/**
* The filter for specifying which tests may be retried.
*/
void filter(Action<? super Filter> action);
/**
* A filter for specifying which tests may be retried.
*
* By default, all tests are eligible for retrying.
*/
interface Filter {
/**
* The patterns used to include tests based on their class name.
*
* The pattern string matches against qualified class names.
* It may contain '*' characters, which match zero or more of any character.
*
* A class name only has to match one pattern to be included.
*
* If no patterns are specified, all classes (that also meet other configured filters) will be included.
*/
SetProperty<String> getIncludeClasses();
/**
* The patterns used to include tests based on their class level annotations.
*
* The pattern string matches against the qualified class names of a test class's annotations.
* It may contain '*' characters, which match zero or more of any character.
*
* A class need only have one annotation matching any of the patterns to be included.
*
* Annotations present on super classes that are {@code @Inherited} are considered when inspecting subclasses.
*
* If no patterns are specified, all classes (that also meet other configured filters) will be included.
*/
SetProperty<String> getIncludeAnnotationClasses();
/**
* The patterns used to exclude tests based on their class name.
*
* The pattern string matches against qualified class names.
* It may contain '*' characters, which match zero or more of any character.
*
* A class name only has to match one pattern to be excluded.
*
* If no patterns are specified, all classes (that also meet other configured filters) will be included.
*/
SetProperty<String> getExcludeClasses();
/**
* The patterns used to exclude tests based on their class level annotations.
*
* The pattern string matches against the qualified class names of a test class's annotations.
* It may contain '*' characters, which match zero or more of any character.
*
* A class need only have one annotation matching any of the patterns to be excluded.
*
* Annotations present on super classes that are {@code @Inherited} are considered when inspecting subclasses.
*
* If no patterns are specified, all classes (that also meet other configured filters) will be included.
*/
SetProperty<String> getExcludeAnnotationClasses();
}
/**
* The set of criteria specifying which test classes must be retried as a whole unit
* if retries are enabled and the test class passes the configured filter.
*/
ClassRetryCriteria getClassRetry();
/**
* The set of criteria specifying which test classes must be retried as a whole unit
* if retries are enabled and the test class passes the configured filter.
*/
void classRetry(Action<? super ClassRetryCriteria> action);
/**
* The set of criteria specifying which test classes must be retried as a whole unit
* if retries are enabled and the test class passes the configured filter.
*/
interface ClassRetryCriteria {
/**
* The patterns used to include tests based on their class name.
*
* The pattern string matches against qualified class names.
* It may contain '*' characters, which match zero or more of any character.
*
* A class name only has to match one pattern to be included.
*
* If no patterns are specified, all classes (that also meet other configured filters) will be included.
*/
SetProperty<String> getIncludeClasses();
/**
* The patterns used to include tests based on their class level annotations.
*
* The pattern string matches against the qualified class names of a test class's annotations.
* It may contain '*' characters, which match zero or more of any character.
*
* A class need only have one annotation matching any of the patterns to be included.
*
* Annotations present on super classes that are {@code @Inherited} are considered when inspecting subclasses.
*
* If no patterns are specified, all classes (that also meet other configured filters) will be included.
*/
SetProperty<String> getIncludeAnnotationClasses();
}
}Other versions are likely to work as well, but are not tested.
| Framework | Version Tested |
|---|---|
JUnit4 |
4.13.2 |
JUnit5 |
5.9.2 |
Spock |
2.3-groovy-3.0 |
TestNG |
7.5 |
In a few cases, test selection for testing frameworks limits the granularity at which tests can be retried.
In each case, this plugin retries at worst at method level.
For JUnit5 @ParameterizedTest, TestNG @Test(dataProvider = "…"),
and Spock @Unroll tests the plugin will retry the entire method with all parameters including those that initially passed.
The plugin supports retrying Spock @Stepwise tests and TestNG @Test(dependsOn = { … }) tests.
-
Upstream tests (those that the failed test depends on) are run because a flaky test may depend on state from the prior execution of an upstream test.
-
Downstream tests are run because a flaky test causes any downstream tests to be skipped in the initial test run.
Some projects may use test tasks with a custom TestFramework to execute tests.
If this is the case, the plugin disables retries and emits the following warning:
> Task :unsupportedTestTaskUnitTest
Test retry requested for task :unsupportedTestTaskUnitTest with unsupported test framework CustomTestFramework - failing tests will not be retriedTo avoid this warning, we can disable retries for the unsupported test task with:
test.named('unsupportedTestTaskUnitTest') {
retry {
maxRetries = 0
}
}tasks.named<Test>("unsupportedTestTaskUnitTest") {
retry {
maxRetries.set(0)
}
}By default, all tests are eligible for retrying.
The filter component of the test retry extension can be used to control which tests should be retried and which should not.
The decision to retry a test or not is based on the tests reported class name, regardless of the name of the test case or method. The annotations present or not on this class can also be used as the criteria.
test {
retry {
maxRetries = 3
filter {
// filter by qualified class name (* matches zero or more of any character)
includeClasses.add("*IntegrationTest")
excludeClasses.add("*DatabaseTest")
// filter by class level annotations
// Note: @Inherited annotations are respected
includeAnnotationClasses.add("*Retryable")
excludeAnnotationClasses.add("*NonRetryable")
}
}
}By default, individual tests are retried. The classRetry component of the test retry extension can be used to control which test classes must be retried as a whole unit. Test classes still have to pass the configured filter.
test {
retry {
maxRetries = 3
classRetry {
// configure by qualified class name (* matches zero or more of any character)
includeClasses.add("*StepWiseIntegrationTest")
// configure by class level annotations
// Note: @Inherited annotations are respected
includeAnnotationClasses("Stepwise")
}
}
}Each execution of a test is discretely reported in Gradle-generated XML and HTML reports.
Similar to the XML and HTML reports, the console log will also report each individual test execution. Before retrying a failed test, Gradle will execute the whole test suite of the test task. This means that all executions of the same test may not be grouped in the console log.
Gradle build scans (--scan option) report discrete test executions as "Execution [N of total]" and will mark a test with both a failed and then a passed outcome as flaky.
Flaky tests can also be visualized across many builds using the Develocity Tests Dashboard.
The plugin has been tested with IDEA, Eclipse IDE and Netbeans.
When delegating test execution to Gradle, each execution is reported discretely as for the test reports. Running tests without Gradle delegation causes tests to not be retried.
When delegating test execution to Gradle, each execution is reported discretely as for the test reports. Running tests without Gradle delegation causes tests to not be retried.
Flaky tests (tests being executed multiple times but with different results) are detected by TeamCity and marked as flaky. TeamCity lists each test that was executed and how often it was run in the build.
By default, TeamCity will fail your build if at least one test fails.
When using failOnPassedAfterRetry = false (ie. the default for this plugin), this failure condition should be disabled.
