JUnit 5 User Guide

1 JUnit 5 User Guide Table of Contents 1. Overview .. 5. What is JUnit 5? .. 5. Supported Java Versions .. 6. Getting Help .. 6. Getting Started.. 6. Downloading JUnit Artifacts.. 6. JUnit 5 Features .. 6. Example Projects .. 6. 2. Writing Tests .. 7. Annotations .. 7. Meta-Annotations and Composed Annotations .. 9. Test Classes and Methods .. 10. Display Names .. 12. Display Name Generators .. 13. Setting the Default Display Name Generator .. 15. Assertions .. 16. Kotlin Assertion Support .. 19. Third-party Assertion Libraries .. 21. Assumptions.. 22. Disabling Tests.. 23. Conditional Test Execution.. 24. Operating System Conditions .. 24. Java Runtime Environment Conditions.. 25. System Property Conditions .. 26. Environment Variable Conditions .. 27. Custom Conditions .. 27. Tagging and Filtering.. 29. Test Execution Order .. 29. Method Order.

2 29. Setting the Default Method Orderer .. 30. Class Order .. 31. Test Instance Lifecycle .. 33. Changing the Default Test Instance Lifecycle .. 33. Nested Tests .. 34. Dependency Injection for Constructors and Methods.. 36. Test Interfaces and Default Methods .. 40. 1. Repeated Tests.. 45. Repeated Test Examples .. 45. Parameterized Tests.. 48. Required Setup .. 49. Consuming Arguments .. 49. Sources of Arguments .. 50. @ValueSource .. 50. Null and Empty Sources .. 50. @EnumSource .. 51. @MethodSource .. 52. @CsvSource .. 55. @CsvFileSource .. 57. @ArgumentsSource .. 59. Argument Conversion .. 59. Widening Conversion .. 59. Implicit Conversion .. 59. Explicit Conversion.. 63. Argument Aggregation .. 64. Custom Aggregators .. 65. Customizing Display Names .. 66. Lifecycle and Interoperability .. 68. Test Templates.. 69. Dynamic Tests.

3 69. Dynamic Test Examples .. 70. URI Test Sources for Dynamic Tests .. 74. Timeouts .. 75. Using @Timeout for Polling Tests .. 77. Disable @Timeout Globally .. 77. Parallel Execution .. 78. Configuration.. 81. Synchronization .. 81. Built-in Extensions .. 83. The TempDirectory Extension .. 83. 3. Migrating from JUnit 4 .. 85. Running JUnit 4 Tests on the JUnit Platform .. 85. Categories Support .. 86. Migration Tips .. 86. Limited JUnit 4 Rule Support .. 86. JUnit 4 @Ignore Support .. 87. 4. Running Tests .. 88. IDE Support .. 88. 2. IntelliJ IDEA .. 88. Eclipse .. 89. NetBeans .. 90. Visual Studio Code .. 90. Other IDEs.. 90. Build Support.. 90. Gradle .. 90. Configuration Parameters.. 91. Configuring Test Engines .. 91. Configuring Logging (optional) .. 92. Maven .. 92. Configuring Test Engines .. 92. Filtering by Test Class Names.

4 94. Filtering by Tags .. 95. Configuration Parameters.. 95. Ant .. 96. Basic Usage .. 96. Console Launcher .. 97. Options .. 98. Argument Files (@-files) .. 101. Using JUnit 4 to run the JUnit Platform .. 101. Setup .. 102. Explicit Dependencies .. 102. Transitive Dependencies.. 102. Display Names vs. Technical Names .. 102. Single Test Class .. 102. Test Suite.. 103. Configuration Parameters .. 104. Pattern Matching Syntax.. 104. Tags .. 105. Syntax Rules for Tags .. 105. Tag Expressions.. 106. Capturing Standard Output/Error .. 106. Using Listeners .. 107. Flight Recorder Support .. 108. 5. Extension Model.. 108. Overview .. 108. Registering Extensions .. 109. Declarative Extension Registration .. 109. Programmatic Extension Registration.. 111. Static Fields .. 112. 3. Instance Fields.. 114. Automatic Extension Registration .. 114.

5 Enabling Automatic Extension Detection .. 114. Extension Inheritance .. 115. Conditional Test Execution .. 115. Deactivating Conditions .. 115. Pattern Matching Syntax.. 116. Test Instance Factories .. 116. Test Instance Post-processing .. 116. Test Instance Pre-destroy Callback.. 116. Parameter Resolution .. 117. Test Result Processing .. 117. Test Lifecycle Callbacks.. 118. Before and After Test Execution Callbacks.. 118. Exception Handling .. 120. Intercepting Invocations .. 123. Providing Invocation Contexts for Test Templates .. 124. Keeping State in Extensions.. 125. Supported Utilities in Extensions .. 126. Annotation Support .. 126. Class Support .. 126. Reflection Support .. 126. Modifier Support .. 126. Relative Execution Order of User Code and Extensions .. 126. User and Extension Code .. 127. Wrapping Behavior of Callbacks.

6 130. 6. Advanced Topics.. 140. JUnit Platform Launcher API .. 140. Discovering Tests .. 140. Executing Tests .. 142. Registering a TestEngine .. 142. Registering a PostDiscoveryFilter .. 143. Registering a LauncherSessionListener .. 143. Registering a LauncherDiscoveryListener .. 146. Registering a TestExecutionListener .. 147. Configuring a TestExecutionListener.. 147. Deactivating a TestExecutionListener .. 147. Pattern Matching Syntax.. 148. Configuring the Launcher .. 148. JUnit Platform Reporting .. 148. JUnit Platform Suite Engine .. 149. 4. Setup .. 149. Required Dependencies.. 149. Transitive Dependencies.. 149. @Suite Example .. 149. JUnit Platform Test Kit.. 150. Engine Test Kit.. 150. Asserting Statistics .. 152. Asserting Events .. 153. 7. API Evolution .. 158. API Version and Status .. 159. Experimental APIs .. 159. Deprecated APIs.

7 162. @API Tooling Support .. 163. 8. Contributors .. 163. 9. Release Notes.. 163. 10. Appendix .. 163. Reproducible Builds.. 163. Dependency Metadata .. 163. JUnit Platform .. 163. JUnit Jupiter .. 165. JUnit Vintage .. 165. Bill of Materials (BOM) .. 165. Dependencies .. 166. Dependency Diagram .. 166. 1. Overview The goal of this document is to provide comprehensive reference documentation for programmers writing tests, extension authors, and engine authors as well as build tool and IDE vendors. What is JUnit 5? Unlike previous versions of JUnit , JUnit 5 is composed of several different modules from three different sub-projects. JUnit 5 = JUnit Platform + JUnit Jupiter + JUnit Vintage The JUnit Platform serves as a foundation for launching testing frameworks on the JVM. It also defines the TestEngine API for developing a testing framework that runs on the platform.

8 Furthermore, the platform provides a Console Launcher to launch the platform from the command line and the JUnit Platform Suite Engine for running a custom test suite using one or more test engines on the platform. First-class support for the JUnit Platform also exists in popular IDEs (see IntelliJ IDEA, Eclipse, NetBeans, and Visual Studio Code) and build tools (see Gradle, Maven, and 5. Ant). JUnit Jupiter is the combination of the new programming model and extension model for writing tests and extensions in JUnit 5. The Jupiter sub-project provides a TestEngine for running Jupiter based tests on the platform. JUnit Vintage provides a TestEngine for running JUnit 3 and JUnit 4 based tests on the platform. It requires JUnit or later to be present on the class path or module path. Supported Java Versions JUnit 5 requires Java 8 (or higher) at runtime.

9 However, you can still test code that has been compiled with previous versions of the JDK. Getting Help Ask JUnit 5 related questions on Stack Overflow or chat with the community on Gitter. Getting Started Downloading JUnit Artifacts To find out what artifacts are available for download and inclusion in your project, refer to Dependency Metadata. To set up dependency management for your build, refer to Build Support and the Example Projects. JUnit 5 Features To find out what features are available in JUnit 5 and how to use them, read the corresponding sections of this User Guide , organized by topic. Writing Tests in JUnit Jupiter Migrating from JUnit 4 to JUnit Jupiter Running Tests Extension Model for JUnit Jupiter Advanced Topics JUnit Platform Launcher API. JUnit Platform Test Kit Example Projects To see complete, working examples of projects that you can copy and experiment with, the junit5- samples repository is a good place to start.

10 The junit5-samples repository hosts a collection of sample projects based on JUnit Jupiter, JUnit Vintage, and other testing frameworks. You'll find appropriate build scripts ( , , , etc.) in the example projects. The links below 6. highlight some of the combinations you can choose from. For Gradle and Java, check out the junit5-jupiter-starter-gradle project. For Gradle and Kotlin, check out the junit5-jupiter-starter-gradle-kotlin project. For Gradle and Groovy, check out the junit5-jupiter-starter-gradle-groovy project. For Maven, check out the junit5-jupiter-starter-maven project. For Ant, check out the junit5-jupiter-starter-ant project. 2. Writing Tests The following example provides a glimpse at the minimum requirements for writing a test in JUnit Jupiter. Subsequent sections of this chapter will provide further details on all available features.