
# BeanOverride と @TestBean

テストで使えないもの (決済プロバイダー、実時間の時計、メールサーバー) と通信する Bean は、テストのオブジェクトに置き換えます。元の定義はどの Bean も生成される前に取り除かれるため、本物のオブジェクトも、それが接続するはずだったものも、決して作られません。それを注入するすべての Bean が置き換えを受け取ります。

Spring の `@TestBean` と `@MockitoBean` に当たりますが、生成されるモックではなく、出来上がったオブジェクトを使います。

## 使う理由

本物のカードに課金したり、本物のメールを送ったりするテストは、遅く、不安定で、危険です。一つの Bean を置き換えればアプリケーションの残りは本物のままなので、テストは結び付け、プロパティ、コントローラーを引き続き確認できます。

## 例

関数として:

```dart
final gateway = FakeGateway();
final clock = FixedClock(DateTime(2026, 1, 1));

final app = springBootTest(
  springApplication,
  overrides: [
    BeanOverride<PaymentGateway>(gateway),                  // その型の唯一の Bean
    BeanOverride<Clock>(clock),
    BeanOverride<PaymentGateway>(MockGateway(), name: 'sandbox'), // 複数の中の一つを名前で
  ],
);
```

クラスとして:

```dart
@SpringBootTest()
class PaymentTest {
  @TestBean(name: 'sandbox')            // sandbox という名前の Bean を置き換える
  final gateway = FakeGateway();

  @TestBean()                           // 唯一の Clock を置き換える
  final Clock clock = FixedClock(DateTime(2026, 1, 1));

  @TestBean()                           // Mailer の Bean がない: 追加する
  final Mailer mailer = RecordingMailer();

  @Autowired()
  late Checkout checkout;

  @Test()
  void paysThroughTheFake() {
    checkout.pay(12.5);
    expect(gateway.charged, [12.5]);
  }
}
```

## どの Bean が置き換えられるか

| 指定 | 置き換えるもの |
|---|---|
| `name:` | その名前の Bean、またはその名前を別名とする Bean |
| 名前なし | `T` の唯一の Bean。複数ある場合は、ただ一つの `@Primary` のもの。複数あって単一のプライマリーがなければ、それらを列挙する `StateError` で起動が失敗する |
| `T` の Bean がない | 何も置き換えない: インスタンスは、型にちなんだ名前 (`PaymentGateway` なら `paymentGateway`) の新しい Bean として追加される |

置き換えは、元のものの名前、別名、修飾子、順序、`@Primary` / `@Fallback` のフラグを保つため、`@Qualifier` の注入ポイントも引き続きそれを見つけます。複数のオーバーライドが同じ Bean を置き換える場合は、最後のものが優先されます。

## どの型のもとで

- **`BeanOverride<T>(instance)`** は置き換えを `T` のもとにだけ登録します。元のものが別の型でも見つかっていた (2 つ目のインターフェースを実装していた) 場合、その型ではもう見つかりません。
- **`BeanOverride.named(instance, name: ...)`** は元のものの型 (それ自身のクラスを除く) を保ち、`T` (`Object` でなければ) とインスタンスのクラスを追加します。偽物が元のものの型の一部しか実装していない場合は、偽物自身の型を指定してください: `BeanOverride.named(fake, name: 'sandbox', types: [FakeGateway, PaymentGateway])`。
- **`@TestBean(name: ...)`** は `BeanOverride.named` を生成します。フィールドの値がコンストラクターで作られている場合 (`= FakeGateway()`。名前付きコンストラクターやカスケードも含む)、生成されるオーバーライドはそのクラスと、その public なスーパータイプをすべて列挙します。それ以外の値 (`= Fakes.gateway()`) では元のものの型が保たれます。
- **名前なしの `@TestBean()`** は、フィールドの宣言された型で `BeanOverride<Type>(value)` を生成します。型は書かれていなければならず (`final Clock clock = ...`)、そうでなければビルドが失敗します。`@TestBean(type: Clock)` は型を明示的に指定します。

## 知っておくべきこと

- **テスト間で何もリセットされません。** 値はテストクラスや `main` とともに一度だけ作られます。共有の偽物やモックは `setUp` (`@BeforeEach`) でリセットするか、`@DirtiesContext` を使ってください。
- **どんな偽物やモックでも使えます。** たとえば `package:mocktail` のものです。スターターは独自のモックライブラリを持ちません (Spring は Mockito を同梱しています)。
- **綴りを間違えた `name:` は失敗しません。** その名前の Bean がなければ、インスタンスはその名前で追加され、本物の Bean は残ります。よくある症状は、本物の Bean がまだ使われていることや、`T` の Bean が二つあるというエラーです。
- **`name:` がなく、`T` の Bean もない場合**、インスタンスは `defaultBeanName(T)` として登録されます。無関係な Bean がすでにその名前を持っていると、その Bean は取り除かれます。
- `ApplicationContextRunner` では、`withBeanOverride<T>(instance)` が、構成が登録された後に同じことを行います。

## Spring (Java) との対応

```java
@MockitoBean PaymentGateway gateway;              // 生成される Mockito のモック
@TestBean(name = "sandbox") PaymentGateway sandbox;
static PaymentGateway sandbox() { return new FakeGateway(); }
```

違い: 生成されるモックやスパイではなく出来上がったオブジェクトを使う、`@MockitoBean(reset)` はない、そして既存の Bean がないオーバーライドは、失敗する代わりにインスタンスを追加します。

## 関連項目

- [springBootTest](spring-boot-test.md)
- [テストクラス](test-classes.md)
- [ApplicationContextRunner](application-context-runner.md)
