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

// 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):

// 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:

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.
  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:

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:

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:

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). 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.

// 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:

@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:

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.

// 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):

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:

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.

@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):

_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());

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)

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

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

Differences that matter:

See also