Skip to content

Improve documentation on Parallel Test Execution #2669

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
2 tasks done
bondolo opened this issue Jul 21, 2021 · 14 comments · Fixed by #4525
Closed
2 tasks done

Improve documentation on Parallel Test Execution #2669

bondolo opened this issue Jul 21, 2021 · 14 comments · Fixed by #4525
Assignees
@2897robo
Labels
component: Jupiter theme: documentation type: enhancement up-for-grabs
Milestone
5.13.0

Comments

@bondolo
Copy link

bondolo commented Jul 21, 2021 •
edited by marcphilipp
Loading

I have some comments regarding configuring tests for parallel execution following reading: https://junit.org/junit5/docs/snapshot/user-guide/index.html#writing-tests-parallel-execution

Identifying all the relevant properties and the defaults for the properties in junit-platform.properties needs to be more obvious. They can be deduced from the narrative but perhaps should just be stated explicitly.

Also, a gentle approach for enabling parallelism should be suggested along with suggested mitigations when things don't work, as a sequence of steps that projects can evolve upon while still getting some parallelization benefit. An example for the Execution annotation would be useful as well. Non-parallel test execution could be considered a form of technical debt and a suggested approach for whittling away at that debt to make incremental progress towards as-parallel-as-practical execution. ie. help people figure out where they are now and what their next step should be along with necessary validation checks for each step.

Deliverables

  • Add table of relevant configuration parameters
  • Add example for using the @Execution annotation
@sbrannen sbrannen changed the title Feedback on Parallel Test Execution documentation Improve documentation on Parallel Test Execution Jul 24, 2021
@marcphilipp
Copy link
Member

@bondolo Thanks for the feedback! Would you be interested in working on this via a more concrete outline here and then a PR?

@bondolo
Copy link
Author

bondolo commented Nov 2, 2021 •
edited
Loading

@marcphilipp I am definitely not an expert in this area. My suggestions above were based upon the concerns I struggled with in starting to enable parallelism in an existing project--a journey which is not yet completed. I would enthusiastically review any new material looking for ideas to advance our usage but, at this point, don't have much useful to contribute.

@MaratCrash
Copy link

@marcphilipp if its possible I can join to the issue and solve that.

@stoyanK7
Copy link
Contributor

stoyanK7 commented Jun 14, 2022 •
edited
Loading

@bondolo Just made a table with the relevant properties, description, accepted values and default value. Is this what you envisioned?
aaa

@bondolo
Copy link
Author

bondolo commented Jun 16, 2022

@stoyanK7 Yes, that is helpful!

@stoyanK7 stoyanK7 mentioned this issue Jun 16, 2022
Closed
7 tasks
@Kavisha4
Copy link

Hi @marcphilipp, interested to work on this, is this issue still open?

@marcphilipp
Copy link
Member

@Kavisha4 Thanks for asking!

The table has been added in #2946 (comment).

I've added another deliverable to the issue description for which we'd accept a PR.

@bondolo If you have any other concrete suggestion, please let us know.

@YongGoose
Copy link
Contributor

YongGoose commented Feb 13, 2025 •
edited
Loading

@marcphilipp

How about improving the documentation on parallel test execution in JUnit Vintage, which I recently contributed to?

Currently, in the JUnit 5 repository, the only issue labeled up-for-grabs that is not in progress on is this one.
However, from my perspective, it already seems to be resolved.
There is still one task left, but having more issues labeled up-for-grabs would encourage more developers to contribute.

If you agree with my suggestion, I’ll go ahead and create the issue.
Of course, I won’t resolve it myself so that other developers can take it on.

@marcphilipp
Copy link
Member

How about improving the documentation on parallel test execution in JUnit Vintage, which I recently contributed to?

What did you have in mind?

@YongGoose
Copy link
Contributor

YongGoose commented Feb 15, 2025 •
edited
Loading

What did you have in mind?

The current documentation on parallel execution in JUnit Vintage is somewhat brief. 😅

Although I wrote it myself, looking at it now, it really seems quite brief.

However, it would be clearer if it were explained more thoroughly, using tables like in the JUnit Jupiter documentation.

Additionally, in JUnit Vintage, class and method parallelism can be configured separately. In cases where junit.vintage.execution.parallel.enabled is set to true, and both junit.vintage.execution.parallel.classes and junit.vintage.execution.parallel.methods are set to false, tests will be executed sequentially. It would be helpful to include this scenario in the documentation.

It would be good to outline all the possible scenarios that can occur with class and method parallelism.

Without this clarification, if only junit.vintage.execution.parallel.enabled is set to true and no other settings are configured, tests will execute sequentially due to the default false values for method and class parallelism.

@marcphilipp
Copy link
Member

Additionally, in JUnit Vintage, class and method parallelism can be configured separately. In cases where junit.vintage.execution.parallel.enabled is set to true, and both junit.vintage.execution.parallel.classes and junit.vintage.execution.parallel.methods are set to false, tests will be executed sequentially. It would be helpful to include this scenario in the documentation.

That's why I added the last sentence here:

junit5/documentation/src/docs/asciidoc/user-guide/migration-from-junit4.adoc

Lines 48 to 49 in c9d8cb1

Enable/disable parallel execution (defaults to `false`). Requires opt-in for `classes`
or `methods` to be executed in parallel using the configuration parameters below.

But I agree that it would benefit from stating explicitly what happens in case neither the classes nor the methods configuration parameter are set to true. So, I think a PR that adds that would be good, with or without creating an issue for it first. 🙂

@YongGoose YongGoose mentioned this issue Feb 15, 2025
Closed
2 tasks
@YongGoose
Copy link
Contributor

YongGoose commented Feb 15, 2025 •
edited
Loading

@marcphilipp

I’ve created the issue!

If you agree with my suggestion, I’ll go ahead and create the issue.
Of course, I won’t resolve it myself so that other developers can take it on.

As mentioned above, I’m only creating the issue for the community, not resolving it myself.
I’d appreciate it if you could add the up-for-grabs label to the issue I created.

Additionally, if you have time, I would appreciate it if you could also take a look at the PR I'm currently working on. 🙂

@2897robo
Copy link
Contributor

Hi @marcphilipp, @sbrannen 👋

I'd love to contribute to this issue.

As someone who is currently deepening my understanding of JUnit's parallel execution model, this looks like a great opportunity to learn and contribute at the same time. I'll review the current documentation and propose clearer explanations and examples around configuration parameters and the @Execution annotation as discussed.

Let me know if it's okay for me to start working on it. If so, I’ll fork the repo and open a PR soon.

Thanks!

@marcphilipp
Copy link
Member

Sure, go ahead! 👍

2897robo added a commit to 2897robo/junit5 that referenced this issue May 12, 2025
@2897robo
Add example usage of @execution annotation for parallel test executio…
54a6c1f 
…n Issue: junit-team#2669
@2897robo 2897robo mentioned this issue May 12, 2025
Merged
@marcphilipp marcphilipp linked a pull request May 13, 2025 that will close this issue
Improve documentation on @Execution annotation usage for parallel test execution #4525
Merged
@marcphilipp marcphilipp modified the milestone: 5.13.0-RC1 May 13, 2025
@marcphilipp marcphilipp added this to the 5.13.0 milestone May 16, 2025
marcphilipp added a commit that referenced this issue May 19, 2025
@2897robo @marcphilipp
Add example for using @Execution annotation to User Guide (#4525)
b4ba1bf 
Resolves #2669.

---------

Co-authored-by: Marc Philipp <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@2897robo 2897robo

Labels
component: Jupiter theme: documentation type: enhancement up-for-grabs
Projects
None yet
Milestone
5.13.0
Development

Successfully merging a pull request may close this issue.

Improve documentation on @Execution annotation usage for parallel test execution 2897robo/junit5
8 participants
@sbrannen @marcphilipp @bondolo @MaratCrash @stoyanK7 @2897robo @Kavisha4 @YongGoose