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 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 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. On Java 8 through Java 15, @BeforeAll and @AfterAll methods cannot be used directly in a @Nested test class unless the "per-class" test instance lifecycle is used. Beginning with Java 16, @BeforeAll and @AfterAll methods can be declared as static in a @Nested test class with either test instance lifecycle mode. 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.

Some annotations may currently be experimental. Consult the table in Experimental APIs for details.

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").

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 {
}

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

@Fast
@Test
void 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.

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 {
}

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

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