設定プロパティとプロファイルのユニットテスト

概要

このスキルは、JUnit 5 を使用した @ConfigurationProperties バインディング、環境固有の設定、プロパティ検証のユニットテストパターンを提供します。プロパティ名マッピング、型変換、検証制約、ネストされた構造、プロファイル固有の設定をカバーしており、完全な Spring コンテキスト起動なしでテストできます。

主な検証ポイント:

• @ConfigurationProperties とテストプロパティ間のプロパティプレフィックスマッチング
• 無効な値を持つ @Validated クラスでの検証トリガー
• Duration、DataSize、コレクション、マップの型変換が動作すること

使用する場面

• @ConfigurationProperties プロパティバインディングのテスト
• プロパティ名マッピングと型変換のテスト
• @NotBlank、@Min、@Max、@Email 制約を使用した設定検証
• 環境固有設定 (開発、本番) のテスト
• ネストされたプロパティ構造とコレクションのテスト
• プロパティが指定されていない場合のデフォルト値の確認
• Spring コンテキスト起動なしの高速設定テスト

手順

1. テスト依存関係をセットアップ: spring-boot-starter-test と AssertJ 依存関係を追加
2. ApplicationContextRunner を使用: 完全な Spring コンテキスト起動なしでプロパティバインディングをテスト
3. プロパティプレフィックスを定義: @ConfigurationProperties(prefix = "...") がテストプロパティパスと一致することを確認
4. すべてのプロパティパスをテスト: ネストされた構造とコレクションを含む各プロパティを検証
5. 検証制約をテスト: context.hasFailed() を使用して @Validated プロパティが無効な値を拒否することを確認
6. 型変換をテスト: Duration (30s)、DataSize (50MB)、コレクション、マップが正しく変換されることを確認
7. デフォルト値をテスト: テストプロパティで指定されていない場合、プロパティが正しいデフォルトを持つことを確認
8. プロファイル固有設定をテスト: 環境固有設定のために ApplicationContextRunner で @Profile を使用
9. エッジケースをテスト: 空文字列、null 値、型の不一致を含める

トラブルシューティングフロー:

• プロパティがバインドされない場合 → プレフィックスが一致しているか確認 (ケバブケースからキャメルケースへの変換)
• 検証がトリガーされない場合 → @Validated アノテーションが存在することを確認
• コンテキスト起動に失敗する場合 → 依存関係と @ConfigurationProperties クラス構造を確認

例

セットアップ: テスト依存関係

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-configuration-processor</artifactId>
  <scope>provided</scope>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-test</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.assertj</groupId>
  <artifactId>assertj-core</artifactId>
  <scope>test</scope>
</dependency>

基本パターン: プロパティバインディング

@ConfigurationProperties(prefix = "app.security")
@Data
public class SecurityProperties {
  private String jwtSecret;
  private long jwtExpirationMs;
  private int maxLoginAttempts;
  private boolean enableTwoFactor;
}

class SecurityPropertiesTest {

  @Test
  void shouldBindPropertiesFromEnvironment() {
    new ApplicationContextRunner()
      .withPropertyValues(
        "app.security.jwtSecret=my-secret-key",
        "app.security.jwtExpirationMs=3600000",
        "app.security.maxLoginAttempts=5",
        "app.security.enableTwoFactor=true"
      )
      .withBean(SecurityProperties.class)
      .run(context -> {
        SecurityProperties props = context.getBean(SecurityProperties.class);
        assertThat(props.getJwtSecret()).isEqualTo("my-secret-key");
        assertThat(props.getJwtExpirationMs()).isEqualTo(3600000L);
        assertThat(props.getMaxLoginAttempts()).isEqualTo(5);
        assertThat(props.isEnableTwoFactor()).isTrue();
      });
  }

  @Test
  void shouldUseDefaultValuesWhenPropertiesNotProvided() {
    new ApplicationContextRunner()
      .withPropertyValues("app.security.jwtSecret=key")
      .withBean(SecurityProperties.class)
      .run(context -> {
        SecurityProperties props = context.getBean(SecurityProperties.class);
        assertThat(props.getJwtSecret()).isEqualTo("key");
        assertThat(props.getMaxLoginAttempts()).isZero();
      });
  }
}

検証テスト

@ConfigurationProperties(prefix = "app.server")
@Data
@Validated
public class ServerProperties {
  @NotBlank
  private String host;

  @Min(1)
  @Max(65535)
  private int port = 8080;

  @Positive
  private int threadPoolSize;
}

class ConfigurationValidationTest {

  @Test
  void shouldFailValidationWhenHostIsBlank() {
    new ApplicationContextRunner()
      .withPropertyValues(
        "app.server.host=",
        "app.server.port=8080",
        "app.server.threadPoolSize=10"
      )
      .withBean(ServerProperties.class)
      .run(context -> {
        assertThat(context).hasFailed()
          .getFailure()
          .hasMessageContaining("host");
      });
  }

  @Test
  void shouldPassValidationWithValidConfiguration() {
    new ApplicationContextRunner()
      .withPropertyValues(
        "app.server.host=localhost",
        "app.server.port=8080",
        "app.server.threadPoolSize=10"
      )
      .withBean(ServerProperties.class)
      .run(context -> {
        assertThat(context).hasNotFailed();
        assertThat(context.getBean(ServerProperties.class).getHost()).isEqualTo("localhost");
      });
  }
}

型変換テスト

@ConfigurationProperties(prefix = "app.features")
@Data
public class FeatureProperties {
  private Duration cacheExpiry = Duration.ofMinutes(10);
  private DataSize maxUploadSize = DataSize.ofMegabytes(100);
  private List<String> enabledFeatures;
  private Map<String, String> featureFlags;
}

class TypeConversionTest {

  @Test
  void shouldConvertDurationFromString() {
    new ApplicationContextRunner()
      .withPropertyValues("app.features.cacheExpiry=30s")
      .withBean(FeatureProperties.class)
      .run(context -> {
        assertThat(context.getBean(FeatureProperties.class).getCacheExpiry())
          .isEqualTo(Duration.ofSeconds(30));
      });
  }

  @Test
  void shouldConvertCommaDelimitedList() {
    new ApplicationContextRunner()
      .withPropertyValues("app.features.enabledFeatures=feature1,feature2")
      .withBean(FeatureProperties.class)
      .run(context -> {
        assertThat(context.getBean(FeatureProperties.class).getEnabledFeatures())
          .containsExactly("feature1", "feature2");
      });
  }
}

ネストされたプロパティ、プロファイル固有設定、コレクションバインディング、高度な検証パターン については references/advanced-examples.md を参照してください。

ベストプラクティス

• すべてのプロパティバインディングをテスト (ネストされた構造とコレクションを含む)
• すべての @NotBlank、@Min、@Max、@Email、@Positive アノテーションの検証制約をテスト
• デフォルト値とカスタム値の両方をテスト してフォールバック動作を確認
• ApplicationContextRunner を使用 して高速なコンテキスト不要のテスト実施
• プロファイル固有設定を個別にテスト (@Profile 付き)
• Duration、DataSize、コレクション、マップの型変換を検証
• エッジケースをテスト: 空文字列、null 値、型の不一致、範囲外の値

制約と警告

• ケバブケースからキャメルケースへの変換: プロパティ app.my-property は Java の myProperty にマッピング
• ルーズバインディング: Spring Boot はデフォルトでルーズバインディングを使用 (必要に応じてストリクトバインディングを使用)
• @Validated 必須: 制約検証を有効にするには @Validated アノテーションを追加
• @ConstructorBinding: コンストラクタバインディング使用時はすべてのパラメータがバインド可能である必要あり
• リストインデックス: [0]、[1] 記法を使用 (リストの場合は連続したインデックスを確保)
• Duration 形式: ISO-8601 (PT30S) または簡易構文 (30s、1m、2h) を受け入れ
• コンテキスト分離: 各 ApplicationContextRunner は共有状態のない新しいコンテキストを作成
• プロファイル有効化: プロファイルテストの場合は withPropertyValues() で spring.profiles.active=profileName を使用

トラブルシューティング

問題	原因	解決策
プロパティがバインドされない	プレフィックス不一致	@ConfigurationProperties(prefix="...") がプロパティパスと一致することを確認
検証がトリガーされない	@Validated が欠落	設定クラスに @Validated アノテーションを追加
コンテキスト起動に失敗	依存関係が欠落	テストスコープに spring-boot-starter-test があることを確認
ネストされたプロパティが null	内部クラスが欠落	ネストされたクラスで @Data を使用するか、ゲッター/セッターを提供
コレクションバインディング失敗	インデックス記法が誤り	[0]、[1] 記法を使用 ((0)、(1) は使用不可)