Develocity Testing Annotations

Common annotations for Develocity's Predictive Test Selection and Test Distribution as well as the standalone Test Retry Plugin.

Annotations

All annotations have an optional because attribute to explain why the annotation is present. The annotations are located in the com.gradle.develocity.testing.annotations package.

Predictive Test Selection

• @MustRun - indicates that the test must be run.

Test Distribution

• @LocalOnly - indicates that the test must be run locally.

• @RemoteOnly - indicates that the test must be run remotely.

Test Retry Plugin

• @Retryable - indicates that the test should be retried.

• @NonRetryable - indicates that the test must not be retried.

• @ClassRetry - indicates that the test class must be retried as a whole unit

Usage

Gradle

testImplementation("com.gradle:develocity-testing-annotations:2.0.1")

Maven

<dependency>
    <groupId>com.gradle</groupId>
    <artifactId>develocity-testing-annotations</artifactId>
    <version>2.0.1</version>
    <scope>test</scope>
</dependency>

Configuration

Predictive Test Selection

The Develocity Gradle plugin version 3.16 or higher has built-in support for the @MustRun annotation.

For Gradle see Must Run Annotation Matcher chapter for details.

tasks.test {
    useJUnitPlatform()
    predictiveSelection {
        enabled.set(true)
        mustRun {
            includeAnnotationClasses.add("com.gradle.develocity.testing.annotations.MustRun")
        }
    }
}

The Develocity Maven extension version 1.20 or higher has built-in support for the @MustRun annotation.

For Maven see the Must Run Annotation Matcher chapter for details.

<plugin>
  <artifactId>maven-surefire-plugin</artifactId>
  <version>3.0.0-M7</version>
  <configuration>
    <properties>
      <predictiveSelection>
        <enabled>true</enabled>
        <mustRun>
          <includeAnnotationClasses>
            <include>com.gradle.develocity.testing.annotations.MustRun</include>
          </includeAnnotationClasses>
        </mustRun>
      </predictiveSelection>
    </properties>
  </configuration>
</plugin>

Test Distribution

The Develocity Gradle plugin version 3.16 or higher has built-in support for these annotations.

For Gradle see Local-/remote-only annotation matcher chapter for details.

tasks.test {
    distribution {
        enabled.set(true)
        localOnly {
            includeAnnotationClasses.addAll("com.gradle.develocity.testing.annotations.LocalOnly")
        }
        remoteOnly {
            includeAnnotationClasses.addAll("com.gradle.develocity.testing.annotations.RemoteOnly")
        }
    }
}

The Develocity Maven extension version 1.20 or higher has built-in support for these annotations.

For Maven see the Local-/remote-only annotation matcher chapter for details.

<plugin>
  <artifactId>maven-surefire-plugin</artifactId>
  <version>3.0.0-M7</version>
  <configuration>
    <properties>
      <distribution>
        <enabled>true</enabled>
        <localOnly>
          <includeAnnotationClasses>
            <include>com.gradle.develocity.testing.annotations.LocalOnly</include>
          </includeAnnotationClasses>
        </localOnly>
        <remoteOnly>
          <includeAnnotationClasses>
            <include>com.gradle.develocity.testing.annotations.RemoteOnly</include>
          </includeAnnotationClasses>
        </remoteOnly>
      </distribution>
    </properties>
  </configuration>
</plugin>

Test Retry Plugin

See the Filtering chapter for details.

Opt-out mode

With this configuration every class not annotated with @NonRetryable will be retried if it fails.

tasks.test {
    retry {
        filter {
            excludeAnnotationClasses.add("com.gradle.develocity.testing.annotations.NonRetryable")
        }
    }
}

Opt-in mode

With this configuration only the classes annotated with @Retryable will be retried if they fail.

tasks.test {
    retry {
        filter {
            includeAnnotationClasses.add("com.gradle.develocity.testing.annotations.Retryable")
        }
    }
}

Retry on class-level (since 1.1)

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, as this annotation does not imply @Retryable by default.

The Test Retry Gradle plugin version 1.5.0 or higher has built-in support for @ClassRetry.

tasks.test {
    retry {
        classRetry {
            includeAnnotationClasses.add("com.gradle.develocity.testing.annotations.ClassRetry")
        }
    }
}

Combining with Opt-in mode

You can also combine configure @ClassRetry act as opt-in marker.

tasks.test {
    retry {
        filter {
            includeAnnotationClasses.add("com.gradle.develocity.testing.annotations.Retryable")
            includeAnnotationClasses.add("com.gradle.develocity.testing.annotations.ClassRetry")
        }
    }
}