https://github.com/gradle/develocity-testing-annotations

Common annotations for Develocity and Test Retry
https://github.com/gradle/develocity-testing-annotations

Last synced: about 1 month ago
JSON representation

Common annotations for Develocity and Test Retry

• Host: GitHub
• URL: https://github.com/gradle/develocity-testing-annotations
• Owner: gradle
• License: apache-2.0
• Created: 2022-08-29T13:48:56.000Z (about 2 years ago)
• Default Branch: main
• Last Pushed: 2024-05-22T20:16:07.000Z (6 months ago)
• Last Synced: 2024-05-22T21:37:31.677Z (6 months ago)
• Language: Java
• Homepage:
• Size: 167 KB
• Stars: 8
• Watchers: 22
• Forks: 6
• Open Issues: 4
• Metadata Files:
  • Readme: README.adoc
  • License: LICENSE

Awesome Lists containing this project

README

        
= Develocity Testing Annotations

Common annotations for https://gradle.com/[Develocity]'s

https://docs.gradle.com/enterprise/predictive-test-selection/[Predictive Test Selection] and

https://docs.gradle.com/enterprise/test-distribution/[Test Distribution] as well as

the standalone https://github.com/gradle/test-retry-gradle-plugin[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

[source,kotlin]

----

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

----

.Maven

[source,xml]

----

    com.gradle

    develocity-testing-annotations

    2.0.1

    test

----

== Configuration

=== Predictive Test Selection

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

For Gradle see https://docs.gradle.com/enterprise/predictive-test-selection/#must_run_annotation_matcher[Must Run Annotation Matcher] chapter for details.

[source,kotlin]

----

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 https://docs.gradle.com/enterprise/predictive-test-selection/#must_run_annotation_matcher_2[Must Run Annotation Matcher] chapter for details.

[source,xml]

----

  maven-surefire-plugin

  3.0.0-M7

  

    

      

        true

        

          

            com.gradle.develocity.testing.annotations.MustRun

          

        

      

    

  

----

=== Test Distribution

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

For Gradle see https://docs.gradle.com/enterprise/test-distribution/#gradle_executor_restrictions_annotation_matcher[Local-/remote-only annotation matcher] chapter for details.

[source,kotlin]

----

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 https://docs.gradle.com/enterprise/test-distribution/#maven_executor_restrictions_annotation_matcher[Local-/remote-only annotation matcher] chapter for details.

[source,xml]

----

  maven-surefire-plugin

  3.0.0-M7

  

    

      

        true

        

          

            com.gradle.develocity.testing.annotations.LocalOnly

          

        

        

          

            com.gradle.develocity.testing.annotations.RemoteOnly

          

        

      

    

  

----

=== Test Retry Plugin

See the https://github.com/gradle/test-retry-gradle-plugin#filtering[Filtering] chapter for details.

==== Opt-out mode

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

[source,kotlin]

----

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.

[source,kotlin]

----

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

[source,kotlin]

----

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.

[source,kotlin]

----

tasks.test {

    retry {

        filter {

            includeAnnotationClasses.add("com.gradle.develocity.testing.annotations.Retryable")

            includeAnnotationClasses.add("com.gradle.develocity.testing.annotations.ClassRetry")

        }

    }

}

----