AssertJの使い方｜assertThatの早見表（文字列・リスト・例外・日付）

AssertJ は、assertThat(実際の値).検証メソッド(期待値) の形で、テストの判定を「文章のように」つなげて書けるライブラリです。 値の型に合わせて使えるメソッドが変わるので、IDE の補完で候補が出ます。

import static org.assertj.core.api.Assertions.*;

assertThat(user.getName()).isEqualTo("Taro");
assertThat(list).hasSize(3).contains("b").doesNotContain("z");
assertThatThrownBy(() -> service.find(-1))
        .isInstanceOf(IllegalArgumentException.class)
        .hasMessageContaining("id");

失敗したときのメッセージが詳しいのも特徴です。 同じ失敗を JUnit と AssertJ で比べると、次のようになりました。

確認環境：AssertJ 3.27.7（GitHub のタグで最新の安定版。Spring Boot 4.1.1 が管理する版と同じ）を、タグ assertj-build-3.27.7 のソースからビルドし、OpenJDK 21.0.10（Linux）で動かしました。この記事の早見表のコードは 96 個の判定がすべて通ること、「迷いやすい3つの違い」の表は16通りを実行した結果であること、失敗メッセージは実際の出力であることを確かめています。JUnit 側のメッセージは JUnit Jupiter 5.10.1、SoftAssertionsExtension は JUnit Platform Console 1.9.1 で実行した結果です（確認日 2026年10月13日）。

依存の追加

Spring Boot のプロジェクトなら、spring-boot-starter-test に AssertJ が入っています（Boot 4.1.1 が管理する版は 3.27.7）。単体で入れる場合は次のとおりです。

// build.gradle.kts
dependencies {
    testImplementation("org.assertj:assertj-core:3.27.7")
}

<!-- pom.xml -->
<dependency>
  <groupId>org.assertj</groupId>
  <artifactId>assertj-core</artifactId>
  <version>3.27.7</version>
  <scope>test</scope>
</dependency>

AssertJ 3.x は Java 8 以上で動きます（ビルド設定の java.version が 8）。4.0.0 はマイルストーン版（4.0.0-M1）が出ている段階です。

import static org.assertj.core.api.Assertions.*; を1行書くと、assertThat などが全部使えます。 JUnit の Assertions と名前がぶつかるので、同じファイルで両方を * で読み込まないようにします。BDD（振る舞い駆動）の書き方が好みなら、BDDAssertions.then(…) も同じ機能です。JUnit そのものの書き方は、関連記事「JUnitの使い方｜単体テストの書き方と観点【JUnit 5・6】」で扱っています。

JUnit の assert と AssertJ の対応表

引数の順番が逆なのが一番の違いです。 JUnit は assertEquals(期待値, 実際の値)、AssertJ は assertThat(実際の値).isEqualTo(期待値) です。JUnit で順番を取り違えると、メッセージの expected と but was が逆に出ます。

型別メソッド早見表

すべての型で使える

as と withFailMessage は、判定メソッドより前に書きます。 後ろに書くと、判定が先に失敗して効きません。

文字列（String）

数値

assertThat(0.1 + 0.2).isEqualTo(0.3) は失敗しました（but was: 0.30000000000000004）。小数は isCloseTo で比べます。BigDecimal の isEqualTo は 1.0 と 1.00 を別の値とみなすので、値だけ比べるなら isEqualByComparingTo を使います。理由は、関連記事「Java BigDecimalの使い方｜金額計算の丸めと比較の注意点」で扱っています。

List・配列（Iterable）

迷いやすい3つの違い

Map

Optional

Optional そのものの使い方は、関連記事「Java Optionalの使い方｜orElseとorElseGetの違いと使う場所」で扱っています。

日付・時刻（java.time）

現在時刻を使う処理は、isCloseTo(…, within(…)) で「数秒のずれ」を許すと安定します。 日付の書式は、関連記事「Java DateTimeFormatterパターン一覧｜日付と文字列の変換」で扱っています。

例外の判定

assertThatThrownBy（一番よく使う形）

assertThatThrownBy(() -> userService.register(new UserRequest("", -1)))
        .isInstanceOf(IllegalArgumentException.class)
        .hasMessage("age must be >= 0")          // 完全一致
        .hasMessageContaining(">= 0")            // 部分一致
        .hasMessageStartingWith("age")
        .hasNoCause();

書き方の一覧

原因（cause）の判定は次のとおりです。

assertThatThrownBy(() -> repository.save(user))
        .isInstanceOf(IllegalStateException.class)
        .hasCauseInstanceOf(IOException.class)     // 直接の原因
        .hasRootCauseMessage("disk");              // 一番奥の原因のメッセージ

例外が出なかったときは、次のメッセージで失敗しました。

Expecting code to raise a throwable.

例外の種類と使い分けは、関連記事「Java 例外一覧｜種類・原因・対処の早見表と使い分け」で扱っています。

extracting と tuple：オブジェクトのリストを判定する

オブジェクトのリストから、特定のフィールドだけを取り出して判定するのが extracting です。

List<Item> items = List.of(new Item("pen", 100), new Item("note", 250));

// 1つのフィールド
assertThat(items).extracting(Item::getName).containsExactly("pen", "note");
assertThat(items).extracting("name").containsExactly("pen", "note");      // 名前でも書ける

// 複数のフィールドは tuple で
assertThat(items)
        .extracting(Item::getName, Item::getPrice)
        .containsExactly(tuple("pen", 100), tuple("note", 250));

// 絞り込んでから取り出す
assertThat(items).filteredOn("price", 100).extracting("name").containsExactly("pen");

// リストのフィールドを平らにする
assertThat(items).flatExtracting(Item::getTags).containsExactly("office", "office", "paper");

usingRecursiveComparison：中身で比べる

equals を実装していないクラスや、一部のフィールドを無視して比べたいときは、usingRecursiveComparison() を使います。 入れ子のオブジェクトの中までフィールドごとに比べます。

record Address(String city, String zip) {}
record User(String name, int age, Address address) {}
record UserDto(String name, int age) {}

User actual = new User("Taro", 20, new Address("Tokyo", "100-0001"));

// 中身が同じなら成功
assertThat(actual).usingRecursiveComparison()
        .isEqualTo(new User("Taro", 20, new Address("Tokyo", "100-0001")));

// 一部のフィールドを無視（入れ子は「.」でつなぐ）
assertThat(actual).usingRecursiveComparison()
        .ignoringFields("age", "address.zip")
        .isEqualTo(new User("Taro", 99, new Address("Tokyo", "999")));

// 違う型（DTO）とも、同じ名前のフィールドで比べられる
assertThat(actual).usingRecursiveComparison()
        .ignoringFields("address")
        .isEqualTo(new UserDto("Taro", 20));

// 期待値で null のフィールドは比べない
assertThat(actual).usingRecursiveComparison()
        .ignoringExpectedNullFields()
        .isEqualTo(new User("Taro", 20, null));

// リストの要素ごとに中身で比べる
assertThat(List.of(actual))
        .usingRecursiveFieldByFieldElementComparatorIgnoringFields("age")
        .containsExactly(new User("Taro", 0, new Address("Tokyo", "100-0001")));

ID や作成日時のように、テストのたびに変わる値を ignoringFields で外すと、DB から取り出したエンティティの判定が書きやすくなります。record の equals のしくみは、関連記事「Java recordの使い方｜classとの違いと実行結果で学ぶ」で扱っています。

SoftAssertions：全部の失敗をまとめて出す

ふつうの assertThat は、最初の失敗でテストが止まります。 SoftAssertions は失敗を貯めておき、最後にまとめて報告します。画面の項目チェックのように、1回で全部の違いを知りたいときに使います。

JUnit 5 の拡張で使う（おすすめの形）

import static org.assertj.core.api.Assertions.*;

import org.assertj.core.api.SoftAssertions;
import org.assertj.core.api.junit.jupiter.InjectSoftAssertions;
import org.assertj.core.api.junit.jupiter.SoftAssertionsExtension;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;

@ExtendWith(SoftAssertionsExtension.class)
class UserTest {

    @InjectSoftAssertions
    SoftAssertions softly;

    record User(String name, int age, String email) {}

    @Test
    void softAssertions() {
        User user = new User("Taro", 17, "taro@example");

        softly.assertThat(user.name()).isEqualTo("Taro");
        softly.assertThat(user.age()).as("age").isGreaterThanOrEqualTo(18);
        softly.assertThat(user.email()).as("email").endsWith(".com");
        // assertAll() は拡張がテストの最後に呼ぶ
    }
}

実行結果です。2つの失敗が両方とも、行番号つきで出ました。

org.assertj.core.error.AssertJMultipleFailuresError:
Multiple Failures (2 failures)
-- failure 1 --
[age]
Expecting actual:
  17
to be greater than or equal to:
  18
at UserTest.softAssertions(UserTest.java:22)
-- failure 2 --
[email]
Expecting actual:
  "taro@example"
to end with:
  ".com"
at UserTest.softAssertions(UserTest.java:23)

拡張を使わない書き方

// ラムダの中をまとめて判定
SoftAssertions.assertSoftly(softly -> {
    softly.assertThat(user.name()).isEqualTo("Taro");
    softly.assertThat(user.age()).isGreaterThan(17);
});

// 自分で assertAll() を呼ぶ
SoftAssertions softly = new SoftAssertions();
softly.assertThat(list).hasSize(3);
softly.assertAll();          // ← 忘れると、失敗しても何も起きない

new SoftAssertions() で作った場合、assertAll() を呼び忘れると、失敗が報告されずにテストが通ります。 拡張か assertSoftly を使うと、この呼び忘れが起きません。

失敗メッセージの読み方

AssertJ 3.27.7 で、わざと失敗させたときの出力です。

基本の形：Expecting actual … to …

Expecting actual:
  "order-123"
to start with:
  "ord_"

「actual（実際の値）が、to 以下（期待）を満たさなかった」と読みます。 isEqualTo だけは JUnit と同じ形になりました。

expected: "Hello Assertj"
 but was: "Hello AssertJ"

expected が期待値、but was が実際の値です。文字列は " で囲まれるので、前後の空白の違いにも気づけます。

as() を付けると先頭に [説明] が付く

[年齢チェック]
Expecting actual:
  17
to be greater than or equal to:
  18

リストは「どこが違うか」まで出る

Expecting actual:
  ["b", "a", "c"]
to contain exactly (and in same order):
  ["a", "b", "c"]
but there were differences at these indexes:
  - element at index 0: expected "a" but was "b"
  - element at index 1: expected "b" but was "a"

[Extracted: name, price]
Expecting actual:
  [("pen", 100), ("note", 250)]
to contain exactly (and in same order):
  [("pen", 100), ("note", 200)]
but some elements were not found:
  [("note", 200)]
and others were not expected:
  [("note", 250)]

extracting を使うと、何を取り出したかが [Extracted: …] で先頭に付きます。not found は期待にあって実際に無いもの、not expected は実際にあって期待に無いものです。

再帰比較は、違うフィールドを全部並べる

Expecting actual:
  User[name=Taro, age=20, address=Address[city=Tokyo, zip=100-0001]]
to be equal to:
  User[name=Taro, age=21, address=Address[city=Osaka, zip=100-0001]]
when recursively comparing field by field, but found the following 2 differences:

field/property 'address.city' differ:
- actual value  : "Tokyo"
- expected value: "Osaka"
...
field/property 'age' differ:
- actual value  : 20
- expected value: 21

この後に、比べ方の設定（比較器や、型が違っても比べること）の説明が続きます。

例外のメッセージ違い

Expecting message to be:
  "age must be positive"
but was:
  "age must be >= 0"

Throwable that failed the check:

java.lang.IllegalArgumentException: age must be >= 0
    at …

その他の型

よくある間違い

よくある質問

Q. Hamcrest の assertThat(x, is(y)) と何が違いますか。 A. Hamcrest はマッチャー（is・hasItem など）を引数で渡す形で、AssertJ は assertThat(x) の後ろにメソッドをつなぐ形です。AssertJ は型に合ったメソッドだけが補完で出るので、書ける判定を探しやすいです。

Q. Mockito と一緒に使えますか。 A. 使えます。Mockito でモックを作り、戻り値の判定に AssertJ を使う形がよくあります。引数を取り出して判定する ArgumentCaptor とも組み合わせられます。Mockito の使い方は、関連記事「Mockitoの使い方｜JUnit 5での基本からよくあるエラーまで」で扱っています。

Q. Spring Boot のテストでも同じですか。 A. 同じです。spring-boot-starter-test に入っていて、MockMvc の結果を AssertJ で判定する MockMvcTester も Spring Framework に用意されています。Controller のテストは、関連記事「Spring Bootテスト入門｜@WebMvcTestとMockMvcの使い分け」で扱っています。

Q. 自分のクラス専用の判定を作れますか。 A. AbstractAssert を継承したクラスを作ると、assertThat(user).hasName("Taro") のような専用のメソッドを足せます。よく使う判定が多いときに向いています。

まとめ

• 形は assertThat(実際の値).判定(期待値)。JUnit とは引数の順番が逆
• リストは containsExactly（順番も）・containsExactlyInAnyOrder（順番は問わない）・contains（含む） を使い分ける
• 例外は assertThatThrownBy(…).isInstanceOf(…).hasMessage(…)
• オブジェクトのリストは extracting ＋ tuple、中身の比較は usingRecursiveComparison
• 全部の失敗を見たいときは SoftAssertions（JUnit 5 の拡張で assertAll の呼び忘れを防ぐ）
• 失敗メッセージは Expecting actual（実際）… to …（期待） と読む

参考・出典

確認日はいずれも 2026年10月13日です。

• AssertJ 公式ドキュメント：https://assertj.github.io/doc/
• AssertJ（GitHub、ソース・タグ assertj-build-3.27.7）：https://github.com/assertj/assertj
• AssertJ Core Javadoc：https://www.javadoc.io/doc/org.assertj/assertj-core/latest/index.html
• Spring Boot ドキュメント「Testing」（Test Scope Dependencies）：https://docs.spring.io/spring-boot/reference/testing/test-scope-dependencies.html

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。