
# 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

```text
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
```

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

- **Prefer a test profile.** `application-test.yml` with `profiles: ['test']` adds its keys on top of `application.yml`.
- **A file with the same path replaces the packaged one** entirely, as in Spring: a `test/resources/application.yml` hides 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:

```dart
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:

```dart
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](containers.md).

## 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

- [springBootTest](spring-boot-test.md)
- [Test classes](test-classes.md)
- [External configuration](../spring-boot-dart/configuration/index.md)
- [Containers](containers.md)
