時計の針を固定し、期限前後を再現する図。Clock.fixedで日時依存テストを安定させる

設計・テスト・レビュー

Javaの現在日時をテストで固定する方法|Clock.fixedで期限判定を確認する

「昨日まで通った期限判定テストが、今日になったら落ちた」。期限を固定して期待結果だけ書き、判定の中でLocalDate.now()を呼んでいると起こる失敗です。テストのたびに予定日を書き換える運用では、期限当日と翌日の境界を保証できません。

ここで取る方針は、現在日時を業務ロジックの入力として扱い、Clockを渡すことです。題材は「締切日当日まで申請でき、翌日からできない」という架空の申請機能。画面表示やDB保存ではなく、期限判定を毎日同じ条件で確かめます。

実行サンプル

締切日の当日・翌日と、同じ瞬間を日本時間とUTCで判定した違いを確認します。 JDK 17以上とMavenを使います。ZIPを展開し、mvn clean testを実行してください。必要なソース、テスト、実行設定を収録しています。

現在日時をコード内に埋め込むと、テストから動かせない

次の形では、テストに2026-04-01の締切日を渡せても、「今」がOSの時計で決まります。

boolean canSubmit(LocalDate deadline) {
    return !LocalDate.now().isAfter(deadline);
}

たとえば4月1日に実行すればtrue、4月2日に実行すればfalse。どちらも正しい動きですが、同じテストケースの期待値を固定できません。Thread.sleep()で日付境界を待つ方法は、実行時間も結果も不安定にします。

Clockを受け取る期限判定にする

例の前提はJava 17、JUnit Jupiter 5.12.2、Maven Surefire 3.5.3です。単独プロジェクトならpom.xmlを次のようにします。

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>example</groupId>
  <artifactId>article-2301</artifactId>
  <version>1.0.0</version>
  <properties>
    <maven.compiler.release>17</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <test.source.directory>src/test/java</test.source.directory>
  </properties>
  <dependencies>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter</artifactId>
      <version>5.12.2</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
  <build>
    <testSourceDirectory>${test.source.directory}</testSourceDirectory>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.14.1</version>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>3.5.3</version>
      </plugin>
    </plugins>
  </build>
</project>

src/main/java/example/DeadlinePolicy.java。LocalDate.now(clock)は、受け取った時計の時刻とタイムゾーンで「今日」を決めます。締切日と同じ日は許可し、翌日になれば拒否します。

package example;

import java.time.Clock;
import java.time.LocalDate;
import java.util.Objects;

public final class DeadlinePolicy {
    private final Clock clock;

    public DeadlinePolicy(Clock clock) {
        this.clock = Objects.requireNonNull(clock);
    }

    public boolean canSubmit(LocalDate deadline) {
        Objects.requireNonNull(deadline);
        LocalDate today = LocalDate.now(clock);
        return !today.isAfter(deadline);
    }
}

本番で使うときは、たとえばnew DeadlinePolicy(Clock.system(ZoneId.of("Asia/Tokyo")))と作ります。SpringならClockをBeanとして注入しても構いません。この例では、申請期限の基準地域を日本時間と決めました。海外利用者の現地日付を基準とするサービスなら、利用者のタイムゾーンをどう決めるかが別の仕様です。

同じ時刻を固定し、日付の切り替わりを確かめる

src/test/java/example/DeadlinePolicyTest.java。UTCで2026年4月1日15時は、日本時間では4月2日0時です。その直前と直後を置くと、タイムゾーンの設定漏れを見つけやすくなります。

固定するUTC時刻日本時間の日付締切日申請可能か
4月1日14:59:594月1日4月1日○
4月1日15:00:004月2日4月1日×
4月1日15:00:004月2日4月2日○
日時依存テストの境界。基準時刻:Clock.fixedで指定。時間帯:ZoneIdをそろえる。期限前:許可されるか。期限後:拒否されるか
日時依存テストの境界。Clock.fixedで期限判定を固定
package example;

import java.time.Clock;
import java.time.Instant;
import java.time.LocalDate;
import java.time.ZoneId;
import java.time.ZoneOffset;

import org.junit.jupiter.api.Test;

import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.CsvSource;

import static org.junit.jupiter.api.Assertions.assertEquals;

class DeadlinePolicyTest {
    private static final ZoneId JAPAN = ZoneId.of("Asia/Tokyo");

    @ParameterizedTest(name = "UTC={0}, 締切={1} → 申請可能={2}")
    @CsvSource({
        "2026-04-01T14:59:59Z, 2026-04-01, true",
        "2026-04-01T15:00:00Z, 2026-04-01, false",
        "2026-04-01T15:00:00Z, 2026-04-02, true"
    })
    void deadlineBoundary(String utcTime, String deadlineText, boolean expected) {
        Clock fixed = Clock.fixed(Instant.parse(utcTime), JAPAN);
        DeadlinePolicy policy = new DeadlinePolicy(fixed);

        boolean actual = policy.canSubmit(LocalDate.parse(deadlineText));

        assertEquals(expected, actual);
    }

    @Test
    void sameInstantCanBeDifferentCalendarDates() {
        Instant midnightInJapan = Instant.parse("2026-04-01T15:00:00Z");
        LocalDate deadline = LocalDate.parse("2026-04-01");

        assertEquals(false, new DeadlinePolicy(Clock.fixed(midnightInJapan, JAPAN)).canSubmit(deadline));
        assertEquals(true, new DeadlinePolicy(Clock.fixed(midnightInJapan, ZoneOffset.UTC)).canSubmit(deadline));
    }
}

mvn clean testで4件成功しました。締切日の当日を含む契約を表の3行で固定し、4件目で同じ2026-04-01T15:00:00Zが、日本では4月2日、UTCでは4月1日になることを確かめています。Clock.fixedで時刻とタイムゾーンを揃えれば、日付が変わる時刻まで待たずに再現できます。

「締切日」か「締切時刻」かで、型も変える

この例は日付単位で「4月1日いっぱい」を許可するルールです。「4月1日18:00 JSTを過ぎたら不可」なら、LocalDate同士の比較では時刻を表せません。InstantやZonedDateTimeで締切の瞬間を定め、Instant.now(clock)と比較します。

締切が業務上の日付なら、日付に変換するZoneIdを決めてからテストします。同じ瞬間でも、東京とUTCでは日付が異なる時間帯があります。締切が時刻まで決まった瞬間なら、たとえば「18:00 JST」を業務のタイムゾーンでInstantに変換し、clock.instant()と比べます。受付は締切ちょうども許すのかを仕様に書き、境界のテストに入れます。

Spring Bootの画面やAPIで同じ問題を扱うときは、サービスへ渡るClockをテスト側で固定し、HTTP応答でも締切の挙動を確かめます。Repositoryへの呼び出しをサービス単体で確かめたい場合は、下のMockito実習へ進めます。

次の実習|Spring BootSpring Bootのテストで時刻を固定する|ClockをDIして締切を確かめる 締切の瞬間に受付を終了する仕様で、テストだけ固定したClockを注入します。直前・ちょうど・直後を送り、MockMvcのJSONで受付可否が切り替わるところまで確認できます。 記事を読む 関連記事Spring BootのServiceをJUnit・Mockitoでテストする方法|Repositoryをモックする基本 Serviceの単体テストではSpring Boot全体を起動せず、JUnit 5とMockitoでRepositoryをモックします。 @Mock で依存先を作り、 @InjectMocks またはコンストラクタでServiceへ渡し、戻り値だけでなく保存処理が正しい引数で呼ばれたかも確認します。 記事を読む

さらに学ぶなら

日時に限らず「どの依存をテストから制御し、どこを実物で確かめるか」を考えたい人には『単体テストの考え方/使い方』を紹介します。出版社の紹介で対象範囲を確認できます。例に使う言語はC#であり、Clock.fixedやJUnitの操作を教える本ではありません。実務担当の本棚(Amazon・アフィリエイトを含みます)にも置いています。この記事の期限判定は本の掲載例や本人の読後体験として示したものではありません。

参照した公式資料

-設計・テスト・レビュー
-,