Annotation Interface ResourceLock
@ResourceLock
is used to declare that the annotated test class or test
method requires access to a shared resource identified by a key.
The resource key is specified via value()
. In addition, mode()
allows one to specify whether the annotated test class or test method requires
READ_WRITE
or
READ
access to the resource. In the former case,
execution of the annotated element will occur while no other test class or
test method that uses the shared resource is being executed. In the latter case,
the annotated element may be executed concurrently with other test classes or
methods that also require READ
access but not at the same time as any
other test that requires READ_WRITE
access.
This guarantee extends to lifecycle methods of a test class or method. For
example, if a test method is annotated with @ResourceLock
the lock
will be acquired before any @BeforeEach
methods are executed and released after all
@AfterEach
methods have been executed.
This annotation can be repeated to declare the use of multiple shared resources.
Uniqueness of a shared resource is determined by both the value()
and the mode()
. Duplicated shared resources do not cause errors.
Since JUnit Jupiter 5.4, this annotation is inherited within class hierarchies.
Since JUnit Jupiter 5.12, this annotation supports adding shared resources
dynamically at runtime via providers()
. Resources declared "statically"
using value()
and mode()
are combined with "dynamic" resources
added via providers()
. For example, declaring resource "A" via
@ResourceLock("A")
and resource "B" via a provider returning
new Lock("B")
will result in two shared resources "A" and "B".
Since JUnit Jupiter 5.12, this annotation supports declaring "static"
shared resources for direct child nodes via the target()
attribute. Using ResourceLockTarget.CHILDREN
in a class-level annotation
has the same semantics as adding an annotation with the same value()
and mode()
to each test method and nested test class declared in the
annotated class. This may improve parallelization when a test class declares a
READ
lock, but only a few methods hold
READ_WRITE
lock. Note that
target = CHILDREN
means that value()
and mode()
no
longer apply to a node declaring the annotation. However, the providers()
attribute remains applicable, and the target of "dynamic" shared resources added
via implementations of ResourceLocksProvider
is not changed.
- Since:
- 5.3
- See Also:
-
Optional Element Summary
Optional ElementsModifier and TypeOptional ElementDescriptionThe resource access mode.Class<? extends ResourceLocksProvider>[]
An array of one or more classes implementingResourceLocksProvider
.The resource key.
-
Element Details
-
value
String valueThe resource key.Defaults to an empty string.
- See Also:
- Default:
""
-
mode
ResourceAccessMode modeThe resource access mode.Defaults to
READ_WRITE
.- See Also:
- Default:
READ_WRITE
-
providers
An array of one or more classes implementingResourceLocksProvider
.Defaults to an empty array.
- Since:
- 5.12
- See Also:
- Default:
{}
-
target
The target of a resource created fromvalue()
andmode()
.Defaults to
SELF
.Note that using
ResourceLockTarget.CHILDREN
in a method-level annotation results in an exception.- Since:
- 5.12
- See Also:
- Default:
SELF
-