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:
- One group per class. Each test class becomes a
groupnamed after the class. One instance of the class is created for the whole group, withShopTest(). - 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
@Autowiredand@Valuefields are assigned insetUp, 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 whereCatalogis 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:hasTheSampleBooksbecomeshas the sample books,readsURLServicebecomesreads url service.
How the builder works
- A cheap text check. A file that does not contain
SpringBootTestorDataTestis skipped at once. - 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). - The application is found. The builder looks at the
.dartfiles ofbin/andlib/(generated files excluded) for a top-level function annotated@SpringBootApplication. See Which application starts. - The imports are copied. The generated file repeats every import of the test file, with the same prefixes and
show/hidecombinators, and imports the test file itself. A relative import is re-pointed fromtest/spring_gen/. So every type and constant written in an annotation means the same thing in the generated file. - The code is written and formatted. One
groupper 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 withouttype: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
@TestBeanfield 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:
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:
- The slice.
DataTestSetup(application, include:, replaceDatabase:)receives theinclude:andreplaceDatabase:arguments of@DataTestwhen they are written. Its properties come first inproperties:(the class's own are merged after them), and its initializer first ininitializers:. - The transaction. Each test is wrapped in
runInTestTransaction. The@BeforeEachand@AfterEachmethods run inside the same transaction, so they are passed asbefore:andafter:instead of being registered withsetUpandtearDown. With@Nestedgroups, the@BeforeEachmethods run from the outside in, the@AfterEachmethods in the opposite order. - Commit or roll back. The innermost
@Commit()or@Rollback(...)decides: the method's first, then the@Nestedfield's, the nested class's, and the test class's.@Commit()and@Rollback(false)giverollback: 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 astransactionManager:.
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());
- The containers are started in
setUpAllbefore everything else of the group, and stopped by atearDownAllregistered 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 asskipWithoutDocker: false, so the class fails instead. A class that is@Disabledkeeps its ownskip:. - With
@ServiceConnectionfields,dynamicProperties:first registers the connections, then calls each@DynamicPropertySourcemethod.
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:
- 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_runnerafter 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:
spring_testamong the other builders, and how to turn one off. - The application: @SpringBootApplication: the
springApplicationa test starts. - Data: entities, repositories, queries
- Testing a web application:
MockMvcand a real server.