第二十三章. 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'
        }
    }
}

下表列出了一些重要的源集属性。你可以在 API 文档中找到更多有关 SourceSet 的详细信息。
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 进程中执行，与主构建进程隔离。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 属性，用于控制测试失败时的行为。测试任务始终执行它检测到的每个测试，如果 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 在执行测试之前等待调试器连接到它的 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 任务选项进行启用。
This can also be enabled at invocation time via the --debug-jvm task option.

从 Gradle 1.10 开始，可以基于测试名称模式，只包含特定测试。过滤是与测试类包含或排除所不同的一种机制，接下来的段落中将会对其详细介绍（-Dtest.single， test.include 和其他相关的）。后者基于文件，例如测试实现类的物理位置。文件级测试选择不支持的许多有趣的场景，都可以用测试级过滤来实现。其中一些 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 文件。你可以设置自定义包含或排除哪些类，只有这些类才会被扫描。根据所使用的测试框架（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 来禁用它。这将使测试任务仅使用包含或排除来查找测试类。如果 scanForTestClasses 被禁用，并且没有指定包含或排除模式，则使用相应的默认值。对于包含的默认值是 “**/*Tests.class”，“**/*Test.class”，而排除的默认值是 “**/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 任务允许指定要包含和排除的 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]你可以在测试任务中配置应该包含在测试执行中或从测试执行中排除的测试组。
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.

还有一个独立的 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 类型结合了多个测试任务的结果，并需要汇总各个测试类的结果。这意味着如果给定的测试类由多个测试任务执行，那么测试报告将包括该类的执行结果，但很难区分这个类的单独执行和它们的输出。
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 属性。当生成档案时，相应的 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 之间共享清单信息。
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 对象来描述。
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 语句中所声明的顺序进行合并。如果基本的清单和合并清单都定义了同一个键的值，那么默认情况下会采用要合并的清单的值。你可以通过添加 eachEntry 来完全自定义结果清单的每一个实体的合并行为，它让你可以访问 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

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

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