Test properties
A test often needs other values than the application ships with: a smaller limit, a fake server's URL, a test database. springBootTest and the test annotations add property sources on top of the application's configuration, and put test/resources/ first on the classpath.
Why
Tests should not edit the application's config files, and they should not depend on the machine they run on. Test-only files live in test/resources/, never embedded into the application; inline properties change one key for one test file; dynamic properties carry values that exist only once the tests run; and the OS environment is hidden unless the test sets it.
Example
lib/resources/application.yml # the application's config
test/resources/application-test.yml # test-only settings, with the test profile
test/resources/payments-test.properties # a property file for one test
test/resources/fixtures/books.json # resources:fixtures/books.json in tests
late HttpServer catalog;
// Declared before springBootTest, so the server is up when the context starts.
setUpAll(() async => catalog = await HttpServer.bind('localhost', 0));
final app = springBootTest(
springApplication,
profiles: ['test'], // + application-test.yml
propertyFiles: ['resources:payments-test.properties'], // found in test/resources/ first
properties: {'shop.max-basket-size': 3},
systemEnvironment: {'SHOP_CURRENCY': 'EUR'},
dynamicProperties: (registry) =>
registry.add('catalog.url', () => 'http://localhost:${catalog.port}'),
);
Which source wins
From the highest:
dynamicProperties(@DynamicPropertySource), and the connection properties of@ServiceConnectioncontainers;properties(@SpringBootTest(properties:)and@TestPropertySource(properties:), merged; on the same key@TestPropertySourcewins);propertyFiles(@TestPropertySource(locations:)); a later file wins;- the command-line
args; systemEnvironment(@TestEnvironment), which stands in for the OS environment;- the config files:
test/resources/first, thenlib/resources/, with the profiles ofprofiles.
test/resources/
While springBootTest runs, test/resources/ comes first on the classpath, before lib/resources/. It is never embedded into the application: the generator embeds only lib/resources/.
- Prefer a test profile.
application-test.ymlwithprofiles: ['test']adds its keys on top ofapplication.yml. - A file with the same path replaces the packaged one entirely, as in Spring: a
test/resources/application.ymlhides the real one. - Relative directories are resolved against the package of the test file (the nearest
pubspec.yaml), so it does not matter whether the tests run from the package, a workspace root or an IDE. - Other directories:
resourceDirectories: ['test/fixtures', 'test/resources']; the first one listed comes first. Browser tests have no file system, so there the directories are not found.
Profiles
profiles: ['test'] (@ActiveProfiles(['test'])) sets spring.profiles.active, replacing the profiles of the config files, as in Spring. List the application's own profiles too when the tests need them: profiles: ['dev', 'test'].
Property files
propertyFiles (@TestPropertySource(locations:)) are resource locations of .properties files. A plain path is a classpath location, so test/resources/ is searched first. A later file wins over an earlier one. A missing file fails the start with a StateError.
Dynamic properties
properties: is fixed when springBootTest is called. Values that exist only once the tests run (the port of a fake server, a temporary directory, a container's address) go through dynamicProperties, which registers a function per property:
final app = springBootTest(
springApplication,
dynamicProperties: (registry) => registry
..add('catalog.url', () => 'http://localhost:${server.port}')
..add('upload.dir', () => tempDir.path),
);
The callback runs each time the context starts (again after markDirty), and each function each time the application reads the property. These values win over every other source. Adding the same name twice keeps the second function. In a test class, a static @DynamicPropertySource() method does the same.
The environment
The OS environment is not visible: systemEnvironment is {} by default, so tests do not depend on the machine. Set the variables a test needs:
final app = springBootTest(
springApplication,
systemEnvironment: {'SHOP_MAX_BASKET_SIZE': '25', 'SPRING_PROFILES_ACTIVE': 'dev'},
);
Properties the tests read
| Key | Values | Default | Meaning |
|---|---|---|---|
spring.test.web-environment |
mock, random-port, defined-port, none |
not set: a real application starts its server; springBootTest and ApplicationContextRunner set mock unless told otherwise |
Which test environments start the web starter's server. random-port sets server.port to 0 and publishes the port in local.server.port |
local.server.port |
int |
set by the web starter | The port the real server listens on; app.localServerPort reads it |
Environment variables of the test tools
| Variable | Meaning |
|---|---|
CONTAINERS_REQUIRED=true |
A test class with containers fails without Docker instead of being skipped (set it in CI) |
DOCKER_HOST |
The Docker daemon (unix:///path, tcp://host:2375) |
TESTCONTAINERS_RYUK_DISABLED=true |
No reaper container |
TESTCONTAINERS_RYUK_CONTAINER_IMAGE |
Another reaper image than testcontainers/ryuk:0.14.0 |
CI |
When set, withReuse(true) is ignored |
These are read from the process running the tests, not from systemEnvironment. See Containers.
In Spring (Java)
The same sources as @SpringBootTest(properties), @TestPropertySource, @DynamicPropertySource and @ActiveProfiles. Differences: the OS environment is empty unless set; systemEnvironment (@TestEnvironment) has no Spring counterpart; test/resources/ is put first on the classpath by springBootTest itself.