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:

  1. dynamicProperties (@DynamicPropertySource), and the connection properties of @ServiceConnection containers;
  2. properties (@SpringBootTest(properties:) and @TestPropertySource(properties:), merged; on the same key @TestPropertySource wins);
  3. propertyFiles (@TestPropertySource(locations:)); a later file wins;
  4. the command-line args;
  5. systemEnvironment (@TestEnvironment), which stands in for the OS environment;
  6. the config files: test/resources/ first, then lib/resources/, with the profiles of profiles.

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

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.

See also