Package org.junit.jupiter.api

Annotation Type TestInstance

  • @Target(TYPE)
@Retention(RUNTIME)
@Inherited
@Documented
@API(status=STABLE,
     since="5.0")
public @interface TestInstance
    @TestInstance is a type-level annotation that is used to configure the lifecycle of test instances for the annotated test class or test interface.

    If @TestInstance is not explicitly declared on a test class or on a test interface implemented by a test class, the lifecycle mode will implicitly default to PER_METHOD. Note, however, that an explicit lifecycle mode is inherited within a test class hierarchy. In addition, the default lifecycle mode may be overridden via the "junit.jupiter.testinstance.lifecycle.default" configuration parameter which can be supplied via the Launcher API, build tools (e.g., Gradle and Maven), a JVM system property, or the JUnit Platform configuration file (i.e., a file named junit-platform.properties in the root of the class path). Consult the User Guide for further information.

    Use Cases

    Setting the test instance lifecycle mode to PER_CLASS enables the following features.

    • Shared test instance state between test methods in a given test class as well as between non-static @BeforeAll and @AfterAll methods in the test class.
    • Declaration of non-static @BeforeAll and @AfterAll methods in @Nested test classes. Beginning with Java 16, @BeforeAll and @AfterAll methods may be declared as static in @Nested test classes with either lifecycle mode.
    • Declaration of @BeforeAll and @AfterAll on interface default methods.
    • Simplified declaration of non-static @BeforeAll and @AfterAll lifecycle methods as well as @MethodSource factory methods in test classes implemented with the Kotlin programming language.

    @TestInstance may also be used as a meta-annotation in order to create a custom composed annotation that inherits the semantics of @TestInstance.

    Parallel Execution

    Using the PER_CLASS lifecycle mode disables parallel execution unless the test class or test method is annotated with @Execution(CONCURRENT).

    Since:
    5.0
    See Also:
    @Nested, @Execution

    • Required Element Summary

      Required Elements 
      Modifier and Type Required Element Description
      TestInstance.Lifecycle value
      The test instance lifecycle mode to use.