
# spring_boot_starter_test

`spring_boot_starter_test` gives tests the real application. It is the Dart counterpart of `spring-boot-starter-test`: `springBootTest` is `@SpringBootTest`, `BeanOverride` is `@MockitoBean` and `@TestBean`, `MockMvc` is MockMvc, `ApplicationContextRunner` is Spring Boot's runner, and the containers are Testcontainers with `@ServiceConnection`.

Tests are written as plain functions in `main`, or as classes with annotations (`@SpringBootTest()`, `@Autowired()`, `@Test()`) the way Spring tests look; the generator turns the classes into the same functions. The package is built on `test_api` and `matcher`, so it works with both `package:test` and `flutter_test`.

## Why

A unit test that creates its objects by hand cannot tell you whether the application starts: whether the config files bind, the beans find each other, and the controllers answer as a client expects. This package starts the real application inside a test, once for many tests, and lets the test change only what it must:

- the whole application with test properties and profiles, and its beans;
- a bean that talks to the outside world (a payment provider, a mail server, the clock) replaced with a fake or a mock;
- the controllers called through the real web layer without a socket (`MockMvc`), or a real server on a free port;
- a starter's auto-configuration checked under each set of properties (`ApplicationContextRunner`);
- what the application logged;
- a database, a Keycloak or any Docker image started for the tests and wired to the application.

## Setup

```yaml
# pubspec.yaml
dev_dependencies:
  spring_boot_starter_test: ^0.9.0
  test: ^1.25.0            # or flutter_test
  build_runner: ^2.17.0
  spring_core_dart_generator: ^0.9.0
```

Run `dart run build_runner build` (or `watch`) before the tests: they use the `springApplication` the generator wrote for your entry point, and the generated code of test classes.

## Example

As a function:

```dart
// test/checkout_test.dart
import 'package:spring_boot_starter_test/spring_boot_starter_test.dart';
import 'package:test/test.dart';

import '../bin/spring_gen/main.spring.dart'; // the generated springApplication

void main() {
  final gateway = FakeGateway();

  // The real shop, started once for the tests below, with a fake gateway.
  final app = springBootTest(
    springApplication,
    profiles: ['test'],                              // reads application-test.yml
    properties: {'shop.max-basket-size': 3},         // above every other source
    overrides: [BeanOverride<PaymentGateway>(gateway)],
  );

  test('checkout pays through the fake', () {
    app.getBean<Checkout>().pay(10);
    expect(gateway.charged, [10]);
  });

  test('GET /api/books/1111 answers the book', () async {
    await app.mockMvc
        .get('/api/books/1111')
        .andExpect(status: 200, json: containsPair('title', 'Dune'));
  });
}
```

The same as a class:

```dart
import 'spring_gen/checkout.test.spring.dart'; // generated, in test/spring_gen/

@SpringBootTest(properties: {'shop.max-basket-size': 3})
@ActiveProfiles(['test'])
class CheckoutTest {
  @TestBean()
  final PaymentGateway gateway = FakeGateway(); // replaces the only PaymentGateway

  @Autowired()
  late Checkout checkout;

  @Test()
  void paysThroughTheFake() {
    checkout.pay(10);
    expect((gateway as FakeGateway).charged, [10]);
  }
}

void main() => runSpringTests();
```

```bash
dart run build_runner build
dart test
```

## What is inside

- [springBootTest](spring-boot-test.md): the whole application in a test, its options and the returned context.
- [Test properties](test-properties.md): `test/resources/`, profiles, property files, dynamic properties, the environment and their precedence.
- [Test classes](test-classes.md): `@SpringBootTest()`, `@Autowired()` fields, `@Test()`, before and after, `@DirtiesContext()`, `@Nested()`.
- [BeanOverride and @TestBean](bean-override.md): replacing beans with fakes and mocks.
- [MockMvc](mock-mvc.md): requests to the controllers in memory, and `webEnvironment` for a real server.
- [ApplicationContextRunner](application-context-runner.md): testing a starter's auto-configuration, and the bean matchers.
- [Captured logs](captured-logs.md): `captureLogs` and `@CapturedOutput()`.
- [Containers](containers.md): PostgreSQL, Keycloak or any image in Docker, with `@ServiceConnection()`, and networks between them.
- [Differences from Spring](differences.md): what works differently than in Spring Boot's tests.

## In Spring (Java)

```java
@SpringBootTest(properties = "shop.max-basket-size=3")
@ActiveProfiles("test")
class CheckoutTest {
  @MockitoBean PaymentGateway gateway;
  @Autowired Checkout checkout;

  @Test
  void paysThroughTheGateway() { ... }
}
```

Differences that matter:

- `springBootTest` is a function for the tests of a `main` or `group`; test classes are generated into it. Each test file starts its own context: there is no context cache across files.
- `BeanOverride` and `@TestBean()` take a ready-made object; there are no generated mocks and no automatic reset.
- The OS environment is empty in tests unless `systemEnvironment` (or `@TestEnvironment`) sets it.
- The one test slice is `@DataTest` of `spring_boot_starter_data`; there is no `@WebMvcTest`.

## See also

- [spring_boot_dart](../spring-boot-dart/index.md)
- [spring_boot_starter_web: testing](../spring-boot-starter-web/testing.md)
- [The generator: tests](../spring-core-dart-generator/tests.md)
- [External configuration](../spring-boot-dart/configuration/index.md)
- [What a build contains](optimizations.md)
