improve junit vintage docs about parallel execution

[etrandafir93]

Issue: #4321

Overview

Improving user guide section about parallel test execution at class/methods level with JUnit Vintage.

---

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

---

Definition of Done

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

[YongGoose]

Why did you remove this?

[YongGoose]

Suggested change

	Requires opt-in for `classes` or `methods` to be executed in parallel using the configuration parameters below.
	Requires opt-in for `classes` or `methods` to be executed in parallel using the configuration parameters below.

[YongGoose]

Suggested change

	By default, the number of available processors is used.
	By default, the number of available processors is used.

[etrandafir93]

I added the spaces, as suggested - but do we need them?

I have added the brake lines to comply with this sembr convention, but I won't have an effect on the way the text is displayed. That's why I haven't added any space at the start of the row.

[YongGoose]

I hope this is helpful to you.

• Implement Parallel Method Execution in JUnit-Vintage engine #4242 (comment)

[YongGoose]

With this setup, the VintageTestEngine will use two different threads

Suggested change

	junit.vintage.execution.parallel.enabled=true
	junit.vintage.execution.parallel.classes=true
	junit.vintage.execution.parallel.enabled=true
	junit.vintage.execution.parallel.classes=true
	junit.vintage.execution.parallel.pool-size=2

[etrandafir93]

I left this property out to allow the reader to focus on the ones that directly impact the example.

For the given example with 2 test classes and parallelization enabled per class, we'll always use 2 threads - even if the thread pool size is larger, correct?

Nonetheless, I have added it back now (and to the other examples as well).

[YongGoose]

For the given example with 2 test classes and parallelization enabled per class, we'll always use 2 threads - even if the thread pool size is larger, correct?

That’s correct.

While you could explain it by saying that running FooTest and BarTest uses two threads, I believe it is more appropriate to relate it to the size of the thread pool rather than directly linking the number of tests to the number of threads. For example, when running three tests in parallel with a thread pool size of two, only two threads will be used, regardless of the number of tests.

What do you think? @marcphilipp

[YongGoose]

The default number of threads is Runtime.getRuntime().availableProcessors() unless specified otherwise.
So, it would be a good idea to include a configuration setting to define the number of threads.

• https://github.com/junit-team/junit5/blob/main/junit-vintage-engine/src/main/java/org/junit/vintage/engine/execution/VintageExecutor.java#L48

[YongGoose]

It would be great to add documentation for the following cases as well.

The document looks much better now.
Thank you! 🙂

junit.vintage.execution.parallel.enabled=false
junit.vintage.execution.parallel.classes=true
junit.vintage.execution.parallel.methods=true

[etrandafir93]

junit.vintage.execution.parallel.enabled=false
junit.vintage.execution.parallel.classes=true
junit.vintage.execution.parallel.methods=true

@YongGoose - thanks for the feedback. I have updated the PR now addressing the comments.
I have broken down the content into 4 short subsections, as the main section grew.

I have added the example above as well as the case where parallel execution is enabled but no parallel execution level is defined - to highlight this misconfiguration as well.

Let me know what you think:)

[YongGoose]

There should be two spaces at the start :)

I’ve also had more feedback on documentation than on code when contributing. 😂

[etrandafir93]

oh 😅 fixed now. I wonder if spotless can be configured to catch this

[YongGoose]

I’m not very familiar with Spotless, so I’m not sure if it provides that feature. 😁
If it does, it might be a good idea to discuss it with Marc and consider contributing.
It looks like the file below is used for Spotless configuration.

• https://github.com/junit-team/junit5/blob/main/gradle/plugins/common/src/main/kotlin/junitbuild.spotless-conventions.gradle.kts

[jbduncan]

As a former contributor to Spotless, there's nothing technical stopping us from adopting such a check. It would "just" require implementing a regex (which the Gradle plugin has native support for) or finding a JVM library or CLI tool that does the job.

However, as English uses full stops for ends of sentences, word shortenings (for example, "regarding" to "re.") and inside other words sometimes (for example, "01.01.2025"), this may be tricky to do without heuristics unless we're happy to catch all full stops followed one space or 3+ spaces.

[YongGoose]

@YongGoose - thanks for the feedback. I have updated the PR now addressing the comments.
I have broken down the content into 4 short subsections, as the main section grew.

I have added the example above as well as the case where parallel execution is enabled but no parallel execution level is defined - to highlight this misconfiguration as well.

Let me know what you think:)

LGTM 👍