Annotations

JUnit Jupiter supports the following annotations for configuring tests and extending the framework.

Unless otherwise stated, all core annotations are located in the org.junit.jupiter.api package in the junit-jupiter-api module.

@Test : Denotes that a method is a test method. Unlike JUnit 4’s @Test annotation, this annotation does not declare any attributes, since test extensions in JUnit Jupiter operate based on their own dedicated annotations. Such methods are inherited unless they are overridden.

@ParameterizedTest : Denotes that a method is a parameterized test. Such methods are inherited unless they are overridden.

@RepeatedTest : Denotes that a method is a test template for a repeated test. Such methods are inherited unless they are overridden.

@TestFactory : Denotes that a method is a test factory for dynamic tests. Such methods are inherited unless they are overridden.

@TestTemplate : Denotes that a method is a template for a test case designed to be invoked multiple times depending on the number of invocation contexts returned by the registered providers. Such methods are inherited unless they are overridden.

@TestClassOrder : Used to configure the test class execution order for @Nested test classes in the annotated test class. Such annotations are inherited.

@TestMethodOrder : Used to configure the test method execution order for the annotated test class; similar to JUnit 4’s @FixMethodOrder. Such annotations are inherited.

@TestInstance : Used to configure the test instance lifecycle for the annotated test class. Such annotations are inherited.

@DisplayName : Declares a custom display name for the test class or test method. Such annotations are not inherited.

@DisplayNameGeneration : Declares a custom display name generator for the test class. Such annotations are inherited.

@BeforeEach : Denotes that the annotated method should be executed before each @Test, @RepeatedTest, @ParameterizedTest, or @TestFactory method in the current class; analogous to JUnit 4’s @Before. Such methods are inherited unless they are overridden.

@AfterEach : Denotes that the annotated method should be executed after each @Test, @RepeatedTest, @ParameterizedTest, or @TestFactory method in the current class; analogous to JUnit 4’s @After. Such methods are inherited unless they are overridden.

@BeforeAll : Denotes that the annotated method should be executed before all @Test, @RepeatedTest, @ParameterizedTest, and @TestFactory methods in the current top-level or @Nested test class; analogous to JUnit 4’s @BeforeClass. Such methods are inherited unless they are overridden and must be static unless the “per-class” test instance lifecycle is used.

@AfterAll : Denotes that the annotated method should be executed after all @Test, @RepeatedTest, @ParameterizedTest, and @TestFactory methods in the current top-level or @Nested test class; analogous to JUnit 4’s @AfterClass. Such methods are inherited unless they are overridden and must be static unless the “per-class” test instance lifecycle is used.

@ParameterizedClass : Denotes that the annotated class is a parameterized class. Such annotations are inherited.

@BeforeParameterizedClassInvocation : Denotes that the annotated method should be executed once before each invocation of a parameterized class. Such methods are inherited unless they are overridden.

@AfterParameterizedClassInvocation : Denotes that the annotated method should be executed once after each invocation of a parameterized class. Such methods are inherited unless they are overridden.

@ClassTemplate : Denotes that the annotated class is a template for a test class designed to be executed multiple times depending on the number of invocation contexts returned by the registered providers. Such annotations are inherited.

@Nested : Denotes that the annotated class is a non-static nested test class. Such annotations are not inherited.

@Tag : Used to declare tags for filtering tests, either at the class or method level; analogous to test groups in TestNG or Categories in JUnit 4. Such annotations are inherited at the class level but not at the method level.

@Disabled : Used to disable a test class or test method; analogous to JUnit 4’s @Ignore. Such annotations are not inherited.

@AutoClose : Denotes that the annotated field represents a resource that will be automatically closed after test execution. Such fields are inherited.

@Timeout : Used to fail a test, test factory, test template, or lifecycle method if its execution exceeds a given duration. Such annotations are inherited.

@TempDir : Used to supply a temporary directory via field injection or parameter injection in a test class constructor, lifecycle method, or test method; located in the org.junit.jupiter.api.io package. Such fields are inherited.

@ExtendWith : Used to register extensions declaratively. Such annotations are inherited.

@RegisterExtension : Used to register extensions programmatically via fields. Such fields are inherited.

Meta-Annotations and Composed Annotations

JUnit Jupiter annotations can be used as meta-annotations. That means that you can define your own composed annotation that will automatically inherit the semantics of its meta-annotations.

For example, instead of copying and pasting @Tag(“fast”) throughout your code base (see Tagging and Filtering), you can create a custom composed annotation named @Fast as follows. @Fast can then be used as a drop-in replacement for @Tag(“fast”).

• Java
• Kotlin

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import org.junit.jupiter.api.Tag;

@Target({ ElementType.TYPE, ElementType.METHOD })
@Retention(RetentionPolicy.RUNTIME)
@Tag("fast")
public @interface Fast {
}

import org.junit.jupiter.api.Tag

@Target(AnnotationTarget.TYPE, AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.RUNTIME)
@Tag("fast")
annotation class Fast

The following @Test method demonstrates usage of the @Fast annotation.

• Java
• Kotlin

@Fast
@Test
void myFastTest() {
    // ...
}

@Fast
@Test
fun myFastTest() {
    // ...
}

You can even take that one step further by introducing a custom @FastTest annotation that can be used as a drop-in replacement for @Tag(“fast”) and @Test.

• Java
• Kotlin

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import org.junit.jupiter.api.Tag;
import org.junit.jupiter.api.Test;

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Tag("fast")
@Test
public @interface FastTest {
}

import org.junit.jupiter.api.Tag
import org.junit.jupiter.api.Test

@Target(AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.RUNTIME)
@Tag("fast")
@Test
annotation class FastTest

JUnit automatically recognizes the following as a @Test method that is tagged with “fast”.

• Java
• Kotlin

@FastTest
void myFastTest() {
    // ...
}

@FastTest
fun myFastTest() {
    // ...
}