Support programmatic registration of resource locks #3889

vdmitrienko · 2024-07-16T18:21:31Z

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

Issue: #2677

marcphilipp

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

junit-jupiter-api/src/main/java/org/junit/jupiter/api/parallel/ResourceLocksFrom.java

junit-jupiter-api/src/main/java/org/junit/jupiter/api/parallel/ResourceLocksProvider.java

documentation/src/docs/asciidoc/user-guide/writing-tests.adoc

…Tests'." This reverts commit ff3c786. Issue: #2677

Issue: #2677

…nto #2677_add_exclusive_resource_programmatically

Issue: #2677

vdmitrienko · 2024-09-02T07:35:05Z

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

...-jupiter-engine/src/main/java/org/junit/jupiter/engine/descriptor/JupiterTestDescriptor.java

documentation/src/docs/asciidoc/user-guide/writing-tests.adoc

documentation/src/test/java/example/sharedresources/DynamicSharedResourcesDemo.java

...iter-engine/src/main/java/org/junit/jupiter/engine/descriptor/MethodBasedTestDescriptor.java

…rammatically

Issue: #2677

...iter-engine/src/main/java/org/junit/jupiter/engine/descriptor/MethodBasedTestDescriptor.java

Issue: #2677

…rammatically

Issue: #2677

.../src/test/java/org/junit/platform/engine/support/descriptor/ResourceLockAnnotationTests.java

Issue: #2677

marcphilipp

Thanks! I'll take it from here.

documentation/src/docs/asciidoc/release-notes/release-notes-5.12.0-M1.adoc

documentation/src/docs/asciidoc/user-guide/writing-tests.adoc

documentation/src/test/java/example/sharedresources/DynamicSharedResourcesDemo.java

junit-jupiter-api/src/main/java/org/junit/jupiter/api/parallel/ResourceLocksProvider.java

marcphilipp · 2024-10-07T08:20:11Z

...-jupiter-engine/src/main/java/org/junit/jupiter/engine/descriptor/JupiterTestDescriptor.java

+		List<ResourceLock> enclosingClassesAnnotations = getEnclosingTestClasses().stream()
+				.map(clazz -> findRepeatableAnnotations(clazz, ResourceLock.class))
+				.flatMap(Collection::stream)
+				.collect(toList());


I think it would be slightly better to get the registered ResourceLockProviders from the parent test descriptor rather than collecting them again for every test and reinstantiating them but I'll take care of that in a follow-up PR.

You're right, many method / nested class descriptors may share the same parent 👍

vdmitrienko · 2024-10-07T08:48:31Z

Thanks! I'll take it from here.

Thank you!
This was my first contribution, and it was very interesting and valuable experience.

vdmitrienko mentioned this pull request Jul 16, 2024

Support programmatic registration of resource locks #2677

Closed

vdmitrienko marked this pull request as draft July 17, 2024 06:39

vdmitrienko changed the title ~~Draft: Implement adding ExclusiveResource programmatically.~~ Implement adding ExclusiveResource programmatically. Jul 17, 2024

vdmitrienko changed the title ~~Implement adding ExclusiveResource programmatically.~~ Introduce adding 'shared resources' programmatically Aug 6, 2024

vdmitrienko marked this pull request as ready for review August 8, 2024 06:52

vdmitrienko added 6 commits August 8, 2024 10:03

Introduce adding 'resource locks' programmatically.

7fc2b96

Issue: #2677

Add 'ResourceLocksProviderIntegrationTests'.

cde4bc8

Issue: #2677

Add JavaDoc.

00788b6

Issue: #2677

Add 'locks from provider' cases to 'NodeTreeWalkerIntegrationTests'.

ff3c786

Issue: #2677

Add 'LockTests'.

1c6eef8

Issue: #2677

Add user guide.

7d894c5

Issue: #2677

marcphilipp linked an issue Aug 9, 2024 that may be closed by this pull request

Support programmatic registration of resource locks #2677

Closed

marcphilipp requested changes Aug 9, 2024

View reviewed changes

vdmitrienko added 5 commits August 12, 2024 22:42

Revert "Add 'locks from provider' cases to 'NodeTreeWalkerIntegration…

1f8a6d0

…Tests'." This reverts commit ff3c786. Issue: #2677

Move '@ResourceLocksFrom' functionality to '@ResourceLock'.

e1b5473

Issue: #2677

Add tests for '@ResourceLock' and 'ResourceLocksProvider'.

4460685

Issue: #2677

Merge branch 'main' of https://github.com/VladimirDmitrienko/junit5 i…

e14bfda

…nto #2677_add_exclusive_resource_programmatically

Fix formatting.

ba476e5

Issue: #2677

vdmitrienko requested a review from marcphilipp August 16, 2024 10:49

Polish Javadoc

1d8488c

marcphilipp requested changes Sep 18, 2024

View reviewed changes

vdmitrienko added 8 commits September 20, 2024 09:13

Merge branch 'refs/heads/main' into #2677_add_exclusive_resource_prog…

3fddd55

…rammatically

Merge branch 'refs/heads/main' into #2677_add_exclusive_resource_prog…

49f9a28

…rammatically

Remove version from User Guide.

d56196d

Issue: #2677

Revert formatting changes in User Guide.

c8d26ef

Issue: #2677

Mention that ResourceLocksProvider must have a no-args constructor.

9383c39

Issue: #2677

Avoid searching for the annotation twice.

249ab3e

Issue: #2677

Polish DynamicSharedResourcesDemo.

67e7dc5

Issue: #2677

Add Release Notes.

792b43a

Issue: #2677

vdmitrienko requested a review from marcphilipp September 27, 2024 11:38

marcphilipp requested changes Oct 2, 2024

View reviewed changes

...iter-engine/src/main/java/org/junit/jupiter/engine/descriptor/MethodBasedTestDescriptor.java Outdated Show resolved Hide resolved

vdmitrienko added 4 commits October 4, 2024 09:43

Collect locks from the providers of the enclosing classes.

ef2f38f

Issue: #2677

Merge branch 'refs/heads/main' into #2677_add_exclusive_resource_prog…

730a99d

…rammatically

Fix formatting.

cb01e24

Issue: #2677

Fix formatting.

35acb01

Issue: #2677

vdmitrienko requested a review from marcphilipp October 4, 2024 08:36

marcphilipp requested changes Oct 4, 2024

View reviewed changes

.../src/test/java/org/junit/platform/engine/support/descriptor/ResourceLockAnnotationTests.java Outdated Show resolved Hide resolved

Remove debug code.

3d8af62

Issue: #2677

marcphilipp self-requested a review October 4, 2024 11:33

Test that the locks from the 'outer' and 'nested' providers combined.

780c03b

Issue: #2677

marcphilipp approved these changes Oct 7, 2024

View reviewed changes

marcphilipp added 4 commits October 7, 2024 10:23

Apply suggestions from code review

fed909b

Polish Javadoc

826fb0f

Remove unused imports

dc6b2a9

Polish code snippet

a728b5b

marcphilipp changed the title ~~Introduce adding 'shared resources' programmatically~~ Allow determining exclusive resources programmatically Oct 7, 2024

marcphilipp merged commit 8e9094d into junit-team:main Oct 7, 2024
15 checks passed

vdmitrienko mentioned this pull request Nov 23, 2024

Allow declaring exclusive resources for child nodes #4151

Merged

6 tasks

sbrannen changed the title ~~Allow determining exclusive resources programmatically~~ Support programmatic registration of resource locks Jan 26, 2025

sbrannen added type: enhancement theme: extensions theme: concurrency component: Jupiter labels Jan 26, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Support programmatic registration of resource locks #3889

Support programmatic registration of resource locks #3889

vdmitrienko commented Jul 16, 2024 •

edited

Loading

marcphilipp left a comment

vdmitrienko commented Sep 2, 2024

marcphilipp left a comment

marcphilipp Oct 7, 2024

vdmitrienko Oct 7, 2024

vdmitrienko commented Oct 7, 2024

Support programmatic registration of resource locks #3889

Support programmatic registration of resource locks #3889

Conversation

vdmitrienko commented Jul 16, 2024 • edited Loading

Overview

Definition of Done

marcphilipp left a comment

Choose a reason for hiding this comment

vdmitrienko commented Sep 2, 2024

marcphilipp left a comment

Choose a reason for hiding this comment

marcphilipp Oct 7, 2024

Choose a reason for hiding this comment

vdmitrienko Oct 7, 2024

Choose a reason for hiding this comment

vdmitrienko commented Oct 7, 2024

vdmitrienko commented Jul 16, 2024 •

edited

Loading