ApplicationContextRunner

ApplicationContextRunner は、テストごとに使い捨ての小さなコンテキストを起動し、どのプロパティと Bean のもとで自動構成が何を生成するかを確認します。スターターの作者のためのツールで、Spring Boot の同名のランナーに当たります。

使う理由

スターターの自動構成は、周囲の状況に反応しなければなりません。デフォルトで Bean を生成し、アプリケーションが独自のものを宣言すれば身を引き、プロパティで変わり、不正な値では失敗します。ケースごとにアプリケーション全体を起動すると遅く、その設定ファイルも読んでしまいます。ランナーは、指定したモジュールだけを、指定したプロパティで起動します。

例

import 'package:neon_cache/spring_auto_configuration.dart';
import 'package:spring_boot_starter_test/spring_boot_starter_test.dart';
import 'package:test/test.dart';

void main() {
  final runner = const ApplicationContextRunner()
      .withAutoConfiguration(neonCacheAutoConfiguration);

  test('creates a cache by default', () {
    runner.run((context) {
      expect(context, hasSingleBean<Cache>());
    });
  });

  test('backs off for the application cache', () {
    // 自動構成の前に登録される、アプリケーション自身の Cache。
    runner.withBean<Cache>(AppCache.new).run((context) {
      expect(context, hasSingleBean<Cache>()); // 身を引かなければ二つになる
      expect(context.getBean<Cache>(), isA<AppCache>());
    });
  });

  test('can be switched off', () {
    runner.withPropertyValues(['neon.cache.enabled=false']).run((context) {
      expect(context, doesNotHaveBean<Cache>());
    });
  });

  test('rejects a negative size', () {
    runner.withPropertyValues(['neon.cache.size=-1']).run((context) {
      expect(context, hasFailed(isA<BeanCreationException>()));
    });
  });
}

メソッド

ランナーはイミュータブルです。各 with... メソッドは新しいランナーを返すため、基本のランナーを共有し、テストごとに拡張できます。

メソッド 働き
withAutoConfiguration(module, [metadata]) テスト対象の自動構成モジュールを追加する。order、before、after を持つ場合は、その @AutoConfigurationModule を metadata として渡す: Dart は実行時に変数のアノテーションを読めない。モジュールは、追加した順序にかかわらず、Spring Boot と同じ方法で並べ替えられる
withUserConfiguration(module) アプリケーションのモジュールを追加する。自動構成の前に登録されるため、その Bean は条件から見える
withBean<T>(supplier, name:) 構成の前に Bean を登録する。実行ごとに新しいインスタンスになる。@ConditionalOnMissingBean は身を引く。身を引かない誤りは 2 つ目の Bean として、あるいは名前が衝突すれば起動の失敗として現れる。Bean を置き換えることは決してない
withBeanOverride<T>(instance, name:) BeanOverride と同じく、構成が登録された後に Bean を置き換える。身を引く誤りを隠してしまうため、身を引くことのテストには withBean を使う
withPropertyValues(['a=b', 'c: d', 'flag']) key=value または key:value の形のプロパティ。最初の = か : で分割され、前後の空白は取り除かれる。区切りがなければ空の値。他のすべてのソースより優先される
withSystemEnvironment({...}) 環境変数。以前の呼び出しのものに追加される (neon.cache.size には NEON_CACHE_SIZE)
withInitializer(initializer) リフレッシュの前に呼ばれる ApplicationContextInitializer。追加した順 (order は使われない)
withParent(context) 親コンテキスト。子コンテキストで動くスターター向け
withAllowBeanDefinitionOverriding(bool) 定義が同じ名前の別の定義を置き換えられるようにする。デフォルトは無効
withAllowCircularReferences(bool) false がデフォルトで、動く唯一の値。true はすべての実行を UnsupportedError で失敗させる

ランナーがしないこと:

アプリケーションと同じく、@ConfigurationProperties の Bean はバインドされ、緩い名前も使えます。

run と runAsync

run(body) は AssertableApplicationContext を本体に渡し、本体が戻ると close() でコンテキストを閉じます。await する本体には runAsync を使ってください。コンテキストは refreshAsync() でリフレッシュされ、返された Future が完了すると closeAsync() で閉じられます。run では、本体の最初の await でコンテキストが閉じられてしまいます。

test('calls the client', () async {
  await runner.runAsync((context) async {
    expect(await context.getBean<CatalogClient>().find('1'), isNotNull);
  });
});

AssertableApplicationContext

起動に失敗したコンテキストも、例外を投げる代わりに渡されるため、テストは構成が不正な入力を拒否することを確認できます。

メンバー 意味
startupFailure 起動を止めたエラー。起動した場合は null
hasFailed コンテキストが起動に失敗したかどうか
context 起動したコンテキスト。起動しなかった場合は失敗を持つ StateError
environment Environment。起動に失敗した後も使える
getBean<T>({qualifier})、getBeanByName(name) Bean。一致するものがないか、コンテキストが起動しなかった場合は例外を投げる
getBeanNamesForType<T>() 親ではなく、このコンテキストにある T の Bean の名前
containsBean(name) その名前の Bean が、ここか親に存在するかどうか

マッチャー

マッチャー コンテキストが次の条件を満たすと成功する
hasSingleBean<T>() T の Bean がちょうど一つ
hasBean<T>() T の Bean が少なくとも一つ
doesNotHaveBean<T>() T の Bean がない
hasBeanNamed('name') その名前または別名の Bean がある
hasFailed([matcher]) 起動に失敗した (AssertableApplicationContext のみ)。マッチャーがあれば、エラーがそれに一致しなければならない

ApplicationContextRunner のコンテキスト、springBootTest のハンドル、あるいはアプリケーションコンテキストのような任意の ListableBeanFactory を受け取ります。失敗すると、見つかった Bean、またはコンテキストが起動しなかった理由を列挙します。AssertJ と同じく、親コンテキストの Bean も数えられます。

Spring (Java) との対応

new ApplicationContextRunner()
    .withConfiguration(AutoConfigurations.of(NeonCacheAutoConfiguration.class))
    .withBean(Cache.class, AppCache::new)
    .withPropertyValues("neon.cache.size=-1")
    .run(context -> assertThat(context).hasFailed());

違い: withAutoConfiguration(module, metadata) はモジュールのアノテーションを手で受け取ります。withBean<T>(supplier) は型を型引数として、サプライヤーとともに受け取ります。withBeanOverride と withSystemEnvironment に対応するものは Boot にはありません。マッチャーが AssertJ の assertThat(context) の代わりになります。

関連項目