Module org.junit.platform.commons
Package org.junit.platform.commons.annotation

Annotation Interface Testable

@Retention(RUNTIME) @Inherited @Documented @API(status=STABLE, since="1.0") public @interface Testable
@Testable is used to signal to IDEs and tooling vendors that the annotated or meta-annotated element is testable.

In this context, the term "testable" means that the annotated element (typically a method, field, or class) can be executed by a TestEngine as a test or test container on the JUnit Platform.

Motivation for @Testable

Some clients of the JUnit Platform, notably IDEs such as IntelliJ IDEA, operate only on sources for test discovery. Thus, they cannot use the full runtime discovery mechanism of the JUnit Platform since it relies on compiled classes. @Testable therefore serves as an alternative mechanism for IDEs to discover potential tests by analyzing the source code only.

Common Use Cases

@Testable will typically be used as a meta-annotation in order to create a custom composed annotation that inherits the semantics of @Testable. For example, the @Test and @TestFactory annotations in JUnit Jupiter are meta-annotated with @Testable.

For test programming models that do not rely on annotations, test classes, test methods, or test fields may be directly annotated with @Testable. Alternatively, if concrete test classes extend from a base class, the base class can be annotated with @Testable. Note that @Testable is an @Inherited annotation.

Requirements for IDEs and Tooling Vendors

  • If a top-level class, static nested class, or inner class is not annotated or meta-annotated with @Testable but contains a method or field that is annotated or meta-annotated with @Testable, the class must be considered to be a testable class.
  • If annotation hierarchies containing @Testable are present on classes, methods, or fields in compiled byte code (e.g., in JARs in the user's classpath), IDEs and tooling vendors must also take such annotation hierarchies into consideration when performing annotation processing for source code.

Restrictions for TestEngine Implementations

A TestEngine must not in any way perform discovery based on the presence of @Testable. In terms of discovery, the presence of @Testable should only be meaningful to clients such as IDEs and tooling vendors. A TestEngine implementation is therefore required to discover tests based on information specific to that test engine (e.g., annotations specific to that test engine).

Supported Target Elements

Since JUnit Platform version 1.7, @Testable may target any declaration element type. This includes the aforementioned method, field, and class elements.

Since:
1.0