Liquibase SDK Test Environments
The wrapper around Test Containers allows us to provide a simple configuration system, plus support testing databases that do not have Docker containers such as in-memory and cloud databases.
The SDK Test Environment System is currently only available in the main Liquibase repository, not for extensions.
The default test environments and settings are configured in liquibase-extension-testing/src/main/resources/liquibase.sdk.yaml.
That file configures the various databases including docker image settings and users to create. Generally, each test system will be created with:
lbuseruser with a password
- A catalog/database called
- An alternate catalog/database named
- An alternate schema named
Besides the environment configuration, the default setup also sets the
liquibase.sdk.testSystem.test configuration to
h2,hsqldb,sqlite. This setting controls which databases are tested against and which are skipped. Note that by default only in-memory databases will be used.
The SDK Test Environment setup looks up configuration keys in:
- System properties
- Environment Variables
If a configuration is set in multiple locations, it will use the value it finds first given the above order.
For example, by default the MysqlIntegrationTest will skip all tests because
liquibase.sdk.testSystem.test does not include "mysql". To customize that configuration, you could:
- Add a
-Dliquibase.sdk.testSystem.test=mysqlargument to your java call. This works well when running specific tests from your IDE's "test run" configuration which you don't always want to enable
- Add a
LIQUBASE_SDK_TEST_SYSTEM_TEST=mysqlenvironment variable. This works like a system property but may be easier to set depending on how you are working
- Create a liquibase.sdk.local.yaml file in
liquibase.sdk.yaml. This file is not checked into git, and works well for more permanent/consistent changes you would like to make
All settings for the test environments use the
liquibase.sdk.testSystem prefix. The overall structure can be seen in the liquibase-extension-testing/src/main/resources/liquibase.sdk.yaml file.
For each test environment, there is a top-level "key" for it. For example,
liquibase.sdk.testSystem.mysql. There is also a
liquibase.sdk.testSystem.default section which contains default/standard settings.
When code is looking for a particular setting such as
liquibase.sdk.testSystem.mysql.username it will first look for
liquibase.sdk.testSystem.mysql.username in all the locations it could be set
and if none has that setting, it will look for
liquibase.sdk.testSystem.default.username in those same locations.
This allows common settings such as "username" to be shared across environments while keeping environment-specific settings like "imageName" separate.
Example liquibase.sdk.local.yaml File
Anything you set in
liquibase.sdk.local.yaml file will override what is in the default
liquibase.sdk.yaml file, but there is no need to duplicate settings from the
Copy/pasting settings from the default only risks unexpected drift between what you are testing against and what others use.
This changes what databases are tested against to be only h2, mysql, and postgresql without changing what is tested against. It also changes the mysql version to test to "8.0" regardless of what the default is.
Tests can auto-start databases on demand when they are run.
A call to
will either return the database connection after starting the database OR throw a
AssumptionViolatedException exception which causes the test to be skipped.
liquibase.sdk.testSystem.test setting controls which environments to auto-start and which to skip.
AbstractIntegrationTest base class contains this logic for the classic integration tests.
To start and stop test systems manually, you can use the
liquibase sdk system up and
liquibase sdk system down commands.
NOTE: these commands are part of the
liquibase-extension-testing module and are not currently shipped as published artifacts.
Therefore, to use them you must either:
mvn packagefrom the root of the Liquibase repository and copy
liquibase-extension-testing/target/liquibase-extension-testing-0-SNAPSHOT.jarto your LIQUIBASE_HOME/lib directory
- From your IDE, run
The "up" and "down" commands let you start and top the test environments as needed.
Any tests you run will use these manually started environments rather than creating their own.