第 二十三章. Java 插件

你可以通过配置适当的源集，来配置项目的布局。这一点将在以下各节中详细讨论。这里是如何更改main Java 和资源源目录的一个简短的例子。
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 {
            srcDir 'src/java'
        }
        resources {
            srcDir 'src/resources'
        }
    }
}

下表列出了一些重要的源集属性。你可以在 SourceSet 的 API 文档中查看更多的详细信息。
The following table lists some of the important properties of a source set. You can find more details in the API documentation for SourceSet .

要定义一个新的源集，你只需在 sourceSets { }块中引用它。下面是一个示例：
To define a new source set, you simply reference it in the sourceSets { } block. Here's an example:

sourceSets {
    intTest
}

当您定义一个新的源集时，Java 插件会为该源集添加一些依赖配置，如 表 23.6，“Java 插件 - 源集依赖项配置”所示。你可以使用这些配置来定义源集的编译和运行时的依赖。
When you define a new source set, the Java plugin adds some dependency configurations for the source set, as shown in Table 23.6, “Java plugin - source set 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.11'
    intTestRuntime 'org.ow2.asm:asm-all:4.0'
}

Java 插件还添加了大量的任务，用于组装源集的类，如 表 23.2，“Java 插件 - 源设置任务”所示。例如，对于一个被叫做 intTest的源集，你可以运行 gradle intTestClasses 来编译 int 测试类。
The Java plugin also adds a number of tasks which assemble the classes for the source set, as shown in Table 23.2, “Java plugin - source set tasks” . For example, for a source set called intTest , you can run gradle intTestClasses to compile the int test classes.

> gradle intTestClasses
:compileIntTestJava
:processIntTestResources
:intTestClasses

BUILD SUCCESSFUL

Total time: 1 secs

添加一个包含了源集的类的JAR包
Adding a JAR containing the classes of a source set:

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

为一个源集生成 Javadoc：
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) {
    testClassesDir = sourceSets.intTest.output.classesDir
    classpath = sourceSets.intTest.runtimeClasspath
}

测试在单独的 JVM中执行，与main构建进程隔离。 Test 任务的 API 可以让你控制什么时候开始。
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.

有大量的属性用于控制测试进程的启动。这包括系统属性、 JVM 参数和使用的 Java 可执行文件。
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.

你可以指定是否要并行运行你的测试。Gradle 通过同时运行多个测试进程来提供并行测试的执行。每个测试进程会依次执行一个单一的测试，所以你一般不需要对你的测试做任何的配置来利用这一点。 maxParallelForks属性指定在给定的时间可以运行的测试进程的最大数。它的默认值是 1，也就是说，不并行执行测试。
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.

测试进程程会为其将 org.gradle.test.worker系统属性设置为一个唯一标识符，这个标识符可以用于文件名称或其他资源标识符。
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.

你可以指定在执行了一定数量的测试类之后，重启那个测试进程。这是一个很有用的替代方案，让你的测试进程可以有很大的堆内存。 forkEvery属性指定了要在测试进程中执行的测试类的最大数。默认是每个测试进程中执行的测试数量不限。
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.

该任务有一个 ignoreFailures属性，用以控制测试失败时的行为。test 会始终执行它检测到的每一个测试。如果 ignoreFailures为 false，并且有测试不通过，那它会停止继续构建。 IgnoreFailures的默认值为 false。
The task has an ignoreFailures property to control the behavior when tests fail. Test 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.

testLogging属性可以配置哪些测试事件需要记录，并且使用什么样的日志级别。默认情况下，对于每个失败的测试都只会打印一个简洁的消息。请参阅 TestLoggingContainer ，查看如何把你的测试日志打印调整为你的偏好设置。
The testLogging property allows 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.

test任务提供了一个 Test.getDebug() 属性，可以设置为启动，使JVM在执行测试之前，等待一个debugger连接到它的5005端口上。
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.

这也可以在调用时通过 --debug-vm task 选项进行启用。
This can also be enabled at invocation time via the --debug-jvm task option.

从Gradle 1.10 开始，可以根据测试的名称模式，只包含指定的测试。过滤，相对于测试类的包含或排除，是一个不同的机制。它将在接下来的段落中进行描述（ -Dtest.single， test.include和friends）。后者基于文件，比如测试实现类的物理位置。file-level 的测试选择不支持的很多有趣的情况，都可以用 test-level 过滤来做到。以下这些场景中，有一些Gradle现在就可以处理，而有一些则将在未来得到实现：
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 the 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"
    }
}

有关更多的详细信息和示例，请参阅 TestFilter 的文档。
For more details and examples please see the TestFilter reference.

使用命令行选项的一些示例：
Some examples of using the command line option:

设置一个 taskName.single = testNamePattern 的系统属性将会只执行匹配 testNamePattern 的那些测试。这个 taskName 可以是一个完整的多项目路径，比如“sub1:sub2:test”，或者仅是一个任务名称。 testNamePattern 将用于形成一个“**/testNamePattern*.class”的包含模式。如果这个模式无法找到任何测试，那么将会抛出一个异常。这是为了使你不会误以为测试通过。如果执行了一个以上的子项目的测试，该模式会被应用于每一个子项目中。如果在一个特定的子项目中，找不到测试用例，那么将会抛出异常。在这种情况下你可以使用路径标记法的模式，这样该模式就会只应用于特定的子项目的测试任务中。或者你可以指定要执行的任务的完整限定名称。你还可以指定多个模式。示例：
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:

Test任务通过检查编译过的测试类来检测哪些类是测试类。默认情况下它会扫描所有的 .class文件。您可以设置自定义的includes 或 excludes，这样就只有这些类才会被扫描。根据所使用的测试框架 （JUnit 或 TestNG），会使用不同的标准进行测试类的检测。
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.

当使用 JUnit 时，我们扫描 JUnit 3 和 4 的测试类。如果满足以下的任何一个条件，这个类就被认为是一个 JUnit 测试类：
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:

当使用 TestNG 时，我们扫描所有带有 @Test注解的方法。
When using TestNG, we scan for methods annotated with @Test .

请注意，抽象类不会被执行。Gradle 还将扫描测试类路径中的 jar 文件里的继承树。
Note that abstract classes are not executed. Gradle also scan up the inheritance tree into jar files on the test classpath.

如果你不想要使用测试类检测，可以通过设置 scanForTestClasses为 false 来禁用它。这将使test任务只使用includes / excludes 来找到测试类。如果 scanForTestClasses为disabled，并且没有指定 include或exclude模式，则使用各自的默认值。对于 include 的默认值是 "**/*Tests.class"， "**/*Test.class"，而对于exclude它的默认值是 "**/Abstract*.class"。
In case you don't want to use the test class detection, you can disable it by setting scanForTestClasses to false. This will make the test task only use the includes / excludes to find test classes. If scanForTestClasses is disabled and no include or exclude patterns are specified, the respective defaults are used. For include this is "**/*Tests.class", "**/*Test.class" and the for exclude it is "**/Abstract*.class" .

JUnit 和 TestNG 可以对测试方法进行复杂的分组。
JUnit and TestNG allows sophisticated groupings of test methods.

为对Junit 测试类和方法进行分组，JUnit 4.8引入了类别的概念。 ^{[ 9]} test任务可以实现一个规范，让你include和exclude 想要的 JUnit 类别。
For grouping JUnit test classes and methods JUnit 4.8 introduces the concept of categories. ^{[ 9 ]} 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'
    }
}

TestNG 框架有一个非常相似的概念。在 TestNG 中你可以指定不同的测试组。 ^{[ 10]}应从测试执行中include或exclude的测试组，可以在test任务中配置。
The TestNG framework has a quite similar concept. In TestNG you can specify different test groups. ^{[ 10 ]} 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'
    }
}

test任务默认情况下会生成以下结果。
The Test task generates the following results by default.

您可以使用 Test.setTestReport() 方法来禁用 HTML 测试报告。目前不能禁用其他的结果。
You can disable the HTML test report using the Test.setTestReport() method. The other results currently cannot be disabled.

这里还有一个独立的 TestReport 任务类型，它可以从一个或多个 Test任务实例生成的二进制结果中生成 HTML 测试报告。要使用这个任务类型，你需要定义一个 destinationDir和要包含到报告的测试结果。这里是一个范例，从子项目的单元测试中生成一个联合报告：
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
}

你应该注意到， TestReport类型组合了多个测试任务的结果，并且需要聚合各个测试类的结果。这意味着，如果一个给定的测试类被多个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.

每个 jar 或war 对象都有一个单独的 Manifest 实例的 manifest属性。当生成archive时，相应的 MANIFEST.MF文件也会被写入进去。
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)
    }
}

您可以创建一个单独的 Manifest实例。它可以用于共享两个jar包的manifest 信息。
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
    }
}

你可以把其他的manifest 合并到任何一个 Manifest对象中。其他的manifest可能使用文件路径来描述，像上面的例子，使用对另一个 Manifest对象的引用。
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()
                }
            }
        }
    }
}

Manifest会根据在 from语句中所声明的顺序进行合并。如果基本的manifest和要合并的manifest都定义了同一个key的值，那么默认情况下会采用要合并的manifest的值。你可以通过添加 eachEntry action 来完全自定义合并行为，它可以让你对每一项生成的manifest 访问它的一个 ManifestMergeDetails 实例。这个合并操作不会在from语句中就马上被触发。它是懒执行的，不管是对于生成一个jar包，还是调用了 writeTo 或者 effectiveManifest
Manifest are merged in the order they are declared by the from statement. If the based 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

你可以很轻松地把一个manifest写入磁盘中。
You can easily write a manifest to disk.

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