第23章 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.

プロジェクトのレイアウトは、適切なソースセットを設定することでカスタマイズできます。これについては後続の節でより詳しく説明します。以下に、mainのJavaソースとリソースのソースディレクトリを変更する簡単な例を示します。

sourceSets {
    main {
        java {
            srcDir 'src/java'
        }
        resources {
            srcDir 'src/resources'
        }
    }
}

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

以下の表は、ソースセットの重要なプロパティの一覧です。 さらに詳しくは、SourceSetのAPIドキュメントをご覧ください。

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

新しいソースセットは、sourceSets { }ブロックの中でそれを参照するだけで定義できます。以下がその例です。:

sourceSets {
    intTest
}

When you define a new source set, the Java plugin adds some dependency configurations for the source set, as shown in 表23.6「Javaプラグイン - ソースセットの依存関係コンフィグレーションJava plugin - source set dependency configurations」. You can use these configurations to define the compile and runtime dependencies of the source set.

ソースセットを定義すると、Javaプラグインは、そのソースセットのために表23.6「Javaプラグイン - ソースセットの依存関係コンフィグレーションJava plugin - source set dependency configurations」で示した依存関係のコンフィグレーションを追加します。これらのコンフィグレーションを、そのソースセットのコンパイル時や実行時の依存関係を定義するために使うことができます。

sourceSets {
    intTest
}

dependencies {
    intTestCompile 'junit:junit:4.11'
    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 表23.2「Javaプラグイン - ソースセットタスクJava plugin - source set tasks」. For example, for a source set called intTest, compiling the classes for this source set is done by running gradle intTestClasses.

また、Javaプラグインは、表23.2「Javaプラグイン - ソースセットタスクJava plugin - source set tasks」に示したような、 そのソースセットのクラスを構築するためのタスクを追加します。 例えば、intTestというソースセットを追加すると、gradle intTestClassesと実行することでそのソースセットのクラスをコンパイルできるようになります。

> gradle intTestClasses
:compileIntTestJava
:processIntTestResources
:intTestClasses

BUILD SUCCESSFUL

Total time: 1 secs

Adding a JAR containing the classes of a source set:

ソースセットのクラスを含んだJARを追加します：

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

Generating Javadoc for a source set:

ソースセットのJavadocを生成します：

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
}

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で行われ、メインのビルドプロセスからは分離されます。TestタスクのAPIを使って、テストの実行を制御できます。

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.

テストプロセスの起動を制御するための多くのプロパティが用意されています。 これにはシステムプロパティや、JVMへの引数、Java実行コマンドなどが含まれます。

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.

テストが並列に実行されるかどうかを指定することができます。 Gradleでは、複数のテストプロセスを同時に実行する並列テスト実行が可能です。 各テストプロセスは一度に一つのテストだけを実行するので、通常、これを活用するために何か特別な準備をする必要はありません。 maxParallelForksプロパティで、同時に実行されるテストプロセスの最大個数を指定します。 デフォルトは1で、これはテストが並列実行されないということです。

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.

テストプロセスでは、そのテストプロセスの一意な識別子であるorg.gradle.test.workerシステムプロパティが設定されます。 これは例えばファイル名の一部や、その他のリソースの識別子などに利用することができます。

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.

一定のテストクラスを実行し終わったら、そのテストプロセスが再起動されるように指定することができます。 これは、テストプロセスに巨大なヒープを割り当てることに対する便利な代替手段になりえます。 forkEveryプロパティは、一つのテストプロセス内で実行されるテストクラスの最大数を指定します。 デフォルトでは各テストプロセスで無制限な数のテストを実行できます。

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.

このタスクは、テストが失敗したときの振る舞いを制御するignoreFailuresプロパティを持っています。 Testはいつも見つけたテストをすべて実行します。 ignoreFailuresがfalseのとき、失敗したテストがあるとそれ以降のビルドは停止されます。 ignoreFailuresのデフォルト値は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.

testLoggingプロパティで、どのテストイベントを、どのログレベルでログに出すべきか設定することができます。 デフォルトでは、全ての失敗したテストに対して簡潔なメッセージがログ出力されます。好みに応じてテストログを設定する方法については、TestLoggingContainerを参照してください。

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:

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:

taskName.single = testNamePatternというシステムプロパティを設定すると、指定されたtestNamePatternにマッチするテストだけが実行されます。 taskNameには、":sub1:sub2:test"のような完全なマルチプロジェクトパスか、単なるタスク名が使えます。 testNamePatternは、"**/testNamePattern*.class"という形式のincludesパターンを構成するのに使われます。 このパターンでテストが一つも見つからない場合は例外が発生します。 これは手違いによる偽りの安心を防ぐためです。 複数のサブプロジェクトに対してテストが実行される場合、パターンは各サブプロジェクトに適用されます。 ある一つのサブプロジェクトでテストが見つからなかった場合でも例外が発生します。 このような場合は、パターンのパス記法を使って、パターンが特定のサブプロジェクトのtestタスクだけに適用されるようにできます。 あるいは、完全修飾タスク名を使って実行するタスクを指定することも可能です。 パターンは複数指定することもできます。以下は実例です：

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.

Testタスクは、コンパイル済みのtestクラスを調べて、どのクラスがテストクラスかを見つけだします。 デフォルトでは、すべての.classファイルがスキャンされます。 カスタムの includes / excludes を設定して、特定のクラスだけをスキャンするようにもできます。 テストクラスの検出には、使用するテストフレームワーク(JUnit / TestNG)によって異なる基準が使われます。

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:

JUnitを使っている場合は、JUnit 3と4両方のテストクラスをスキャンします。 以下のいずれかの基準に合致する場合、そのクラスはJUnitのテストクラスだと見なされます：

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

TestNGを使っている場合は、@Testアノテーションが付いたメソッドをスキャンします。

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

抽象クラスは実行されないことに注意してください。 Gradleは、testクラスパス上のjarファイルに含まれる継承ツリーもスキャンします。

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.

上記のテストクラス検出を使いたくないときは、scanForTestClassesをfalseに設定することで、これを無効にすることができます。 この場合、testタスクがテストクラスを探すときにはincludes / excludesだけが使われます。 scanForTestClassesが無効になっていて、かつincludesやexcludesパターンが指定されていないときは、 デフォルトとしてincludesには"**/*Tests.class", "**/*Test.class"、 そしてexcludesには"**/Abstract*.class"が使われます。

JUnit and TestNG allows sophisticated groupings of test methods.

For grouping JUnit test classes and methods JUnit 4.8 introduces the concept of categories. ^[16] 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'
    }
}

The TestNG framework has a quite similar concept. In TestNG you can specify different test groups. ^[17] 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'
    }
}

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やwarオブジェクトは、それぞれManifestのインスタンスであるmanifestプロパティを持ちます。 アーカイブが生成されるとき、対応するMANIFEST.MFファイルがアーカイブ内に作成されます。

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.

独立したManifestインスタンスを生成することもできます。 これは例えば、複数のjar間でマニフェスト情報を共有する目的などに利用できます。

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.

Manifestオブジェクトに他のマニフェストをマージすることもできます。 マージ対象のマニフェストは、ファイルパス、または上の例のように別のManifestオブジェクトの参照によって指定できます。

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

マニフェストはfrom文で宣言された順にマージされます。 元のマニフェストとマージするマニフェストの双方に同じキーを持つ値が定義されている場合、デフォルトではマージするマニフェストのものが有効になります。 マージの振る舞いは、マージで生成されるマニフェストの各エントリに対するManifestMergeDetailsインスタンスにアクセスする、eachEntryアクションを追加することによって自在にカスタマイズ可能です。 マージはfrom文によって即座に実行されるわけではありません。 jarの生成時、またはwriteToや effectiveManifestの呼び出し時に、遅延して実行されます。

You can easily write a manifest to disk.

マニフェストをディスクに書き出すのは簡単です。

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