Document compatibility with JUnit 4 TestRules

[smoyer64]

The following is an analysis of which JUnit 4 TestRule functionality is provided by JUnit 5. This should be documented in an addendum to the User Guide.

• DisableOnDebug - partially accomplished using DisableIf/EnableIf, partially allowed via the use of @Tags as described in sections 3.7 Tagging and Filtering of the user guide. But is it completely covered? I was completely off base with this assessment. This @TestRule allows you to disable a test rule if the JVM is in debug mode and has absolutely nothing to do with deciding what tests should be run.
• ExpectedException - use Assertions.expectThrows() as described in section 3.4 Assertions of the User Guide.
• ExternalResource
• TemporaryFolder - Provide TemporaryDirectory which is used for internal JUnit 5 tests as part of https://github.com/junit-team/junit5-samples. See Create example for TemporaryFolder extension junit5-samples#4.
• RuleChain - JUnit 5 extensions enable via @ExtendWith are executed in declaration order.
• Stopwatch - partially provided via the TimingExtension in section 5.6.1 Before and After Test Execution Callbacks of the user guide. See this comment: Create example for TemporaryFolder extension junit5-samples#4 (comment). Reporting of the result state could be accomplished by injecting TestReporter via parameter resolution (using @BeforeAll?) but there are potentially use cases that can't be handled.
• TestWatcher
• TestName - inject TestInfo into the test using parameter resolution.
• Timeout - JUnit 4 allows the timeout to be specified via @Test. Is there an equivalent in JUnit 5? For performance testing, it would also be nice to have the test fail if it exceeded a threshold.
• Verifier
• ErrorCollector - use Assertions.assertAll() as described in section 3.4 Assertions of the User Guide.

Related Issues

• Demonstrate migration path from JUnit 4 to JUnit 5 #169

Related Blog Posts

• http://www.codeaffine.com/2016/04/06/replace-rules-in-junit5/
• http://blog.codefx.org/libraries/junit-5-conditions/

[sbrannen]

Great list, and... thanks for doing all of the research!

[sbrannen]

This is related to #169.

[sbrannen]

Related blog posts:

• http://www.codeaffine.com/2016/04/06/replace-rules-in-junit5/
• http://blog.codefx.org/libraries/junit-5-conditions/

[sbrannen]

FYI: timeouts are supported in JUnit Jupiter via the assertTimeout() and assertTimeoutPreemptively() methods in Assertions. See #438 and related commits for details.

[smoyer64]

Nice! I'll update the description and mark it complete when M3 becomes current.

[marcphilipp]

@smoyer64 Would you be interested to add a section that documents the migration strategy for rules to the User Guide?

There are already sections for "Migration Tips" and "Limited JUnit 4 Rule Support".

[smoyer64]

@marcphilipp I've started this task and, after thinking through how I'd like it to be organized, wanted to present my thoughts before getting too far ahead.

It's my opinion that those using TestRule are intimately familiar with the javadocs at http://junit.org/junit4/javadoc/latest/org/junit/rules/TestRule.html (and for the javadocs and examples provided for each of the implementations). My intention is to leverage that knowledge to provide side-by-side (well ... top and bottom) examples of JUnit4 and JUnit5 for each of the rules in the description of this issue. Each rule would also get a sub-heading to make them easy to find using the Java class name of the rule.

I've created the jupiter and vintage equivalents for ExpectedException as an example. Note that these classes are not yet annotated for inclusion in the documentation but they do pass spotless checks and execute successfully during the platform tests. The examples can be found at https://github.com/selesy/junit5/tree/issues/343-document-testrule-compatibility/documentation/src/test/java/example/testrule.

Please comment/critique both my intended approach and the way I've named/structure the example classes.

[marcphilipp]

I think that's a very good approach. Please proceed! 🙂

[smoyer64]

Full steam ahead ... I think I'll open a PR that's linked to this issue and my fork so that it's easier for the team to review my work. I'll mark it WIP so that it's clear that it shouldn't be merged yet.

[sbrannen]

@smoyer64, is this still in progress?

[marcphilipp]

@smoyer64 I've unassigned you and put this issue "up-for-grabs" for someone else to take over.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. Given the limited bandwidth of the team, it will be automatically closed if no further activity occurs. Thank you for your contribution.

[stale]

This issue has been automatically closed due to inactivity. If you have a good use case for this feature, please feel free to reopen the issue.