Merge remote-tracking branch 'origin/master' into junit-teamgh-1850

.github/ISSUE_TEMPLATE.md

@@ -5,7 +5,8 @@ after answering yourself: **"What kind of issue is this?"**_
 
 - ( ) **Question.** This issue tracker is not the place for questions.
 If you want to ask how to do something, or to understand why
-something isn't working the way you expect it to, use Stack Overflow.
+something isn't working the way you expect it to, please first use Stack
+Overflow or Gitter.
 https://stackoverflow.com/questions/tagged/junit5
 
 - ( ) **Bug report.** Please provide us the version of JUnit 5 you are

.github/ISSUE_TEMPLATE/question.md

@@ -1,12 +1,11 @@
 ---
 name: Question
-about: Please ask on Gitter or StackOverflow
-
+about: Please first ask on Gitter or StackOverflow before creating an issue
 ---
 
 This issue tracker is not the place for questions.
 If you want to ask how to do something, or to understand why
-something isn't working the way you expect it to, use Gitter [1] or Stack Overflow [2].
+something isn't working the way you expect it to, please use Gitter [1] or Stack Overflow [2].
 
 [1] https://gitter.im/junit-team/junit5
 [2] https://stackoverflow.com/questions/tagged/junit5

azure-pipelines.yml

@@ -1,17 +1,11 @@
-trigger:
-  branches:
-    include:
-    - master
-    - releases/*
-
 jobs:
 - job: linux_11
   displayName: Linux (OpenJDK 11)
   pool:
     vmImage: 'ubuntu-16.04'
   steps:
     - checkout: self
-      fetchDepth: 1
+      fetchDepth: 10
     - template: src/azure/azure-gradle-step.yml
       parameters:
         publishTestResults: true
@@ -23,7 +17,7 @@ jobs:
   container: openjdk:12
   steps:
     - checkout: self
-      fetchDepth: 1
+      fetchDepth: 10
     - template: src/azure/azure-gradle-step.yml
 
 - job: linux_13
@@ -33,7 +27,7 @@ jobs:
   container: openjdk:13
   steps:
     - checkout: self
-      fetchDepth: 1
+      fetchDepth: 10
     - template: src/azure/azure-gradle-step.yml
       parameters:
         continueOnError: true
@@ -43,15 +37,15 @@ jobs:
     vmImage: 'macOS-10.13'
   steps:
     - checkout: self
-      fetchDepth: 1
+      fetchDepth: 10
     - template: src/azure/azure-gradle-step.yml
 
 - job: Windows
   pool:
     vmImage: 'windows-2019'
   steps:
     - checkout: self
-      fetchDepth: 1
+      fetchDepth: 10
     - template: src/azure/azure-gradle-step.yml
 
 - job: coverage
@@ -61,7 +55,7 @@ jobs:
     vmImage: 'ubuntu-16.04'
   steps:
     - checkout: self
-      fetchDepth: 1
+      fetchDepth: 10
     - bash: |
         set -e
         export JAVA_HOME="${JAVA_HOME_11_X64}"
@@ -84,7 +78,7 @@ jobs:
     vmImage: 'ubuntu-16.04'
   steps:
     - checkout: self
-      fetchDepth: 1
+      fetchDepth: 10
     - bash: |
         set -e
         export JAVA_HOME="${JAVA_HOME_11_X64}"
@@ -102,7 +96,7 @@ jobs:
     vmImage: 'ubuntu-16.04'
   steps:
     - checkout: self
-      fetchDepth: 1
+      fetchDepth: 10
     - bash: |
         set -e
         export JAVA_HOME="${JAVA_HOME_11_X64}"

buildSrc/src/main/kotlin/java-library-conventions.gradle.kts

@@ -173,7 +173,7 @@ val compileModule by tasks.registering(JavaCompile::class) {
 tasks.compileJava {
 	// See: https://docs.oracle.com/en/java/javase/11/tools/javac.html
 	options.compilerArgs.addAll(listOf(
-			"-Xlint", // Enables all recommended warnings.
+			"-Xlint:all,-deprecation", // Enables all recommended warnings.
 			"-Werror" // Terminates compilation when warnings occur.
 	))
 	if (modularProjects.contains(project)) {

documentation/src/docs/asciidoc/release-notes/index.adoc

@@ -15,7 +15,7 @@ authors as well as build tool and IDE vendors.
 
 include::../link-attributes.adoc[]
 
-include::release-notes-5.5.0-M2.adoc[]
+include::release-notes-5.5.0-RC1.adoc[]
 
 include::release-notes-5.5.0-M1.adoc[]
 

documentation/src/docs/asciidoc/release-notes/release-notes-5.5.0-M2.adoc → documentation/src/docs/asciidoc/release-notes/release-notes-5.5.0-RC1.adoc

@@ -1,27 +1,28 @@
-[[release-notes-5.5.0-M2]]
-== 5.5.0-M2️
+[[release-notes-5.5.0-RC1]]
+== 5.5.0-RC1
 
 *Date of Release:* ❓
 
 *Scope:* ❓
 
 For a complete list of all _closed_ issues and pull requests for this release, consult the
-link:{junit5-repo}+/milestone/37?closed=1+[5.5 M2] milestone page in the JUnit repository
+link:{junit5-repo}+/milestone/37?closed=1+[5.5 RC1] milestone page in the JUnit repository
 on GitHub.
 
 
-[[release-notes-5.5.0-M2-junit-platform]]
+[[release-notes-5.5.0-RC1-junit-platform]]
 === JUnit Platform
 
 ==== Bug Fixes
 
-* ❓
+* A custom `ClassLoader` created for additional `--class-path` entries passed to the
+  `ConsoleLauncher` will now be closed after usage to gracefully free file handles.
 
 ==== Deprecations and Breaking Changes
 
-* Class `PreconditionViolationException` in concealed package
- `org.junit.platform.commons.util` is now deprecated and substituted by an exception class
-  with the same name in exported package `org.junit.platform.commons`.
+* The internal `PreconditionViolationException` class in concealed package
+  `org.junit.platform.commons.util` is now deprecated and has been replaced by an
+  exception class with the same name in exported package `org.junit.platform.commons`.
 
 ==== New Features and Improvements
 
@@ -31,9 +32,11 @@ on GitHub.
   `java.util.Optional<? extends AnnotatedElement>` argument.
 * Exceptions thrown by `TestExecutionListeners` no longer cause test execution to abort.
   Instead, they will be logged as warnings now.
+* New `MethodSource.from()` variant that accepts `String, String, Class<?>...` as
+  arguments.
 
 
-[[release-notes-5.5.0-M2-junit-jupiter]]
+[[release-notes-5.5.0-RC1-junit-jupiter]]
 === JUnit Jupiter
 
 ==== Bug Fixes
@@ -45,19 +48,27 @@ on GitHub.
 
 ==== Deprecations and Breaking Changes
 
-* ❓
+* Script-based condition APIs and their supporting implementations are deprecated with
+  the intent to remove them in JUnit Jupiter 5.6. Users should instead rely on a
+  combination of other built-in conditions or create and use a custom implementation of
+  `ExecutionCondition` to evaluate the same conditions.
 
 ==== New Features and Improvements
 
+* Support for declarative timeouts using `@Timeout` or configuration parameters (see
+  <<../user-guide/index.adoc#writing-tests-declarative-timeouts, User Guide>> for details)
 * New overloaded variants of `Assertions.assertLinesMatch(...)` that accept a `String` or
   a `Supplier<String>` for a custom failure message.
 * Failure messages for `Assertions.assertLinesMatch(...)` now emit each expected and
   actual line in a dedicated line.
-* New Kotlin friendly `assertDoesNotThrow` assertions have been added as top-level
-  functions in the `org.junit.jupiter.api` package.
+* New Kotlin friendly `assertDoesNotThrow`, `assertTimeout`, and `assertTimeoutPreemptively`
+  assertions have been added as top-level functions in the `org.junit.jupiter.api` package.
 * Display names for test methods generated by the `ReplaceUnderscores`
   `DisplayNameGenerator` no longer include empty parentheses for test methods that do not
   declare any parameters.
+* New `junit.jupiter.displayname.generator.default` configuration parameter to set the
+  default `DisplayNameGenerator` that will be used unless `@DisplayName` or
+  `@DisplayNameGeneration` is present.
 * `MethodOrderer.Random` now generates a default random seed only once and prints it to
   the log in order to allow reproducible builds.
 * Methods ordered with `MethodOrderer.Random` now execute using the `SAME_THREAD`
@@ -68,22 +79,12 @@ on GitHub.
 * New `InvocationInterceptor` extension API (see
   <<../user-guide/index.adoc#extensions-intercepting-invocations, User Guide>> for
   details).
-* New `junit.jupiter.displayname.generator.default` configuration parameter to set the
-  default `DisplayNameGenerator` that will be used unless `@DisplayName` or
-  `@DisplayNameGeneration` is present.
 
 
-[[release-notes-5.5.0-M2-junit-vintage]]
+[[release-notes-5.5.0-RC1-junit-vintage]]
 === JUnit Vintage
 
-==== Bug Fixes
-
-* ❓
-
-==== Deprecations and Breaking Changes
-
-* ❓
-
 ==== New Features and Improvements
 
-* ❓
+* `junit:junit` is now a compile-scoped dependency of `junit-vintage-engine` to allow for
+  easier dependency management in Maven POMs.

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

@@ -40,6 +40,7 @@ in the `junit-jupiter-api` module.
 | `@Nested`                | Denotes that the annotated class is a non-static <<writing-tests-nested,nested test class>>. `@BeforeAll` and `@AfterAll` methods cannot be used directly in a `@Nested` test class unless the "per-class" <<writing-tests-test-instance-lifecycle, test instance lifecycle>> is used. Such annotations are not _inherited_.
 | `@Tag`                   | Used to declare <<writing-tests-tagging-and-filtering,tags for filtering tests>>, either at the class or method level; analogous to test groups in TestNG or Categories in JUnit 4. Such annotations are _inherited_ at the class level but not at the method level.
 | `@Disabled`              | Used to <<writing-tests-disabling,disable>> a test class or test method; analogous to JUnit 4's `@Ignore`. Such annotations are not _inherited_.
+| `@Timeout`               | Used to fail a test, test factory, test template, or lifecycle method if its execution exceeds a given duration. Such annotations are _inherited_.
 | `@ExtendWith`            | Used to <<extensions-registration-declarative,register extensions declaratively>>. Such annotations are _inherited_.
 | `@RegisterExtension`     | Used to <<extensions-registration-programmatic,register extensions programmatically>> via fields. Such fields are _inherited_ unless they are _shadowed_.
 | `@TempDir`               | Used to supply a <<writing-tests-built-in-extensions-TempDirectory,temporary directory>> via field injection or parameter injection in a lifecycle method or test method; located in the `org.junit.jupiter.api.io` package.
@@ -217,11 +218,12 @@ include::{testDir}/example/AssertionsDemo.java[tags=user_guide]
 
 [[writing-tests-assertions-preemptive-timeouts]]
 [WARNING]
-.Preemptive Timeouts
+.Preemptive Timeouts with `assertTimeoutPreemptively()`
 ====
-The various `assertTimeoutPreemptively()` methods in the `Assertions` class execute the
-provided `executable` or `supplier` in a different thread than that of the calling code.
-This behavior can lead to undesirable side effects if the code that is executed within the
+Contrary to <<writing-tests-declarative-timeouts, declarative timeouts>>, the various
+`assertTimeoutPreemptively()` methods in the `Assertions` class execute the provided
+`executable` or `supplier` in a different thread than that of the calling code. This
+behavior can lead to undesirable side effects if the code that is executed within the
 `executable` or `supplier` relies on `java.lang.ThreadLocal` storage.
 
 One common example of this is the transactional testing support in the Spring Framework.
@@ -413,16 +415,15 @@ include::{testDir}/example/ConditionalTestExecutionDemo.java[tags=user_guide_env
 [[writing-tests-conditional-execution-scripts]]
 ==== Script-based Conditions
 
+WARNING: Conditional test execution via `{EnabledIf}` and `{DisabledIf}` is _deprecated_
+for removal in a future release of JUnit Jupiter.
+
 JUnit Jupiter provides the ability to either _enable_ or _disable_ a container or test
 depending on the evaluation of a script configured via the `{EnabledIf}` or
 `{DisabledIf}` annotation. Scripts can be written in JavaScript, Groovy, or any other
 scripting language for which there is support for the Java Scripting API, defined by JSR
 223.
 
-WARNING: Conditional test execution via `{EnabledIf}` and `{DisabledIf}` is currently an
-_experimental_ feature. Consult the table in <<api-evolution-experimental-apis>> for
-details.
-
 TIP: If the logic of your script depends only on the current operating system, the
 current Java Runtime Environment version, a particular JVM system property, or a
 particular environment variable, you should consider using one of the built-in
@@ -1031,10 +1032,9 @@ for parameterized tests that accept a single argument.
 * `{NullAndEmptySource}`: a _composed annotation_ that combines the functionality of
   `@NullSource` and `@EmptySource`.
 
-If you need to supply multiple varying types of _empty_ or _blank_ strings to a
-parameterized test, you can achieve that using
-<<writing-tests-parameterized-tests-sources-ValueSource>> -- for example,
-`@ValueSource(strings = {" ", " ", "\t", "\n"})`.
+If you need to supply multiple varying types of _blank_ strings to a parameterized test,
+you can achieve that using <<writing-tests-parameterized-tests-sources-ValueSource>> --
+for example, `@ValueSource(strings = {"{nbsp}", "{nbsp}{nbsp}{nbsp}", "\t", "\n"})`.
 
 You can also combine `@NullSource`, `@EmptySource`, and `@ValueSource` to test a wider
 range of `null`, _empty_, and _blank_ input. The following example demonstrates how to
@@ -1571,6 +1571,95 @@ include::{testDir}/example/DynamicTestsDemo.java[tags=user_guide]
 ----
 
 
+[[writing-tests-declarative-timeouts]]
+=== Timeouts
+
+.Declarative timeouts are an experimental feature
+WARNING: You're invited to give it a try and provide feedback to the JUnit team so they
+can improve and eventually <<api-evolution, promote>> this feature.
+
+The `@Timeout` annotation allows to declare that a test, test factory, test template, or
+lifecycle method should fail if its execution time exceeds a given duration, and
+optionally a time unit (seconds are used by default).
+
+The following example shows how `@Timeout` is applied to lifecycle and test methods.
+
+[source,java]
+----
+include::{testDir}/example/TimeoutDemo.java[tags=user_guide]
+----
+
+Contrary to the `assertTimeoutPreemptively()` assertion, the execution of the annotated
+method proceeds in the main thread of the test. If the timeout is exceeded, the main
+thread is interrupted from another thread. This is done to ensure interoperability with
+frameworks such as Spring that make extensive use of mechanisms that are sensitive to the
+currently running thread (e.g. `ThreadLocals`).
+
+To apply the same timeout to all test methods within a test class and all its `@Nested`
+classes, you can declare the `@Timeout` annotation on the class level. It will then be
+applied to all test, test factory, and test template methods within that class and its
+`@Nested` classes unless overridden by a `@Timeout` annotation on a method or `@Nested`
+class. Please note that `@Timeout` annotations declared on the class level are not
+applied to lifecycle methods.
+
+Declaring `@Timeout` on a test factory method checks that the method returns within the
+specified duration but does verify the execution time of the returned `DynamicTests`.
+Please use `assertTimeout()`/`assertTimeoutPreemptively()` for that purpose.
+
+If `@Timeout` is present on a test template method, such as a method annotated with
+`@RepeatedTest` or `@ParameterizedTest`, each invocation is checked to finish within the
+given timeout.
+
+The following <<running-tests-config-params, configuration parameters>> can be used to
+specify global timeouts for all methods of a certain category unless they or an enclosing
+test class is annotated with `@Timeout`:
+
+`junit.jupiter.execution.timeout.default`::
+    Default timeout for all testable and lifecycle methods
+`junit.jupiter.execution.timeout.testable.method.default`::
+    Default timeout for all testable methods
+`junit.jupiter.execution.timeout.test.method.default`::
+    Default timeout for `@Test` methods
+`junit.jupiter.execution.timeout.testtemplate.method.default`::
+    Default timeout for `@TestTemplate` methods
+`junit.jupiter.execution.timeout.testfactory.method.default`::
+    Default timeout for `@TestFactory` methods
+`junit.jupiter.execution.timeout.lifecycle.method.default`::
+    Default timeout for all lifecycle methods
+`junit.jupiter.execution.timeout.beforeall.method.default`::
+    Default timeout for `@BeforeAll` methods
+`junit.jupiter.execution.timeout.beforeeach.method.default`::
+    Default timeout for `@BeforeEach` methods
+`junit.jupiter.execution.timeout.aftereach.method.default`::
+    Default timeout for `@AfterEach` methods
+`junit.jupiter.execution.timeout.afterall.method.default`::
+    Default timeout for `@AfterAll` methods
+
+More specific configuration parameters override less specific ones. For example,
+`junit.jupiter.execution.timeout.test.method.default` overrides
+`junit.jupiter.execution.timeout.testable.method.default` which overrides
+`junit.jupiter.execution.timeout.default`.
+
+The values of such configuration parameters must be in the following, case-insensitive
+format: `<number> [ns|μs|ms|s|m|h|d]`. The space between the number and the unit may be
+omitted. Specifying no unit is equivalent to using seconds.
+
+.Example timeout configuration parameter values
+[cols="20,80"]
+|===
+| Parameter value | Equivalent annotation
+
+| `42`            | `@Timeout(42)`
+| `42 ns`         | `@Timeout(value = 42, unit = NANOSECONDS)`
+| `42 μs`         | `@Timeout(value = 42, unit = MICROSECONDS)`
+| `42 ms`         | `@Timeout(value = 42, unit = MILLISECONDS)`
+| `42 s`          | `@Timeout(value = 42, unit = SECONDS)`
+| `42 m`          | `@Timeout(value = 42, unit = MINUTES)`
+| `42 h`          | `@Timeout(value = 42, unit = HOURS)`
+| `42 d`          | `@Timeout(value = 42, unit = DAYS)`
+|===
+
+
 [[writing-tests-parallel-execution]]
 === Parallel Execution