Package org.junit.jupiter.api.parallel

Annotation Type ResourceLock

  • @API(status=STABLE,
     since="5.10")
@Retention(RUNTIME)
@Target({TYPE,METHOD})
@Inherited
@Repeatable(ResourceLocks.class)
public @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.

    Shared resources declared on or provided for methods or nested test classes in a @ClassTemplate are propagated as if they were declared on the outermost enclosing @ClassTemplate class itself.

    Since:
    5.3
    See Also:
    Isolated, Resources, ResourceAccessMode, ResourceLockTarget, ResourceLocks, ResourceLocksProvider