Overview
Warning
| This plugin is under minimal maintenance and no new features are planned for it. |
What is it?
This is a custom plugin for Gradle to support defining and invoking unit tests. It provides the following features.
-
A DSL for defining your unit test processes, including variations called flavours, defaulting to
Debug
andRelease
. -
Automatic definition of tasks for invoking your unit test processes.
-
Ability to run tests according to build dependencies, or independently per-project.
-
Automatic replacement of
<flavour>
and<f>
in test definitions.
Example build script
Here is an example build script:
buildscript {
gplugins.use "unit-test:7.2.5"
}
gplugins.apply()
def extraArgs = "--stuff"
tests {
foo {
commandLine "foo/build/<Flavour>/foo_test.exe"
commandLine "--output_format=XML", extraArgs
redirectOutputToFile "foo/test_results/foo_vc10_u<f>64.xml"
}
bar {
commandLine "bar/build/<Flavour>/bar_test.exe", extraArgs
}
}
If this build script elsewhere defines a dependency on another source control module then this will result in:
-
a task
unitTestDebug
, which does nothing itself but depends on-
a task
unitTestFooDebug
which invokesfoo/build/Debug/foo_test.exe
with the arguments--output_format=XML --stuff
and redirects standard output to a filefoo/test_results/foo_vc10_ud64.xml
; -
a task
unitTestBarDebug
which invokesbar/build/Debug/bar_test.exe
with the arguments--stuff
(and leaves standard output as normal); and -
all
unitTestDebug
tasks on dependent modules
-
-
a similar task named
unitTestRelease
To run only the tests for one project, and not run the tests for dependent modules, run Gradle
with the -a
option and specify the test task using the project path. For example, gw -a :someProject:testFoo
.
DSL Guide
tests
This is a container for test definitions. The first level below tests
defines the names of the
tests. By default each test definition applies to all flavours (e.g. Debug and Release).
commandLine
This method defines the command line for the unit test process. You can call this method any number of times to append extra parts to the command-line, and the method accepts any number of arguments.
Wherever <flavour>
appears in the command line, it will be replaced with the corresponding
flavour (for example, Debug
or Release
) converted to lower case. Similarly <Flavour>
will be
replaced with only the first letter in upper case, and <FLAVOUR>
with all letters in upper case.
Wherever <f>
appears in the command line, it will be replaced with a single character, the first
letter of the flavour in lower case (for example, d
or r
), and <F>
will be replaced with
the first letter in upper case.
The first argument to this method is the executable and it should be specified in one of the following ways.
-
As a filename with no path part, to be found on the system
PATH
; for example, "cmd.exe
" -
As a relative path, which is taken relative to the project’s
projectDir
; for example, "path/to/test.exe
". -
As an absolute path; for example, "
${project.projectDir}/../path/to/integration_test.exe
".
→ Call this method at least once.
workingDir
This method and property allow you to set the working directory for the unit test executable.
Note
| If the commandLine specifies a rellative path, it is not relative to this working directory. This property only sets the "current directory" for the test process when it is runnning. |
tests {
foo {
commandLine "foo/build/<Flavour>/foo_test.exe"
commandLine "--output_format=XML"
workingDir = new File(projectDir, "foo/test_results/foo_vc10_u<f>64.xml")
// or workingDir new File("${projectDir}/foo/test_results/foo_vc10_u<f>64.xml")
// or workingDir file("foo/test_results/foo_vc10_u<f>64.xml")
}
}
redirectOutputToFile
Warning
| This method is deprecated and will be remoted in a future version of the Holy Gradle.
Please use setStandardOutput and setStandardOutputTee instead. Note that those methods
accept a File , not String , and are not automatically treated as relative to the projectDir . |
This method allows you to have the output of the unit test process redirected to a file of your choice.
As above you can use <flavour>
, <f>
, and so on.
→ Call this method at most once.
setStandardOutput
This settable property allows you to have the output of the unit test process redirected to a file of your choice.
The value for this property can be a Java File
object, a string, or other types as documented
for the Gradle Project#file
method. The value is intepreted relative to the projectDir
,
unless you supply a File
with an absolute path.
As above you can use <flavour>
, <f>
, and so on in the strings used to construct the File
objects.
tests {
foo {
commandLine "foo/build/<Flavour>/foo_test.exe"
commandLine "--output_format=XML"
standardOutput = "foo/test_results/foo_vc10_u<f>64.xml")
// or standardOutput = new File(rootProject.projectDir, "foo/test_results/foo_vc10_u<f>64.xml")
}
}
→ Set this property at most once.
setErrorOutput
This settable property is similar to setStandardOutput but it redirects the "standard error" stream for the test process, instead of the "standard output" stream. You can redirect both the standard error and standard output streams to separate files.
Warning
| Do not attempt to redirect standard error and standard output to the same file. This will result in unpredictable mixing of output, and may also result in exceptions if Gradle tries to close one stream when the application is still writing to the other — because they are really the same stream. |
→ Set this property at most once.
setStandardOutputTee
This settable property is similar to setStandardOutput but it redirects output to a file and also outputs as normal, at the same time.
tests {
foo {
commandLine "foo/build/<Flavour>/foo_test.exe"
commandLine "--output_format=XML"
standardOutputTee = "foo/test_results/foo_vc10_u<f>64.xml"
}
}
→ Set this property at most once.
setErrorOutputTee
This settable property is similar to setStandardOutputTee but it redirects the "standard error" stream for the test process, instead of the "standard output" stream. You can redirect both the standard error and standard output streams to separate files.
Warning
| Do not attempt to redirect standard error and standard output to the same file. This will result in unpredictable mixing of output, and may also result in exceptions if Gradle tries to close one stream when the application is still writing to the other — because they are really the same stream. |
flavour
This method allows you to restrict this unit test to a subset of flavours. This method takes any number of arguments, each one specifying the name of a flavour for which this unit test process will be run.
tests {
blah {
commandLine "blah /build/<flavour>/blah.exe"
flavour "Debug"
}
}
The above code allows you to filter out flavours for individual unit tests, as opposed to
testFlavours
which defines the flavours globally for the build script.
→ Call this method any number of times.
testFlavours
This is a container to allow you to specify the unit test flavours explicitly. By default, if you do not use this DSL the plugin will behave as if you had specified the following.
testFlavours {
Debug
Release
}
Tasks
unitTest<flavour>
If for example you are using the default flavours you will have tasks named unitTestDebug
and unitTestRelease
. Each task will cause the unit test processes for this module and all
dependent modules to be run.
To run the tests for this module, but not those for other modules, use the -a
argument to Gradle.