
# Tests: @SpringBootTest and @DataTest

The `spring_test` builder reads the test classes of a test file, the classes annotated `@SpringBootTest()` (from `spring_boot_starter_test`) or `@DataTest()` (from `spring_boot_starter_data`), and writes a function `runSpringTests()` that registers their tests with `package:test`. The test file's `main` calls that function.

## Why

`package:test` runs only the functions registered with `group` and `test` from `main`. In Spring, JUnit finds the `@Test` methods of a class with reflection, and Spring's test extension fills the `@Autowired` fields. Dart has no reflection on the VM in AOT mode, in Flutter or on the web, so this work is done at build time: the builder reads the class and writes the `group`, `setUp` and `test` calls that you would otherwise write by hand.

The annotations themselves do nothing at run time. All their meaning is in the generated file.

## Input and output

For each file `test/<name>_test.dart` the builder writes `test/spring_gen/<name>.test.spring.dart`. The path below `test/` is kept:

| Test file | Generated file |
|---|---|
| `test/checkout_test.dart` | `test/spring_gen/checkout.test.spring.dart` |
| `test/orders/basket_test.dart` | `test/spring_gen/orders/basket.test.spring.dart` |

The generated files are in their own folder, and their names do not end in `_test.dart`, so `dart test` does not take them for tests.

The builder writes nothing, and says nothing, for a test file that does not contain the text `SpringBootTest` or `DataTest`, or that declares no class annotated with one of them. Files outside `test/`, and files whose name does not end in `_test.dart`, are never read.

## A first test

```dart
// test/shop_class_test.dart
import 'package:neon_books_server/src/catalog/catalog_service.dart';
import 'package:neon_books_server/src/shop/clock.dart';
import 'package:spring_boot_starter_test/spring_boot_starter_test.dart';
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';
import 'package:test/test.dart';

import 'spring_gen/shop_class.test.spring.dart'; // generated

class FixedClock implements Clock {
  @override
  DateTime now() => DateTime.utc(2026, 10, 27, 12);
}

@SpringBootTest(properties: {'neon.shop.delivery-time': '3d'})
@ActiveProfiles(['dev', 'test'])
@TestEnvironment({'NEON_SHOP_NAME': 'Night Books'})
class ShopTest {
  // Replaces the `clock` bean.
  @TestBean(type: Clock, name: 'clock')
  final clock = FixedClock();

  @Autowired()
  late MockMvc mvc;

  @Autowired()
  late Catalog catalog;

  @Value(r'${neon.shop.name}')
  late String shopName;

  @Test('properties from the annotation and the environment')
  void configuration() => expect(shopName, 'Night Books');

  @Test()
  @Tag('logs')
  void logsOfTheTest() => catalog.search('poetry', 0);

  @Nested('the catalog')
  final theCatalog = TheCatalog();
}

class TheCatalog {
  @Autowired()
  late Catalog catalog;

  @Test()
  void hasTheSampleBooks() => expect(catalog.search('', 0).total, 8);
}

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

The builder writes (shortened from the real file of the `server_guide` example):

```dart
// test/spring_gen/shop_class.test.spring.dart
// GENERATED CODE - DO NOT MODIFY BY HAND
// Generated by spring_core_dart_generator from the @SpringBootTest classes of shop_class_test.dart.

// ignore_for_file: type=lint, unused_import, unused_shown_name, duplicate_import

// The test file's imports, copied.
import 'package:neon_books_server/src/catalog/catalog_service.dart';
import 'package:neon_books_server/src/shop/clock.dart';
import 'package:spring_boot_starter_test/spring_boot_starter_test.dart';
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';
import 'package:test/test.dart';

// The test file itself.
import '../shop_class_test.dart';

import 'package:spring_boot_starter_test/generated.dart' as _sbt;

// The application's generated file, which declares springApplication.
import '../../bin/spring_gen/main.spring.dart' as _app0;

/// Declares the tests of the `@SpringBootTest` classes of `shop_class_test.dart`.
void runSpringTests() {
  _sbt.group('ShopTest', () {
    final $instance = ShopTest();
    final $app = _sbt.springBootTest(
      _app0.springApplication,
      properties: {'neon.shop.delivery-time': '3d'},
      profiles: ['dev', 'test'],
      systemEnvironment: {'NEON_SHOP_NAME': 'Night Books'},
      overrides: [_sbt.BeanOverride<Clock>($instance.clock, name: 'clock')],
    );
    _sbt.setUp(() {
      $instance.mvc = $app.mockMvc;
      $instance.catalog = $app.getBean();
      $instance.shopName = $app.value(r'${neon.shop.name}');
    });
    _sbt.test(
      'properties from the annotation and the environment',
      () => $instance.configuration(),
    );
    _sbt.test(
      'logs of the test',
      () => $instance.logsOfTheTest(),
      tags: ['logs'],
    );
    _sbt.group('the catalog', () {
      _sbt.setUp(() {
        $instance.theCatalog.catalog = $app.getBean();
      });
      _sbt.test(
        'has the sample books',
        () => $instance.theCatalog.hasTheSampleBooks(),
      );
    });
  });
}
```

What to notice:

- **One group per class.** Each test class becomes a `group` named after the class. One instance of the class is created for the whole group, with `ShopTest()`.
- **One context per class.** `springBootTest(...)` starts the application before the first test of the group and closes it after the last. The annotations of the class become its named arguments.
- **Fields are set before every test.** The `@Autowired` and `@Value` fields are assigned in `setUp`, so after a context restart (`@DirtiesContext`) they hold the new beans.
- **No bean type is written.** `$instance.catalog = $app.getBean();` takes its type argument from the field, through Dart's type inference. The builder never needs to know where `Catalog` is declared.
- **Test names.** A test is named by `@DisplayName('...')`, else by the argument of `@Test('...')`, else by the method name split into lower-case words: `hasTheSampleBooks` becomes `has the sample books`, `readsURLService` becomes `reads url service`.

## How the builder works

1. **A cheap text check.** A file that does not contain `SpringBootTest` or `DataTest` is skipped at once.
2. **The file is parsed, not resolved.** The builder reads the test file as syntax only, which is fast. Annotations are recognized by their simple name, with or without an import prefix (`@Test()` and `@sbt.Test()` are the same).
3. **The application is found.** The builder looks at the `.dart` files of `bin/` and `lib/` (generated files excluded) for a top-level function annotated `@SpringBootApplication`. See [Which application starts](#which-application-starts).
4. **The imports are copied.** The generated file repeats every import of the test file, with the same prefixes and `show` / `hide` combinators, and imports the test file itself. A relative import is re-pointed from `test/spring_gen/`. So every type and constant written in an annotation means the same thing in the generated file.
5. **The code is written and formatted.** One `group` per test class, in file order.

The test file is resolved with the analyzer only in two cases where the syntax does not tell enough, both about `@TestBean` fields:

- a `@TestBean(name: ...)` field without `type:` whose value is a call (`= FakeGateway()`, `= Fakes.gateway()`): when the value is a constructor call, the fake is registered under its class and that class's supertypes;
- a `@TestBean` field whose type is inferred, or named without `?` and not declared in the test file: it may be a nullable type alias (`typedef MaybeMailer = Mailer?;`).

The generated file imports `package:spring_boot_starter_test/generated.dart` (as `_sbt`), so the test package needs `spring_boot_starter_test` as a dev dependency.

## What main must do

The test file must import its generated file and call `runSpringTests()` from `main`:

```dart
import 'spring_gen/checkout.test.spring.dart';

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

`main` may register other tests too, before or after the call. When the import is missing, the build logs a warning that names the line to add:

```text
test/checkout_test.dart does not import 'spring_gen/checkout.test.spring.dart': add import 'spring_gen/checkout.test.spring.dart'; and void main() => runSpringTests();
```

The generated file imports the test file, and the test file imports the generated file. Dart allows such an import cycle between libraries.

## Which application starts

`springBootTest` needs the `springApplication` getter, which the main builder writes into the `.spring.dart` of the application's `main` (see [The application: @SpringBootApplication](spring-boot-application.md)). The test builder picks the entry point like this:

| Situation | Entry point |
|---|---|
| `application:` is given | that file (a path in the package); it may be anywhere in the package, for example `test/data_test/app/data_test_app.dart`, as long as it declares a `@SpringBootApplication` function |
| one `@SpringBootApplication` function in `bin/` or `lib/` | that one |
| none | a build error |
| several | a build error that asks to name one |

The generated file imports the application's generated file: `package:<package>/spring_gen/...` for an entry point in `lib/`, a relative path otherwise (`../../bin/spring_gen/main.spring.dart`). The main builder generates `.spring.dart` files for `test/` too, so a small application declared under `test/` for one group of tests works the same way.

```dart
// Two applications in bin/: name the one to start.
@SpringBootTest(application: 'bin/admin.dart')
class AdminTest {
  // ...
}
```

## The options of @SpringBootTest

The builder copies each argument's source into the call of `springBootTest`. Options that are not written are not passed, and `springBootTest` uses its own defaults (no arguments, `test/resources` as the resource directory, `WebEnvironment.mock`).

| Annotation | Argument of `springBootTest` |
|---|---|
| `@SpringBootTest(args: [...])` | `args:` |
| `@SpringBootTest(properties: {...})` | `properties:` |
| `@TestPropertySource(properties: {...})` | `properties:`, merged with the one above (`{...a, ...b}`, the later one wins) |
| `@TestPropertySource(locations: [...])` | `propertyFiles:` |
| `@SpringBootTest(resourceDirectories: [...])` | `resourceDirectories:` |
| `@SpringBootTest(webEnvironment: ...)` | `webEnvironment:` |
| `@SpringBootTest(application: '...')` | which application starts (see above) |
| `@ActiveProfiles([...])` | `profiles:` |
| `@TestEnvironment({...})` | `systemEnvironment:` |
| static `@DynamicPropertySource` methods | `dynamicProperties:` |
| static `@ContextInitializer` methods | `initializers:`, each as `ApplicationContextInitializer.of(method)` |
| `@TestBean` fields | `overrides:`, each as a `BeanOverride` |

`@SpringBootTest`, `@DataTest`, `@ActiveProfiles`, `@TestPropertySource`, `@TestEnvironment` and `@Testcontainers` belong on the class. On a method they fail the build, since there is one context per class.

An annotation argument may name a static member of the test class without the class name, as Dart allows inside the class. The generated code is outside the class, so the builder adds the class name (`Fixtures.port` for `port`).

## Members of a test class

### Injected fields

`@Autowired()`, `@Value('...')` and `@LocalServerPort()` fields must be `late`, not `final`, not static, public, and have their type written:

```dart
@Autowired()
late Checkout checkout;
```

The value the field receives depends on its declared type:

| Field | Generated assignment |
|---|---|
| `@LocalServerPort() late int port` | `$app.localServerPort` |
| `@Value('${a.b}') late String x` | `$app.value(...)`; for a nullable type `$app.optionalValue(...)` |
| `SpringBootTestContext` | the test context itself |
| `MockMvc` | `$app.mockMvc` |
| `ApplicationContext`, `ConfigurableApplicationContext` | `$app.context` |
| `Environment`, `ConfigurableEnvironment` | `$app.environment` |
| `List<T>`, `Iterable<T>` | `$app.getBeans()` |
| `Set<T>` | `$app.getBeans<T>().toSet()` |
| `Map<String, T>` | `$app.context.getBeansOfType<T>()` |
| `ObjectProvider<T>`, `ObjectFactory<T>`, `Provider<T>` | `$app.context.getBeanProvider()` |
| any other nullable type `T?` | `$app.findBean()` (null when there is no such bean) |
| any other type | `$app.getBean()` |

A `@Qualifier('name')` on the field is passed as `qualifier:` to `getBean`, `findBean`, `getBeans` and `getBeanProvider`.

A `@CapturedOutput() late CapturedLogs logs;` field receives the log records of the test: the group starts with `final $logs = _sbt.captureLogs();` and the field is set to it before each test.

### Test methods and lifecycle methods

| Annotation | Must be | Generated |
|---|---|---|
| `@Test()` | an instance method without parameters | `_sbt.test(name, () => $instance.method())` |
| `@BeforeEach()` | an instance method without parameters | `_sbt.setUp(...)` |
| `@AfterEach()` | an instance method without parameters | `_sbt.tearDown(...)` |
| `@BeforeAll()` | static, in the test class (not a `@Nested` one) | `_sbt.setUpAll(...)`, before the context starts |
| `@AfterAll()` | static, in the test class | `_sbt.tearDownAll(...)`, after the context closes |

`@BeforeAll` methods must be static because they run before the class is created. The `tearDownAll` of an `@AfterAll` method is registered before `springBootTest`, and `package:test` runs `tearDownAll` callbacks in reverse order, so it runs after the context is closed.

A test method may return a `Future`; `package:test` waits for it.

### Options of a test or a group

| Annotation | On | Generated |
|---|---|---|
| `@DisplayName('...')` | a `@Test` method | the test's name |
| `@Disabled()` or `@Disabled('why')` | a class, a `@Test` method, a `@Nested` field | `skip: true` or `skip: 'why'` |
| `@Tag('slow')` (repeatable) | the same | `tags: [...]` |
| `@TestOptions(timeout:, retry:, testOn:, onPlatform:)` | the same | the same named arguments of `test` or `group` |
| `@DirtiesContext()` | a class or `@Nested` field | a new context after each test of the group (`_sbt.setUp($app.markDirty)`) |
| `@DirtiesContext()` | a `@Test` method | marks the context dirty when the test starts, so the next test gets a new one |

On a member that is not a `@Test` method (or a `@Nested` field), these annotations fail the build instead of being ignored.

### Nested groups

A field annotated `@Nested()` becomes a group inside the class's group. Its value must be created with a class of the same test file (`final theCatalog = TheCatalog();`). The nested class has its own `@Autowired` fields, tests and `@BeforeEach` / `@AfterEach` methods, and shares the context of the outer class. Its name is the argument of `@Nested('...')`, else the field name in words.

`@TestBean`, `@Container`, `@BeforeAll` and `@AfterAll` belong to the outer class: in a nested class they fail the build.

### Superclasses

A test class may extend a class declared in the same test file: its annotated members are included, the superclass's first. A superclass declared in another file cannot be seen, because the file is read as syntax. The build then logs a warning:

```text
test/shop_test.dart: ShopTest extends BaseTest from another file; its @Test, @Autowired and other annotated members are not seen. Declare it in the test file.
```

## @TestBean

A `@TestBean` field replaces a bean of the application with the field's value. The field needs a value, and the generated override depends on what is written:

| Field | Generated override |
|---|---|
| `@TestBean() final PaymentGateway gateway = FakeGateway();` | `BeanOverride<PaymentGateway>($instance.gateway)` |
| `@TestBean(type: Clock, name: 'clock') final clock = FixedClock();` | `BeanOverride<Clock>($instance.clock, name: 'clock')` |
| `@TestBean(name: 'gateway') final gateway = FakeGateway();` | `BeanOverride.named(..., name: 'gateway', types: [...])`, with the types of `FakeGateway` and its supertypes, read from the resolved file |
| `@TestBean() final Mailer? mailer = ...;` | `BeanOverride<Mailer>(...)`; when the value is `null` at run time the test fails with `@TestBean field ShopTest.mailer is null: it needs a value` |

A `@TestBean()` field without `name:` or `type:` and without a written type fails the build: the builder cannot tell which bean it replaces.

## @DataTest

`@DataTest()` (from `spring_boot_starter_data`) starts a slice of the application: its data beans on an in-memory database. Each test runs in a transaction that is rolled back at the end. The generated code calls `package:spring_boot_starter_data/testing.dart` by its URL, so `spring_boot_starter_test` and the data starter do not depend on each other.

```dart
// test/data_test/commit_test.dart
@DataTest(application: 'test/data_test/app/data_test_app.dart')
class CommitTest {
  @Autowired()
  late BookRepository books;

  @Test()
  @Commit()
  Future<void> commitsABook() async {
    await books.save(Book(title: 'Dune', year: 1965));
  }

  @Test()
  Future<void> startsEmptyAgain() async {
    expect(await books.count(), 0);
  }
}

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

Generated (shortened, from the data starter's tests):

```dart
import 'package:spring_boot_starter_test/generated.dart' as _sbt;
import 'package:spring_boot_starter_data/testing.dart' as _data;

import 'app/data_test_app.spring.dart' as _app0;

void runSpringTests() {
  _sbt.group('CommitTest', () {
    final $instance = CommitTest();
    // The slice: the properties and the initializer that keep only the data beans.
    final $slice = _data.DataTestSetup(_app0.springApplication);
    final $app = _sbt.springBootTest(
      _app0.springApplication,
      properties: $slice.properties,
      initializers: [$slice.initializer],
    );
    _sbt.setUp(() {
      $instance.books = $app.getBean();
    });
    _sbt.test(
      'commits a book',
      () => _data.runInTestTransaction(
        $app.context,
        () => $instance.commitsABook(),
        rollback: false,
      ),
    );
    _sbt.test(
      'starts empty again',
      () => _data.runInTestTransaction(
        $app.context,
        () => $instance.startsEmptyAgain(),
      ),
    );
  });
}
```

How it differs from `@SpringBootTest`:

- **The slice.** `DataTestSetup(application, include:, replaceDatabase:)` receives the `include:` and `replaceDatabase:` arguments of `@DataTest` when they are written. Its properties come first in `properties:` (the class's own are merged after them), and its initializer first in `initializers:`.
- **The transaction.** Each test is wrapped in `runInTestTransaction`. The `@BeforeEach` and `@AfterEach` methods run inside the same transaction, so they are passed as `before:` and `after:` instead of being registered with `setUp` and `tearDown`. With `@Nested` groups, the `@BeforeEach` methods run from the outside in, the `@AfterEach` methods in the opposite order.
- **Commit or roll back.** The innermost `@Commit()` or `@Rollback(...)` decides: the method's first, then the `@Nested` field's, the nested class's, and the test class's. `@Commit()` and `@Rollback(false)` give `rollback: false`. Without any, the test rolls back.
- **The transaction manager.** The innermost `@Transactional(transactionManager: '...')` that names one (method, then nested group, then class), else `@DataTest(transactionManager: '...')`, is passed as `transactionManager:`.

`args:`, `properties:` and `resourceDirectories:` of `@DataTest` are passed as for `@SpringBootTest`.

## Containers

Static fields annotated `@Container()` hold containers (from `package:spring_boot_starter_test/containers.dart`) that start once for the class, before its context, and are removed after it. `@ServiceConnection()` on such a field also writes the container's connection properties into the application, for example `spring.datasource.*` for a database.

```dart
@DataTest(
  application: 'test/data_test/postgres_app/postgres_data_app.dart',
  replaceDatabase: false,
)
@Testcontainers()
class ContainerPostgresTest {
  @Container()
  @ServiceConnection()
  static final postgres = PostgresContainer('postgres:17');

  @Autowired()
  late BookRepository books;

  @Test()
  Future<void> savesABook() async {
    await books.save(Book(title: 'Dune', year: 1965));
    expect(await books.count(), 1);
  }
}
```

Generated (shortened):

```dart
_sbt.group('ContainerPostgresTest', () {
  // First, so @BeforeAll methods and the context find the containers running.
  final $containers = _sbt.TestContainers(
    {'ContainerPostgresTest.postgres': ContainerPostgresTest.postgres},
    serviceConnections: {'ContainerPostgresTest.postgres'},
  );
  _sbt.setUpAll($containers.start);
  _sbt.tearDownAll($containers.stop);
  final $instance = ContainerPostgresTest();
  final $slice = _data.DataTestSetup(
    _app0.springApplication,
    replaceDatabase: false,
  );
  final $app = _sbt.springBootTest(
    _app0.springApplication,
    properties: $slice.properties,
    // The containers' connections first, so a @DynamicPropertySource
    // method can still change one.
    dynamicProperties: (registry) {
      $containers.registerConnections(registry);
    },
    initializers: [$slice.initializer],
  );
  // ...
}, skip: _sbt.TestContainers.skipReason());
```

- The containers are started in `setUpAll` before everything else of the group, and stopped by a `tearDownAll` registered first, so it runs last, after the context is closed.
- The group gets `skip: TestContainers.skipReason()`: without Docker the class is skipped with a reason. `@Testcontainers(disabledWithoutDocker: false)` is passed as `skipWithoutDocker: false`, so the class fails instead. A class that is `@Disabled` keeps its own `skip:`.
- With `@ServiceConnection` fields, `dynamicProperties:` first registers the connections, then calls each `@DynamicPropertySource` method.

A `@Container` field must be static, public, in the test class (not a `@Nested` one), and have a value (or be `late`). `@ServiceConnection` without `@Container` on the same field fails the build.

## Build errors

The builder reports an error at the member that causes it, as `path:line:column: message`. Among them:

| Problem | Message (shortened) |
|---|---|
| no application | `No application in this package: @SpringBootTest needs a @SpringBootApplication entry point in bin/ or lib/.` |
| several applications | `Several applications in this package (bin/a.dart, bin/b.dart): name one, @SpringBootTest(application: 'bin/a.dart').` |
| `application:` names no entry point | `'bin/x.dart' is not an entry point with @SpringBootApplication of this package (...)` |
| both annotations on one class | `@DataTest and @SpringBootTest on one class: ... keep one, or write a second class.` |
| the class cannot be created | `'ShopTest' is private`, `is abstract`, `has no unnamed constructor`, or `needs a constructor without required parameters` |
| an injected field is not `late` or is `final` / static | `@Autowired field 'checkout' must be late and not final or static: @Autowired() late Checkout checkout;` |
| an injected field without a type | `@Autowired field 'checkout' needs its type written.` |
| a test method with parameters | `@Test method pays has parameters: test methods take none (widget tests with a WidgetTester come with spring_boot_starter_flutter_test).` |
| `@BeforeAll` not static | `@BeforeAll method start must be static: it runs before the class is created.` |
| `@Commit` or `@Rollback` outside a `@DataTest` | `@Commit needs a @DataTest class: only its tests run in a transaction.` |
| a private name in an annotation argument | `'_port' is private to the test file; the generated test cannot reach it: make it public.` |

The generated code is in another library, so it cannot reach private names: the test class, its annotated members, and every name used in an annotation argument must be public.

## While you type

While the test file has syntax errors (for example under `dart run build_runner watch`), the builder logs a warning and writes the existing generated file again unchanged. The test's import of it keeps working until the file parses again. Without an existing generated file, nothing is written.

## In Spring (Java)

```java
@SpringBootTest(properties = "neon.shop.delivery-time=3d")
@ActiveProfiles({"dev", "test"})
class ShopTest {
  @Autowired Catalog catalog;

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

Differences that matter:

- JUnit and Spring's test extension find the tests and fill the fields at run time with reflection. Here the builder writes that code. Run `build_runner` after you change a test class.
- The test file needs `void main() => runSpringTests();`.
- Spring caches contexts across test classes with the same configuration. Here each class starts its own context and closes it after its tests.
- Annotations are recognized by name in the test file, and a superclass must be declared in the same file.

## See also

- [The builders](builders.md): `spring_test` among the other builders, and how to turn one off.
- [The application: @SpringBootApplication](spring-boot-application.md): the `springApplication` a test starts.
- [Data: entities, repositories, queries](data.md)
- [Testing a web application](../spring-boot-starter-web/testing.md): `MockMvc` and a real server.
