EqualsVerifierでequalsとhashCodeの検証を自動化

2025年7月31日

Javaにおけるequals()メソッドとhashCode()メソッドの正しい実装は、SetやMapなどのコレクション操作やオブジェクトの同一性判定において不可欠な要素です。

しかし、これらのメソッドが満たすべき「対称性」「推移性」「一貫性」といった厳密な契約条件をすべてクリアした実装とテストを作成するのは簡単ではありません。手動でテストコードを書く場合、どうしても見落としや抜け漏れが発生し、深刻なバグを招く原因となってしまいます。

そんな課題を解決してくれるのが、EqualsVerifierというユニットテスト専用ライブラリです。本記事では、EqualsVerifierの基本的な導入手順から実践的な活用方法、さらにはLombokライブラリとの組み合わせまで、具体的なコード例とともに詳しくご紹介します。

EqualsVerifierとは？

EqualsVerifier は、Javaクラスの equals() および hashCode() メソッドが、正しく実装されているかどうかを自動で検証してくれるユニットテスト向けライブラリです。

このライブラリは、オブジェクトの同値性に関する「契約（contract）」――対称性、推移性、一貫性、nullとの比較、hashCodeとの整合性など――がすべて守られているかを、網羅的かつ高速にチェックしてくれます。

EqualsVerifierを使えば、1行のコードで複雑なロジックの正当性を検証でき、手動で書くテストコードの量と漏れを大幅に削減できます。

開発者はオランダの Jan Ouwens 氏で、オープンソースとして広く利用されており、多くのJavaプロジェクトで信頼性の高いテスト手法として採用されています。

なぜEqualsVerifierを使うべきか

Javaのequals()やhashCode()には、以下のような厳密な「契約（contract）」が定められています。

対称性：A.equals(B) が true なら B.equals(A) も true であること
推移性：A.equals(B)、B.equals(C) なら A.equals(C)
一貫性：同じオブジェクトに対する比較結果は常に同じであること
nullとの比較：A.equals(null) は常に false を返すこと
hashCodeとの整合性：A.equals(B) が true なら A.hashCode() == B.hashCode()

この契約に違反すると、SetやMapなどのコレクションで正しく動作しない、バグが発見しづらい、といった重大な問題を引き起こします。

とはいえ、これらすべてを手動で網羅的にテストするのは非常に手間がかかり、抜け漏れや見落としのリスクもあります。

EqualsVerifierを使えば、たった1行のテストコードで、これらの契約を自動で検証できます。人手では困難なレベルの網羅性を確保できるため、テストの信頼性を高め、保守性を向上させるうえで非常に有効です。

EqualsVerifierの導入方法

EqualsVerifierは、Maven や Gradle を使って簡単に導入できます。いずれもテスト用のライブラリとして扱うため、testスコープ（または testImplementation）で指定しましょう。

Mavenを使用する場合

<dependency>
  <groupId>nl.jqno.equalsverifier</groupId>
  <artifactId>equalsverifier</artifactId>
  <version>4.0.6</version>
  <scope>test</scope>
</dependency>

Gradleを使用する場合

dependencies {
    testImplementation 'nl.jqno.equalsverifier:equalsverifier:4.0.6'
}

あとは、通常のユニットテストと同様にテストクラスを作成し、EqualsVerifierを使った検証コードを記述するだけです。

基本的な使い方とサンプルコード

ここでは、EqualsVerifierの最も基本的な使い方を紹介します。まずは、シンプルな POJO クラス Person に対して equals() と hashCode() の検証を行ってみましょう。

テスト対象クラス

import java.util.Objects;

public final class Person {
    private final String name;
    private final int age;

    public Person(String name, int age) {
        this.name = name;
        this.age = age;
    }

    @Override
    public boolean equals(Object obj) {
        if (!(obj instanceof Person)) {
            return false;
        }
        Person other = (Person) obj;
        return Objects.equals(name, other.name) && age == other.age;
    }

    @Override
    public int hashCode() {
        return Objects.hash(name, age);
    }
}

テストクラス

import org.junit.jupiter.api.Test;
import nl.jqno.equalsverifier.EqualsVerifier;

public class PersonTest {
    @Test
    void equalsAndHashCodeShouldFollowContract() {
        EqualsVerifier.forClass(Person.class).verify();
    }
}

このテストを実行するだけで、Person クラスの equals() と hashCode() が、Javaの契約（対称性・推移性・nullとの比較・hashCodeの整合性など）を正しく満たしているかどうかを自動的に検証してくれます。

もし契約に違反していれば、EqualsVerifierはその理由を明示したエラーメッセージを出力し、どこに問題があるかを教えてくれます。

代表的なオプションと使いどころ

EqualsVerifierには、現実的なユースケースに対応するための便利なオプションが多数用意されています。ここでは、特によく使われる代表的なメソッドと、その使いどころを紹介します。

`withNonnullFields(...)`

指定したフィールドに null が入ることがない（入ってはいけない）と明示するためのオプションです。
EqualsVerifierは自動的に null を代入してテストするため、非null前提のフィールドにはこの設定が必要です。

EqualsVerifier.forClass(Person.class)
    .withNonnullFields("name")
    .verify();

`withIgnoredFields(...)`

equals() や hashCode() に関係しないフィールドを検証対象から除外します。
ログ用のフィールドやキャッシュ、DIされた依存など、同値性に影響を与えないフィールドがある場合に便利です。

EqualsVerifier.forClass(Person.class)
    .withIgnoredFields("logger")
    .verify();

`usingGetClass()`

equals() の中で getClass() による厳密な型チェックを行っている場合に指定します。
デフォルトでは instanceof による比較が前提なので、明示的にこの指定が必要です。

EqualsVerifier.forClass(Person.class)
    .usingGetClass()
    .verify();

`suppress(...)`

EqualsVerifierが検出する警告を抑制します。
たとえば、フィールドが final でない場合や、非推奨な構成を明示的に許容したいときに使います。使用には注意が必要です。

EqualsVerifier.forClass(Person.class)
    .suppress(Warning.NONFINAL_FIELDS)
    .verify();

Lombokとの併用方法と注意点

@EqualsAndHashCode などの Lombok アノテーションを使えば、equals() や hashCode() を手書きせずに自動生成できます。EqualsVerifier はこのような Lombok 生成コードとも問題なく動作します。

たとえば、次のようなクラスに対しても、通常どおり検証可能です。

@EqualsAndHashCode
public class Person {
    private String name;
    private int age;
}

この場合、EqualsVerifier は次のように使えます。

EqualsVerifier.forClass(Person.class).verify();

よくある注意点

継承関係がある場合： @EqualsAndHashCode(callSuper = true) を明示しないと、EqualsVerifier がスーパークラスのフィールドを無視していると警告することがあります。
静的/static フィールド： Lombok は static フィールドを equals() に含めません。EqualsVerifier は「すべてのフィールドを使っていない」と警告する場合があるため、.suppress(Warning.ALL_FIELDS_SHOULD_BE_USED) で対応できます。
一部のフィールドだけで比較したい場合： @EqualsAndHashCode(onlyExplicitlyIncluded = true) を指定し、対象のフィールドに @EqualsAndHashCode.Include を付けましょう。

EqualsVerifier と Lombok の相性は良好ですが、「何が自動生成されているか」を把握したうえで検証を書くのが安心です。