Introduce adding 'shared resources' programmatically

[VladimirDmitrienko]

Solves: #2677

Overview

Introduce adding shared resources programmatically via @ResourceLock(providers = ...) attribute
which accepts an array of one or more classes implementing ResourceLocksProvider interface.

It allows to add resources in runtime (immediately before starting execution on the engine level).

Resources can be distributed based on any test class / nested test class / test method attributes (e.g. package name, class / method name etc.) or any other user logic.

This approach serves as a more flexible and less verbose alternative for cases in which:

• adding lots of @ResourceLock(value, mode) annotations manually may be inconvenient;
• shared resources are not known until runtime.

---

I hereby agree to the terms of the JUnit Contributor License Agreement.

---

Definition of Done

• There are no TODOs left in the code
• Method preconditions are checked and documented in the method's Javadoc
• Coding conventions (e.g. for logging) have been followed
• Change is covered by automated tests including corner cases, errors, and exception handling
• Public API has Javadoc and @API annotations
• Change is documented in the User Guide
• Change is documented in the Release Notes

[marcphilipp]

Looks very promising! Sorry for the late request to change the API.

[marcphilipp]

After discussion in the team, we'd prefer adding a Class<? extends ResourceLocksProvider>[] providers() default {} attribute to the existing @ResourceLock annotation (and making value() optional by giving it an empty default value).

[VladimirDmitrienko]

Updated.

[marcphilipp]

We should also mention here (and in the annotations' Javadoc) that "static" and "dynamic" locks are combined.

[VladimirDmitrienko]

Updated.
Mentioned in Javadoc for @ResourceLock and ResourceLocksProvider.

[VladimirDmitrienko]

Hi @marcphilipp
Maybe you have any updates regarding this PR?

[marcphilipp]

We should avoid searching for the annotation twice here

[VladimirDmitrienko]

Done

[marcphilipp]

Since the User Guide is versioned, we usually avoid mentioning specific versions when features were introduced. Thus, please remove that bit.

[VladimirDmitrienko]

Got it. Done

[marcphilipp]

Please revert the changes made to the formatting of these two paragraphs.

[VladimirDmitrienko]

Done

[marcphilipp]

Maybe it would make for a better example if we'd check for testMethod.getName().startsWith("canSet") and invert the if?

[VladimirDmitrienko]

Good point.
Done

[marcphilipp]

What about @Nested test classes? I think we'll have to collect exclusive resources from providers from the test class and, if it's a @Nested one, also from its enclosing class, recursively.

[marcphilipp]

On second thought, there is no need to apply locks from the class level to methods as it is redundant. When executing the method, the class-level locks are already held.

[VladimirDmitrienko]

What about @Nested test classes? I think we'll have to collect exclusive resources from providers from the test class and, if it's a @Nested one, also from its enclosing class, recursively.

I suppose that the behaviour of ResourceLocksProvider should be similar to the plain @ResourceLock("...").
Let's consider such an example:

@ResourceLock("A")
static class TestClass {

    @Nested
    @ResourceLock("B")
    class NestedTestClass {
    }
}

NestedTestClass gets only B but does not get A.

That's why I'm not sure that @Nested classes should invoke providers of enclosing classes.

[marcphilipp]

Please disregard my initial comment. We should neither check the test class nor any of its enclosing classes since that's already being done by the parent test descriptors. Thus, please remove the extra code that sets fromProvidersInClassLevelAnnotation etc.

[VladimirDmitrienko]

If we remove this code then LocksProvider#provideForMethod() will not be invoked for test():

@ResourceLock(providers = LocksProvider.class)
static class TestClass {

    @Test
    void test() {
    }
}