= Annotations

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

Unless otherwise stated, all core annotations are located in the `{api-package}` 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
xref:writing-tests/parameterized-classes-and-tests.adoc[parameterized test]. Such methods are inherited
unless they are overridden.

`*@RepeatedTest*`:: Denotes that a method is a test template for a
xref:writing-tests/repeated-tests.adoc[repeated test]. Such methods are inherited unless they
are overridden.

`*@TestFactory*`:: Denotes that a method is a test factory for
xref:writing-tests/dynamic-tests.adoc[dynamic tests]. Such methods are inherited unless they are
overridden.

`*@TestTemplate*`:: Denotes that a method is a
xref:writing-tests/test-templates.adoc[template for a test case] designed to be invoked multiple
times depending on the number of invocation contexts returned by the registered
xref:extensions/providing-invocation-contexts-for-test-templates.adoc[providers]. Such methods are inherited unless they are
overridden.

`*@TestClassOrder*`:: Used to configure the
xref:writing-tests/test-execution-order.adoc#classes[test class execution order] for `@Nested`
test classes in the annotated test class. Such annotations are inherited.

`*@TestMethodOrder*`:: Used to configure the
xref:writing-tests/test-execution-order.adoc#methods[test method execution order] for the
annotated test class; similar to JUnit 4's `@FixMethodOrder`. Such annotations are
inherited.

`*@TestInstance*`:: Used to configure the
xref:writing-tests/test-instance-lifecycle.adoc[test instance lifecycle] for the annotated test
class. Such annotations are inherited.

`*@DisplayName*`:: Declares a custom xref:writing-tests/display-names.adoc[display name] for the
test class or test method. Such annotations are not inherited.

`*@DisplayNameGeneration*`:: Declares a custom
xref:writing-tests/display-names.adoc#generator[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"
xref:writing-tests/test-instance-lifecycle.adoc[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"
xref:writing-tests/test-instance-lifecycle.adoc[test instance lifecycle] is used.

`*@ParameterizedClass*`:: Denotes that the annotated class is a
xref:writing-tests/parameterized-classes-and-tests.adoc[parameterized class]. Such annotations are
inherited.

`*@BeforeParameterizedClassInvocation*`:: Denotes that the annotated method should be
executed once _before_ each invocation of a
xref:writing-tests/parameterized-classes-and-tests.adoc[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
xref:writing-tests/parameterized-classes-and-tests.adoc[parameterized class]. Such methods are inherited
unless they are overridden.

`*@ClassTemplate*`:: Denotes that the annotated class is a
xref:writing-tests/class-templates.adoc[template for a test class] designed to be executed
multiple times depending on the number of invocation contexts returned by the registered
xref:extensions/providing-invocation-contexts-for-class-templates.adoc[providers]. Such annotations are inherited.

`*@Nested*`:: Denotes that the annotated class is a non-static
xref:writing-tests/nested-tests.adoc[nested test class]. Such annotations are not inherited.

`*@Tag*`:: Used to declare
xref:writing-tests/tagging-and-filtering.adoc[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 xref:writing-tests/disabling-tests.adoc[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
xref:writing-tests/built-in-extensions.adoc#AutoClose[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
xref:writing-tests/built-in-extensions.adoc#TempDirectory[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
xref:extensions/registering-extensions.adoc#registration-declarative[register extensions declaratively]. Such
annotations are inherited.

`*@RegisterExtension*`:: Used to
xref:extensions/registering-extensions.adoc#registration-programmatic[register extensions programmatically] via fields.
Such fields are inherited.

WARNING: Some annotations may currently be _experimental_. Consult the table in
xref:api-evolution.adoc#experimental-apis[Experimental APIs] for details.

[[annotations]]
== 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
xref:writing-tests/tagging-and-filtering.adoc[]), you can create a custom _composed annotation_
named `@Fast` as follows. `@Fast` can then be used as a drop-in replacement for
`@Tag("fast")`.

[tabs]
====
Java::
+
--
[source,java,indent=0]
----
include::example$java/example/Fast.java[tags=user_guide]
----
--

Kotlin::
+
--
[source,kotlin,indent=0]
----
include::example$kotlin/example/kotlin/Fast.kt[tags=user_guide]
----
--
====

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

[tabs]
====
Java::
+
--
[source,java,indent=0]
----
@Fast
@Test
void myFastTest() {
    // ...
}
----
--

Kotlin::
+
--
[source,kotlin,indent=0]
----
@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`.

[tabs]
====
Java::
+
--
[source,java,indent=0]
----
include::example$java/example/FastTest.java[tags=user_guide]
----
--

Kotlin::
+
--
[source,kotlin,indent=0]
----
include::example$kotlin/example/kotlin/FastTest.kt[tags=user_guide]
----
--
====

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

[tabs]
====
Java::
+
--
[source,java,indent=0]
----
@FastTest
void myFastTest() {
    // ...
}
----
--

Kotlin::
+
--
[source,kotlin,indent=0]
----
@FastTest
fun myFastTest() {
    // ...
}
----
--
====
