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 and Release.

  • 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 invokes foo/build/Debug/foo_test.exe with the arguments --output_format=XML --stuff and redirects standard output to a file foo/test_results/foo_vc10_ud64.xml;

    • a task unitTestBarDebug which invokes bar/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.