Module org.junit.jupiter.api
Package org.junit.jupiter.api

Annotation Interface 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.

Since:
5.0
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    TestInstance.Lifecycle
    Enumeration of test instance lifecycle modes.

  • Required Element Summary

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