
# ApplicationContextRunner

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

## 使う理由

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

## 例

```dart
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` で失敗させる |

ランナーがしないこと:

- 設定ファイルは読まず、環境変数は設定しない限り空です。
- Web サーバーは起動しません。`spring.test.web-environment=mock` を設定します。本物のサーバーには `withPropertyValues(['spring.test.web-environment=random-port'])` を追加してください。

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

## run と runAsync

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

```dart
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) との対応

```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)` の代わりになります。

## 関連項目

- [自動構成とスターター](../spring-boot-dart/auto-configuration.md)
- [条件](../spring-boot-dart/conditions.md)
- [BeanOverride と @TestBean](bean-override.md)
