- JUnit 5 introduced a newer set of APIs to write and launch tests. It also introduced - the concept of test engines. Test engines decide which classes are considered as testcases - and how they are executed. JUnit 5 supports running tests that have been written using - JUnit 4 constructs as well as tests that have been written using JUnit 5 constructs. - For more details about JUnit 5 itself, please refer to the JUnit 5 project's documentation at - https://junit.org/junit5/. + JUnit 5 introduced a newer set of APIs to write and launch tests. It also introduced the concept + of test engines. Test engines decide which classes are considered as testcases and how they are + executed. JUnit 5 supports running tests that have been written using JUnit 4 constructs as well + as tests that have been written using JUnit 5 constructs. For more details about JUnit 5 + itself, please refer to the JUnit 5 project's documentation + at https://junit.org/junit5/.
- The goal of this junitlauncher task is to allow launching the JUnit 5
- test launcher and building the test requests so that the selected tests can then be parsed
- and executed by the test engine(s) supported by JUnit 5. This task in itself does not
- understand what a test case is nor does it execute the tests itself.
+ The goal of this junitlauncher task is to allow launching the JUnit 5 test launcher
+ and building the test requests so that the selected tests can then be parsed and executed by the
+ test engine(s) supported by JUnit 5. This task in itself does not understand what a test
+ case is nor does it execute the tests itself.
- Note: This task depends on external libraries not included - in the Apache Ant distribution. See - Library Dependencies for more information. + Note: This task depends on external libraries not included in the Apache Ant + distribution. See Library Dependencies for + more information.
- Note: - You must have the necessary JUnit 5 libraries in the classpath of the tests. At the time of - writing this documentation, the list of JUnit 5 platform libraries that are necessary to run the tests - are: + Note: You must have the necessary JUnit 5 libraries in the classpath of the + tests. At the time of writing this documentation, the list of JUnit 5 platform libraries that + are necessary to run the tests are: +
+- Depending on the test engine(s) that you want to use in your tests, you will further need the following - libraries in the classpath + Depending on the test engine(s) that you want to use in your tests, you will further need the + following libraries in the classpath
- For junit-vintage engine:
+ For junit-vintage
engine:
+
- For junit-jupiter engine:
+ For junit-jupiter
engine:
+
- To have these in the test classpath, you can follow either of the following approaches: + To have these in the test classpath, you can follow either of the following approaches: +
+ant-junitlauncher.jar in ANT_HOME/lib
- directory
- ant-junitlauncher.jar in the ANT_HOME/lib directory and include all
- other relevant jars in the classpath by passing them as a -lib option, while invoking Ant
-
- Tests are defined by nested elements like test,
- testclasses tags (see nested
- elements).
test, testclasses tags
+ (see nested elements).
+
| Attribute | -Description | -Required | +Attribute | +Description | +Required |
|---|---|---|---|---|---|
| haltOnFailure | -A value of true implies that build has to stop
- if any failure occurs in any of the tests. JUnit 5 classifies failures
- as both assertion failures as well as exceptions that get thrown during
- test execution. As such, this task too considers both these cases as
- failures and doesn't distinguish one from another.
+ | haltOnFailure | +A value of trueimplies that build has to stop if any failure occurs in any of + the tests. JUnit 4+ classifies failures as both assertion failures as well as exceptions + that get thrown during test execution. As such, this task too considers both these cases + as failures and doesn't distinguish one from another. |
- No; default is false. |
+ No; default is false |
| failureProperty | -The name of a property to set in the event of a failure + | failureProperty | +The name of a property to set in the event of a failure (exceptions in tests are considered failures as well). | -No. | +No |
- The nested <classpath> element that represents a
- PATH like structure can be used to configure
- the task to use this classpath for finding and running the tests. This classpath
- will be used for:
+ The nested <classpath> element that represents
+ a PATH like structure can be used to configure the task to use
+ this classpath for finding and running the tests. This classpath will be used for:
+
classpath element isn't configured for the task, then the classpath of
-Ant itself will be used for finding the test classes and JUnit 5 libraries.
-
+
+ If the classpath element isn't configured for the task, then the classpath of Ant
+ itself will be used for finding the test classes and JUnit 5 libraries.
- The junitlauncher task can be configured with listener(s) to listen
- to test execution events (such as a test execution starting, completing etc...). The listener
- is expected to be a class which implements the org.junit.platform.launcher.TestExecutionListener.
- This TestExecutionListener interface is an API exposed by the JUnit 5 platform APIs and isn't
- specific to Ant. As such, you can use any existing implementation of TestExecutionListener in
- this task.
+ The junitlauncher task can be configured with listener(s) to listen to
+ test execution events (such as a test execution starting, completing etc...). The listener is
+ expected to be a class which implements
+ the org.junit.platform.launcher.TestExecutionListener.
+ This TestExecutionListener interface is an API exposed by the JUnit 5
+ platform APIs and isn't specific to Ant. As such, you can use any existing implementation
+ of TestExecutionListener in this task.
- junitlauncher provides a way where the test execution results can be formatted and presented
- in a way that's customizable. The task allows for configuring test result formatters, through the use of
- listener element. As noted previously, the listener element expects the listener
- to implement the org.junit.platform.launcher.TestExecutionListener interface. Typically, result
- formatters need a bit more configuration details to be fed to them, during the test execution - details
- like where to write out the formatted result. Any such listener can optionally implement
- the org.apache.tools.ant.taskdefs.optional.junitlauncher.TestResultFormatter interface. This interface
- is specific to Ant junitlauncher task and it extends the org.junit.platform.launcher.TestExecutionListener
- interface
+ junitlauncher provides a way where the test execution results can be formatted and
+ presented in a way that's customizable. The task allows for configuring test result formatters,
+ through the use of listener element. As noted previously, the listener
+ element expects the listener to implement
+ the org.junit.platform.launcher.TestExecutionListener
+ interface. Typically, result formatters need a bit more configuration details to be fed to them,
+ during the test execution—details like where to write out the formatted result. Any such
+ listener can optionally implement
+ the org.apache.tools.ant.taskdefs.optional.junitlauncher.TestResultFormatter
+ interface. This interface is specific to Ant junitlauncher task and it extends
+ the org.junit.platform.launcher.TestExecutionListener interface
- The junitlauncher task comes with the following pre-defined test result formatter types:
+ The junitlauncher task comes with the following pre-defined test result formatter
+ types:
+
legacy-plain : This formatter prints a short statistics line for all test cases.
+ legacy-plain: This formatter prints a short statistics line for all test + cases.
legacy-brief : This formatter prints information for tests that failed or were skipped.
+ legacy-brief: This formatter prints information for tests that failed or were + skipped.
legacy-xml : This formatter prints statistics for the tests in xml format.
+ legacy-xml: This formatter prints statistics for the tests in XML format.
junit task's formatters used to do. Furthermore, the legacy-xml formatters
-generates the XML to comply with the same schema that the junit task's XML formatter used to follow.
-As a result, the XML generated by this formatter, can be used as-is by the junitreport task.
-
+
+ Note: Each of these formatters named legacy
try to format the results
+ similar to what the junit task's formatters used to do. Furthermore,
+ the legacy-xml
formatter generates the XML to comply with the same schema that
+ the junit task's XML formatter used to follow. As a result, the XML generated by
+ this formatter, can be used as-is by the junitreport task.
listener element supports the following attributes:
-
-| Attribute | -Description | -Required | +Attribute | +Description | +Required |
|---|---|---|---|---|---|
| type | -Use a predefined formatter (either
- legacy-xml, legacy-plain or legacy-brief).
- |
- Exactly one of these | +type | +Use a predefined formatter (either legacy-xml, legacy-plain+ or legacy-brief). |
+ Exactly one of these |
| classname | -Name of a listener class which implements org.junit.platform.launcher.TestExecutionListener
- or the org.apache.tools.ant.taskdefs.optional.junitlauncher.TestResultFormatter interface
+ | classname | +Name of a listener class which
+ implements org.junit.platform.launcher.TestExecutionListener or
+ the org.apache.tools.ant.taskdefs.optional.junitlauncher.TestResultFormatter
+ interface
|
||
| resultFile | -The file name to which the formatted result needs to be written to. This attribute is only
- relevant
- when the listener class implements the org.apache.tools.ant.taskdefs.optional.junitlauncher.TestResultFormatter
+ | resultFile | +
+ The file name to which the formatted result needs to be written to. This attribute is
+ only relevant when the listener class implements
+ the org.apache.tools.ant.taskdefs.optional.junitlauncher.TestResultFormatter
interface.
- If no value is specified for this attribute and the listener implements the
-
+ If no value is specified for this attribute and the listener implements
+ the |
- No | +No |
| sendSysOut | -If set to true then the listener will be passed the stdout content
- generated by the test(s). This attribute is relevant only if the listener
- class implements the org.apache.tools.ant.taskdefs.optional.junitlauncher.TestResultFormatter
- interface.
- |
- No; defaults to false |
+ sendSysOut | +If set to truethen the listener will be passed the stdout content
+ generated by the test(s). This attribute is relevant only if the listener class
+ implements
+ the org.apache.tools.ant.taskdefs.optional.junitlauncher.TestResultFormatter
+ interface. |
+ No; defaults to false |
| sendSysErr | -If set to true then the listener will be passed the stderr content
- generated by the test(s). This attribute is relevant only if the listener
- class implements the org.apache.tools.ant.taskdefs.optional.junitlauncher.TestResultFormatter
- interface.
- |
- No; defaults to false |
+ sendSysErr | +If set to truethen the listener will be passed the stderr content
+ generated by the test(s). This attribute is relevant only if the listener class
+ implements
+ the org.apache.tools.ant.taskdefs.optional.junitlauncher.TestResultFormatter
+ interface. |
+ No; defaults to false |
| if | -Only use this listener if the named property is set. - | -No | +if | +Only use this listener if the named property is + set. | +No |
| unless | -Only use this listener if the named property is - not - set. - | -No | +unless | +Only use this listener if the named property + is not set. | +No |
listener element supports the following attributes:
Defines a single test class.
-| Attribute | -Description | -Required | +Attribute | +Description | +Required |
|---|---|---|---|---|---|
| name | -Fully qualified name of the test class. | -Yes | +name | +Fully qualified name of the test class. | +Yes |
| methods | -Comma-separated list of names of test case methods to execute. - If this is specified, then only these test methods from the test class will be - executed. - | -No | +methods | +Comma-separated list of names of test case methods to execute. If this is specified, + then only these test methods from the test class will be executed. | +No |
| haltOnFailure | -Stop the build process if a failure occurs during the test
- run (exceptions are considered as failures too).
- Overrides value set on junitlauncher element.
- |
- No | +haltOnFailure | +Stop the build process if a failure occurs during the test run (exceptions are
+ considered as failures too). Overrides value set on junitlauncher
+ element. |
+ No |
| failureProperty | -The name of a property to set in the event of a failure
- (exceptions are considered failures as well). Overrides value set on
- junitlauncher element.
- |
- No | +failureProperty | +The name of a property to set in the event of a failure (exceptions are considered
+ failures as well). Overrides value set on junitlauncher element. |
+ No |
| outputDir | -Directory to write the reports to. | -No; default is the base directory of the project. | +outputDir | +Directory to write the reports to. | +No; default is the base directory of the project. |
| if | -Only run this test if the named property is set. - | -No | +if | +Only run this test if the named property is + set. | +No |
| unless | -Only run this test if the named property is not - set. - | -No | +unless | +Only run this test if the named property + is not set. | +No |
listener element supports the following attributes:
Define a number of tests based on pattern matching.
- testclasses collects the included resources from any number
- of nested Resource Collections. It then
- selects each resource whose name ends in .class. These classes are then passed on to the
- JUnit 5 platform for it to decide and run them as tests.
+ testclasses collects the included resources
+ from any number of nested Resource
+ Collections. It then selects each resource whose name ends in .class. These
+ classes are then passed on to the JUnit 5 platform for it to decide and run them as tests.
| Attribute | -Description | -Required | +Attribute | +Description | +Required |
|---|---|---|---|---|---|
| haltOnFailure | -Stop the build process if a failure occurs during the test
- run (exceptions are considered as failures too).
- Overrides value set on junitlauncher element.
- |
- No | +haltOnFailure | +Stop the build process if a failure occurs during the test run (exceptions are
+ considered as failures too). Overrides value set on junitlauncher
+ element. |
+ No |
| failureProperty | -The name of a property to set in the event of a failure
- (exceptions are considered failures as well). Overrides value set on
- junitlauncher element.
- |
- No | +failureProperty | +The name of a property to set in the event of a failure (exceptions are considered
+ failures as well). Overrides value set on junitlauncher element. |
+ No |
| outputDir | -Directory to write the reports to. | -No; default is the base directory of the project. | +outputDir | +Directory to write the reports to. | +No; default is the base directory of the project. |
| if | -Only run the tests if the named property is set. - | -No | +if | +Only run the tests if the named property is + set. | +No |
| unless | -Only run the tests if the named property is not - set. - | -No | +unless | +Only run the tests if the named property + is not set. | +No |
- testclasses can define their own listeners via nested listener elements.
+ testclasses can define their own listeners via nested listener
+ elements.
listener element supports the following attributes:
<junitlauncher>
<classpath refid="test.classpath"/>
<test name="org.myapp.SimpleTest"/>
-</junitlauncher>
-
-
+</junitlauncher>
- Launches the JUnit 5 platform to run the org.myapp.SimpleTest test
+ Launches the JUnit 5 platform to run the org.myapp.SimpleTest test
@@ -418,20 +418,20 @@ The listener element supports the following attributes:
- Launches the JUnit 5 platform to run the org.myapp.SimpleTest and the
- org.myapp.AnotherTest tests. The build process will be stopped if any
- test, in the org.myapp.SimpleTest, fails.
+ Launches the JUnit 5 platform to run the org.myapp.SimpleTest and
+ the org.myapp.AnotherTest tests. The build process will be stopped if any test, in
+ the org.myapp.SimpleTest, fails.
<junitlauncher>
<classpath refid="test.classpath"/>
<test name="org.myapp.SimpleTest" methods="testFoo, testBar"/>
-</junitlauncher>
-
+</junitlauncher>
+
- Launches the JUnit 5 platform to run only the testFoo and testBar methods of the
- org.myapp.SimpleTest test class.
+ Launches the JUnit 5 platform to run only the testFoo and testBar
+ methods of the org.myapp.SimpleTest test class.
@@ -443,12 +443,12 @@ The listener element supports the following attributes:
<include name="org/example/**/tests/**/"/>
</fileset>
</testclasses>
-</junitlauncher>
-
+</junitlauncher>
- Selects any .class files that match the org/example/**/tests/**/ fileset
- filter, under the ${build.classes.dir} and passes those classes to the JUnit 5 platform for
+ Selects any .class files that match
+ the org/example/**/tests/**/ fileset filter, under
+ the ${build.classes.dir} and passes those classes to the JUnit 5 platform for
execution as tests.
listener element supports the following attributes:
<listener type="legacy-xml" sendSysOut="true" sendSysErr="true"/>
<listener type="legacy-plain" sendSysOut="true" />
</testclasses>
-</junitlauncher>
-
+</junitlauncher>
- Selects any .class files that match the org/example/**/tests/**/ fileset
- filter, under the ${build.classes.dir} and passes those classes to the JUnit 5 platform for
- execution as tests. Test results will be written out to the ${output.dir} by the
- legacy-xml and legacy-plain formatters, in separate files.
- Furthermore, both the legacy-xml and the legacy-plain
- listeners, above, are configured to receive the standard output content generated by the tests.
- The legacy-xml listener is configured to receive standard error content as well.
-
+ Selects any .class files that match
+ the org/example/**/tests/**/ fileset filter, under
+ the ${build.classes.dir} and passes those classes to the JUnit 5 platform for
+ execution as tests. Test results will be written out to the ${output.dir} by
+ the legacy-xml
and legacy-plain
formatters, in separate files. Furthermore, both
+ the legacy-xml
and the legacy-plain
listeners, above, are configured to receive
+ the standard output content generated by the tests. The legacy-xml
listener is
+ configured to receive standard error content as well.