The Java Plugin

The Java plugin also adds a number of tasks which form a lifecycle for the project:

The following diagram shows the relationships between these tasks.

Figure: Java plugin - tasks

You configure the project layout by configuring the appropriate source set. This is discussed in more detail in the following sections. Here is a brief example which changes the main Java and resource source directories.

sourceSets {
    main {
        java {
            srcDirs = ['src/java']
        }
        resources {
            srcDirs = ['src/resources']
        }
    }
}

Figure: Java plugin - dependency configurations

For each source set you add to the project, the Java plugins adds the following dependency configurations:

String docsDirName: :_The name of the directory to generate documentation into, relative to the build directory._ Default value: docs

These properties are provided by convention objects of type JavaPluginConvention, and BasePluginConvention.

The following table lists some of the important properties of a source set. You can find more details in the API documentation for SourceSet.

To define a new source set, you simply reference it in the sourceSets { } block. Here’s an example:

sourceSets {
    intTest
}

When you define a new source set, the Java plugin adds some dependency configurations for the source set, as shown in the section called “SourceSet dependency configurations”. You can use these configurations to define the compile and runtime dependencies of the source set.

sourceSets {
    intTest
}

dependencies {
    intTestCompile 'junit:junit:4.12'
    intTestRuntime 'org.ow2.asm:asm-all:4.0'
}

The Java plugin also adds a number of tasks which assemble the classes for the source set, as shown in the section called “SourceSet Tasks”. For example, for a source set called intTest, compiling the classes for this source set is done by running gradle intTestClasses.

> gradle intTestClasses
:compileIntTestJava
:processIntTestResources
:intTestClasses

BUILD SUCCESSFUL in 0s
2 actionable tasks: 2 executed

Adding a JAR containing the classes of a source set:

task intTestJar(type: Jar) {
    from sourceSets.intTest.output
}

Generating Javadoc for a source set:

task intTestJavadoc(type: Javadoc) {
    source sourceSets.intTest.allJava
}

Adding a test suite to run the tests in a source set:

task intTest(type: Test) {
    testClassesDirs = sourceSets.intTest.output.classesDirs
    classpath = sourceSets.intTest.runtimeClasspath
}

By default, the Java compiler runs in the Gradle process. Setting options.fork to true causes compilation to occur in a separate process. In the case of the Ant javac task, this means that a new process will be forked for each compile task, which can slow down compilation. Conversely, Gradle’s direct compiler integration (see above) will reuse the same compiler process as much as possible. In both cases, all fork options specified with options.forkOptions will be honored.

Tests are executed in a separate JVM, isolated from the main build process. The Test task’s API allows you some control over how this happens.

There are a number of properties which control how the test process is launched. This includes things such as system properties, JVM arguments, and the Java executable to use.

You can specify whether or not to execute your tests in parallel. Gradle provides parallel test execution by running multiple test processes concurrently. Each test process executes only a single test at a time, so you generally don’t need to do anything special to your tests to take advantage of this. The maxParallelForks property specifies the maximum number of test processes to run at any given time. The default is 1, that is, do not execute the tests in parallel.

The test process sets the org.gradle.test.worker system property to a unique identifier for that test process, which you can use, for example, in files names or other resource identifiers.

You can specify that test processes should be restarted after it has executed a certain number of test classes. This can be a useful alternative to giving your test process a very large heap. The forkEvery property specifies the maximum number of test classes to execute in a test process. The default is to execute an unlimited number of tests in each test process.

The task has an ignoreFailures property to control the behavior when tests fail. The Test task always executes every test that it detects. It stops the build afterwards if ignoreFailures is false and there are failing tests. The default value of ignoreFailures is false.

The testLogging property allows you to configure which test events are going to be logged and at which detail level. By default, a concise message will be logged for every failed test. See TestLoggingContainer for how to tune test logging to your preferences.

Projects with large test suites can take a long time to execute even though a failure occurred early on leading to unnecessary wait times (especially on CI). To short circuit this behavior, the Test.getFailFast() property allows you to cause the test task to fail after the first test failure instead of running all tests. When this property is true, the resulting output will only show the results of tests that have completed up to and including the failure. To enable this fail fast behavior in your build file, set the failFast property to true:

test {
    failFast = true
}

The --fail-fast command line option enables the behavior from the command line. An invocation looks like:

gradle integTest --fail-fast

The default value for the failFast property is false.

The test task provides a Test.getDebug() property that can be set to launch to make the JVM wait for a debugger to attach to port 5005 before proceeding with test execution.

This can also be enabled at invocation time via the --debug-jvm task option (since Gradle 1.12).

Starting with Gradle 1.10, it is possible to include only specific tests, based on the test name pattern. Filtering is a different mechanism than test class inclusion / exclusion that will be described in the next few paragraphs (-Dtest.single, test.include and friends). The latter is based on files, e.g. the physical location of the test implementation class. File-level test selection does not support many interesting scenarios that are possible with test-level filtering. Some of them Gradle handles now and some will be satisfied in future releases:

Test filtering feature has following characteristic:

test {
    filter {
        //include specific method in any of the tests
        includeTestsMatching "*UiCheck"

        //include all tests from package
        includeTestsMatching "org.gradle.internal.*"

        //include all integration tests
        includeTestsMatching "*IntegTest"
    }
}

For more details and examples please see the TestFilter reference.

Some examples of using the command line option:

This is something you can combine with continuous build using --continuous (or -t, for short) to re-execute a subset of tests immediately after every change.

gradle test --continuous --tests "com.mypackage.foo.*"

Setting a system property of taskName.single = testNamePattern will only execute tests that match the specified testNamePattern. The taskName can be a full multi-project path like :sub1:sub2:test or just the task name. The testNamePattern will be used to form an include pattern of **/testNamePattern*.class. If no tests with this pattern can be found, an exception is thrown. This is to shield you from false security. If tests of more than one subproject are executed, the pattern is applied to each subproject. An exception is thrown if no tests can be found for a particular subproject. In such a case you can use the path notation of the pattern, so that the pattern is applied only to the test task of a specific subproject. Alternatively you can specify the fully qualified task name to be executed. You can also specify multiple patterns. Examples:

The Test task detects which classes are test classes by inspecting the compiled test classes. By default it scans all .class files. You can set custom includes / excludes, only those classes will be scanned. Depending on the test framework used (JUnit / TestNG) the test class detection uses different criteria.

When using JUnit, we scan for both JUnit 3 and 4 test classes. If any of the following criteria match, the class is considered to be a JUnit test class:

When using TestNG, we scan for methods annotated with @Test.

Note that abstract classes are not executed. Gradle also scans up the inheritance tree into jar files on the test classpath.

If you don’t want to use test class detection, you can disable it by setting scanForTestClasses to false. This will make the test task only use includes / excludes to find test classes. If scanForTestClasses is false and no include / exclude patterns are specified, the defaults are **/*Tests.class, **/*Test.class and **/Abstract*.class for include and exclude, respectively.

JUnit/JUnit Platform and TestNG allow sophisticated groupings of test methods.

For grouping JUnit 4 test classes and methods JUnit 4.8 introduces the concept of categories.^[14] The test task allows the specification of the JUnit categories you want to include and exclude.

test {
    useJUnit {
        includeCategories 'org.gradle.junit.CategoryA'
        excludeCategories 'org.gradle.junit.CategoryB'
    }
}

In JUnit Platform, tagging is introduced instead of categories. You can specify the included/excluded tags as follows:

test {
    useJUnitPlatform {
        includeTags 'fast'
        excludeTags 'slow'
    }
}

The TestNG framework has a quite similar concept. In TestNG you can specify different test groups.^[15] The test groups that should be included or excluded from the test execution can be configured in the test task.

test {
    useTestNG {
        excludeGroups 'integrationTests'
        includeGroups 'unitTests'
    }
}

JUnit 5 is the latest version of the well-known JUnit test framework. Unlike its predecessor, JUnit 5 is modularized and composed of several modules:

JUnit 5 = JUnit Platform + JUnit Jupiter + JUnit Vintage

The JUnit Platform serves as a foundation for launching testing frameworks on the JVM. JUnit Jupiter is the combination of the new programming model and extension model for writing tests and extensions in JUnit 5. JUnit Vintage provides a TestEngine for running JUnit 3 and JUnit 4 based tests on the platform.

The following code enables JUnit Platform support in build.gradle:

test {
    useJUnitPlatform()
}

See Test.useJUnitPlatform() for more details.

dependencies {
    testImplementation 'org.junit.jupiter:junit-jupiter-api:5.1.0'
    testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.1.0'
}

package org.gradle.junitplatform;

import org.junit.jupiter.api.*;

public class JupiterTest {
    @Test
    public void ok() {
        System.out.println("Hello from JUnit Jupiter!");
    }
}

dependencies {
    testImplementation 'org.junit.jupiter:junit-jupiter-api:5.1.0'
    testRuntimeOnly 'org.junit.jupiter:junit-jupiter-engine:5.1.0'
    testCompileOnly 'junit:junit:4.12'
    testRuntimeOnly 'org.junit.vintage:junit-vintage-engine:5.1.0'
}

TestNG allows explicit control of the execution order of tests.

The preserveOrder property controls whether tests are executed in deterministic order. Preserving the order guarantees that the complete test (including @BeforeXXX and @AfterXXX) is run in a test thread before the next test is run. While preserving the order of tests is the default behavior when directly working with testng.xml files, the TestNG API, that is used for running tests programmatically, as well as Gradle’s TestNG integration execute tests in unpredictable order by default.^[16] Preserving the order of tests was introduced with TestNG version 5.14.5. Setting the preserveOrder property to true for an older TestNG version will cause the build to fail.

test {
    useTestNG {
        preserveOrder true
    }
}

The groupByInstance property controls whether tests should be grouped by instances. Grouping by instances will result in resolving test method dependencies for each instance instead of running the dependees of all instances before running the dependants. The default behavior is not to group tests by instances.^[17] Grouping tests by instances was introduced with TestNG version 6.1. Setting the groupByInstances property to true for an older TestNG version will cause the build to fail.

test {
    useTestNG {
        groupByInstances true
    }
}

The Test task generates the following results by default.

There is also a stand-alone TestReport task type which can generate the HTML test report from the binary results generated by one or more Test task instances. To use this task type, you need to define a destinationDir and the test results to include in the report. Here is a sample which generates a combined report for the unit tests from subprojects:

subprojects {
    apply plugin: 'java'

    // Disable the test report for the individual test task
    test {
        reports.html.enabled = false
    }
}

task testReport(type: TestReport) {
    destinationDir = file("$buildDir/reports/allTests")
    // Include the results from the `test` task in all subprojects
    reportOn subprojects*.test
}

You should note that the TestReport type combines the results from multiple test tasks and needs to aggregate the results of individual test classes. This means that if a given test class is executed by multiple test tasks, then the test report will include executions of that class, but it can be hard to distinguish individual executions of that class and their output.

Each jar or war object has a manifest property with a separate instance of Manifest. When the archive is generated, a corresponding MANIFEST.MF file is written into the archive.

jar {
    manifest {
        attributes("Implementation-Title": "Gradle",
                   "Implementation-Version": version)
    }
}

You can create stand-alone instances of a Manifest. You can use that for example, to share manifest information between jars.

ext.sharedManifest = manifest {
    attributes("Implementation-Title": "Gradle",
               "Implementation-Version": version)
}
task fooJar(type: Jar) {
    manifest = project.manifest {
        from sharedManifest
    }
}

You can merge other manifests into any Manifest object. The other manifests might be either described by a file path or, like in the example above, by a reference to another Manifest object.

task barJar(type: Jar) {
    manifest {
        attributes key1: 'value1'
        from sharedManifest, 'src/config/basemanifest.txt'
        from('src/config/javabasemanifest.txt',
             'src/config/libbasemanifest.txt') {
            eachEntry { details ->
                if (details.baseValue != details.mergeValue) {
                    details.value = baseValue
                }
                if (details.key == 'foo') {
                    details.exclude()
                }
            }
        }
    }
}

Manifests are merged in the order they are declared by the from statement. If the base manifest and the merged manifest both define values for the same key, the merged manifest wins by default. You can fully customize the merge behavior by adding eachEntry actions in which you have access to a ManifestMergeDetails instance for each entry of the resulting manifest. The merge is not immediately triggered by the from statement. It is done lazily, either when generating the jar, or by calling writeTo or effectiveManifest

You can easily write a manifest to disk.

jar.manifest.writeTo("$buildDir/mymanifest.mf")