Maven Surefire Pluginのincludeになにを指定したらいいのかわからないという話

これは、なにをしたくて書いたもの？

Maven Surefire Pluginにはincludes ／ include、excludes ／ excludeでテストを絞り込んだり除外したりする機能があります。

ドキュメントを見ていると、なにとマッチさせているのかがいつもよくわからなくなるので調べてみました。

Maven Surefire Pluginのincludesとexcludes

対象のドキュメントはこちら。

Maven Surefire Plugin – Inclusions and Exclusions of Tests

今回はincludes ／ includeを対象にします。

まずはシンプルな使い方から。サンプルはこんな感じですね。

        <configuration>
          <includes>
            <include>Sample.java</include>
          </includes>
        </configuration>

ワイルドカード（*、**）も含め、Javaのソースコード名で指定するように見えます。

"**/Test*.java" - includes all of its subdirectories and all Java filenames that start with "Test".
"**/*Test.java" - includes all of its subdirectories and all Java filenames that end with "Test".
"**/*Tests.java" - includes all of its subdirectories and all Java filenames that end with "Tests".
"**/*TestCase.java" - includes all of its subdirectories and all Java filenames that end with "TestCase".

Inclusions and Exclusions of Tests / Inclusions

%regex[.*(Cat|Dog).*Test.*]のように、正規表現での指定もできます。

Inclusions and Exclusions of Tests / Regular Expression Support

surefire:testのドキュメントにも同じようなことがまとめられています。

surefire:test / Parameter Details / includes

じゃあ、きっちり指定しようと思うとsrc/test/java/path/to/AbcTest.javaとか書くんですか…？という気になるので、Maven Surefire Pluginの
includes ／ includeがなにとマッチさせているのかちょっと見てみました。

ちなみに、testを使うとメソッドレベルまで絞り込んだり、includes ／ include、excludes ／ excludeを一括で指定できたりと
さらに柔軟に扱えます。

surefire:test / Parameter Details / test

これはincludeやexcludeにカンマ区切りで指定することで同じ動作が実現できるようです。今回はこちらは扱いません。

Inclusions and Exclusions of Tests / Multiple Formats in One

また、ここまでの話はMaven Failsafe Pluginでも同じだと思います。

Maven Failsafe Plugin – Inclusions and Exclusions of Tests

Maven Failsafe Plugin – failsafe:integration-test

環境

今回の環境はこちら。

$ java --version
openjdk 21.0.4 2024-07-16
OpenJDK Runtime Environment (build 21.0.4+7-Ubuntu-1ubuntu222.04)
OpenJDK 64-Bit Server VM (build 21.0.4+7-Ubuntu-1ubuntu222.04, mixed mode, sharing)


$ mvn --version
Apache Maven 3.9.8 (36645f6c9b5079805ea5009217e36f2cffd34256)
Maven home: $HOME/.sdkman/candidates/maven/current
Java version: 21.0.4, vendor: Ubuntu, runtime: /usr/lib/jvm/java-21-openjdk-amd64
Default locale: ja_JP, platform encoding: UTF-8
OS name: "linux", version: "5.15.0-117-generic", arch: "amd64", family: "unix"

準備

Maven依存関係など。

    <properties>
        <maven.compiler.release>21</maven.compiler.release>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter</artifactId>
            <version>5.10.3</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <version>3.3.1</version>
                <configuration>
                    <!-- あとで -->
                </configuration>
            </plugin>
        </plugins>
    </build>

Maven Surefire Pluginの設定はあとで書きます。

テストコードを用意する

テスト対象となるテストコードを用意します。

Maven Surefire Pluginの動作を見るだけなので、テストの中身は要りません。いるのはファイル名やパスのバリエーションですね。

src/test/java/org/littlewings/surefire/SampleTest.java

package org.littlewings.surefire;

import org.junit.jupiter.api.Test;

class SampleTest {
    @Test
    void test() {
    }
}

src/test/java/org/littlewings/surefire/sample/SampleTest.java

package org.littlewings.surefire.sample;

import org.junit.jupiter.api.Test;

class SampleTest {
    @Test
    void test() {
    }
}

src/test/java/org/littlewings/surefire/foo/FooTest.java

package org.littlewings.surefire.foo;

import org.junit.jupiter.api.Test;

class FooTest {
    @Test
    void test() {
    }
}

src/test/java/org/littlewings/surefire/bar/BarTest.java

package org.littlewings.surefire.bar;

import org.junit.jupiter.api.Test;

class BarTest {
    @Test
    void test() {
    }
}

src/test/java/org/littlewings/surefire/hoge/HogeTest.java

package org.littlewings.surefire.hoge;

import org.junit.jupiter.api.Test;

public class HogeTest {
    @Test
    void test() {
    }
}

Maven Surefire Pluginのincludes／includeを設定する

用意したテストコードのパスは以下です。

src/test/java/org/littlewings/surefire/SampleTest.java
src/test/java/org/littlewings/surefire/sample/SampleTest.java
src/test/java/org/littlewings/surefire/foo/FooTest.java
src/test/java/org/littlewings/surefire/bar/BarTest.java
src/test/java/org/littlewings/surefire/hoge/HogeTest.java

まずはなにも設定せずにテストを動かします。

            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <version>3.3.1</version>
                <configuration>
                </configuration>
            </plugin>

実行。

$ mvn test

当然ですが、すべてのテストコードが実行されます。

[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running org.littlewings.surefire.bar.BarTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.061 s -- in org.littlewings.surefire.bar.BarTest
[INFO] Running org.littlewings.surefire.hoge.HogeTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.004 s -- in org.littlewings.surefire.hoge.HogeTest
[INFO] Running org.littlewings.surefire.SampleTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.004 s -- in org.littlewings.surefire.SampleTest
[INFO] Running org.littlewings.surefire.sample.SampleTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.004 s -- in org.littlewings.surefire.sample.SampleTest
[INFO] Running org.littlewings.surefire.foo.FooTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.003 s -- in org.littlewings.surefire.foo.FooTest
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 5, Failures: 0, Errors: 0, Skipped: 0

SampleTest.javaと書いてみます。

            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-surefire-plugin</artifactId>
                <version>3.3.1</version>
                <configuration>
                    <includes>
                        <include>SampleTest.java</include>
                    </includes>
                </configuration>
            </plugin>

実行。

$ mvn test

2つのテストクラスが実行されました。

[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running org.littlewings.surefire.SampleTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.058 s -- in org.littlewings.surefire.SampleTest
[INFO] Running org.littlewings.surefire.sample.SampleTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.004 s -- in org.littlewings.surefire.sample.SampleTest
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0

後方一致しているような感じですね。

こう設定してみるとどうでしょうか。
※ここからはconfigurationのみを記載します

                <configuration>
                    <includes>
                        <include>**/SampleTest.java</include>
                    </includes>
                </configuration>

結果は変わりません。つまり、同じ意味だったということになるのでしょうか？
※mvn testの実行も以降は省略します

[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running org.littlewings.surefire.SampleTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.049 s -- in org.littlewings.surefire.SampleTest
[INFO] Running org.littlewings.surefire.sample.SampleTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.004 s -- in org.littlewings.surefire.sample.SampleTest
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0

ちなみに、.javaを書かなくても動いたりします。

                <configuration>
                    <includes>
                        <include>**/SampleTest</include>
                    </includes>
                </configuration>

結果。

[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running org.littlewings.surefire.SampleTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.054 s -- in org.littlewings.surefire.SampleTest
[INFO] Running org.littlewings.surefire.sample.SampleTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.004 s -- in org.littlewings.surefire.sample.SampleTest
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0

これを見ると、ちょっとなにを対象にしているかわからなくなりますよね…。

ワイルドカードを使った例。

                <configuration>
                    <includes>
                        <include>**/Ba*Test.java</include>
                    </includes>
                </configuration>

結果。

[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running org.littlewings.surefire.bar.BarTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.043 s -- in org.littlewings.surefire.bar.BarTest
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

正規表現。%regex[パターン]で書きます。

                <configuration>
                    <includes>
                        <include>%regex[.*FooTest.*]</include>
                    </includes>
                </configuration>

結果。

[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running org.littlewings.surefire.foo.FooTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.048 s -- in org.littlewings.surefire.foo.FooTest
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

前後の.*が重要のようで、削除するとテスト対象にならなくなります。

                <configuration>
                    <includes>
                        <include>%regex[.*FooTest]</include>
                    </includes>
                </configuration>

こちらもテスト対象がゼロになります。

                <configuration>
                    <includes>
                        <include>%regex[FooTest.*]</include>
                    </includes>
                </configuration>

最後に組み合わせで。

                <configuration>
                    <includes>
                        <include>SampleTest.java</include>
                        <include>**/Ba*Test.java</include>
                        <include>%regex[.*FooTest.*]</include>
                    </includes>
                </configuration>

結果。

[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running org.littlewings.surefire.bar.BarTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.064 s -- in org.littlewings.surefire.bar.BarTest
[INFO] Running org.littlewings.surefire.SampleTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.004 s -- in org.littlewings.surefire.SampleTest
[INFO] Running org.littlewings.surefire.sample.SampleTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.006 s -- in org.littlewings.surefire.sample.SampleTest
[INFO] Running org.littlewings.surefire.foo.FooTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.005 s -- in org.littlewings.surefire.foo.FooTest
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 4, Failures: 0, Errors: 0, Skipped: 0

Maven Surefire Pluginのinclude／excludeはなにを見ているのか？

Maven Surefire Pluginでテスト対象に含める、または除外するかを判定しているのはこちらです。

https://github.com/apache/maven-surefire/blob/surefire-3.3.1/surefire-api/src/main/java/org/apache/maven/surefire/api/testset/TestListResolver.java#L177-L205

テストが指定されたパターンに一致すればテスト対象となり、また除外対象にもなります。

            boolean shouldRun = false;

            if (getIncludedPatterns().isEmpty()) {
                shouldRun = true;
            } else {
                for (ResolvedTest filter : getIncludedPatterns()) {
                    if (filter.matchAsInclusive(testClassFile, methodName)) {
                        shouldRun = true;
                        break;
                    }
                }
            }

            if (shouldRun) {
                for (ResolvedTest filter : getExcludedPatterns()) {
                    if (filter.matchAsExclusive(testClassFile, methodName)) {
                        shouldRun = false;
                        break;
                    }
                }
            }
            return shouldRun;

マッチ対象はクラスとメソッドがあるのですが、今回はメソッドのみを見ます。

クラス名は以下でフォーマットされます。

https://github.com/apache/maven-surefire/blob/surefire-3.3.1/surefire-api/src/main/java/org/apache/maven/surefire/api/testset/ResolvedTest.java#L273-L284

この時、.javaは.classに置き換えられます。

https://github.com/apache/maven-surefire/blob/surefire-3.3.1/surefire-api/src/main/java/org/apache/maven/surefire/api/testset/ResolvedTest.java#L286-L296

また、パスの先頭が**/で始まっていない場合は追加されます。

https://github.com/apache/maven-surefire/blob/surefire-3.3.1/surefire-api/src/main/java/org/apache/maven/surefire/api/testset/ResolvedTest.java#L277-L279

つまり、SampleTest.javaは**/SampleTest.classと同じです。

.javaという感じでソースコードを指定したのですが、結局対象にしているのは.classのようですね。

そして、こちらで渡されるクラスファイルとマッチするか確認するのですが、この時に渡されるtestClassFileはorg/littlewings/surefire/SampleTest.classのような値が渡ってきます。

https://github.com/apache/maven-surefire/blob/surefire-3.3.1/surefire-api/src/main/java/org/apache/maven/surefire/api/testset/TestListResolver.java#L177-L205

ということは、マッチするか判定しているのはテスト対象のソースコードのパスではなく、テスト対象のクラスですね。

正規表現を使った場合は、パスの補正は入りません。そして、指定された正規表現に対してorg/littlewings/surefire/SampleTest.classの
ようなクラスに対してマッチを試みます。

こうなると、前後のパターンを削るとマッチしなくなった理由がわかる気がします。

ここまでわかると、実は.classで指定してもよいことがわかりますね。

                <configuration>
                    <includes>
                        <include>SampleTest.class</include>
                    </includes>
                </configuration>

そして、拡張子がなくてもよかったこともわかります。

                <configuration>
                    <includes>
                        <include>SampleTest</include>
                    </includes>
                </configuration>

結果はどちらもこうなります。

[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running org.littlewings.surefire.SampleTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.056 s -- in org.littlewings.surefire.SampleTest
[INFO] Running org.littlewings.surefire.sample.SampleTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.005 s -- in org.littlewings.surefire.sample.SampleTest
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0

オマケ的に。

                <configuration>
                    <includes>
                        <include>**/sample/*SampleTest</include>
                    </includes>
                </configuration>

結果。

[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running org.littlewings.surefire.sample.SampleTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.056 s -- in org.littlewings.surefire.sample.SampleTest
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

こんなところでしょうか。

おわりに

Maven Surefire Pluginのincludeになにを指定したらいいのかよくわかっていなかったので、ちょっと詳しくみてみました。

なんとなく雰囲気で指定していることが多かったのですが、どういう挙動をしているかわかったのでどう書くとどういう結果になるかが
だいぶわかるようになった気がします。

CLOVER🍀

That was when it all began.