JUnit 5 Test Framework integration

pg-embedded supports the JUnit 5 framework through the EmbeddedPgExtension class.

The following snipped creates a new extension programmatically:

@RegisterExtension
public static EmbeddedPgExtension multiDatabase = MultiDatabaseBuilder.instanceWithDefaults().build();

EmbeddedPgExtension supports registration as a static field or an instance field. If registered as a static field, the EmbeddedPostgres instance supporting the extension is started once per test class, otherwise a new instance is started and stopped for each test method.

Creating and customizing EmbeddedPgExtension

Programmatically created instances are the preferred way to use the EmbeddedPgExtension. They can be customized extensively using the builder classes:

MultiDatabaseBuilder creates an extension in multi database mode. Any invocation of EmbeddedPgExtension.createDatabaseInfo() or EmbeddedPgExtension.createDataSource() creates a new database.
SingleDatabaseBuilder creates an extension in single database mode. Any invocation of EmbeddedPgExtension.createDatabaseInfo() or EmbeddedPgExtension.createDataSource() accesses the default database.

All builders have the same set static creation methods for simple, fluent configuration in test classes:

instance() returns a vanilla, not customized Builder.
instanceWithDefaults() returns a Builder with Builder.withInstancePreparer(EmbeddedPostgres.Builder::withDefaults) as an instance preparer.
preparedInstance() returns a Builder that registers the provided EmbeddedPostgresPreparer as a database preparer
preparedInstanceWithDefaults() returns a Builder that registers the provided EmbeddedPostgresPreparer as a database preparer and Builder.withInstancePreparer(EmbeddedPostgres.Builder::withDefaults) as an instance preparer.

The methods to customize the DatabaseManager are also available for EmbeddedPgExtension customization.

Declarative use

Tests can also use declarative registration of the EmbeddedPgExtension class.

@ExtendWith(EmbeddedPgExtension.class)
public class DeclarativeTest {

    @Test
    public void testCode(DataSource dataSource) {
      ...
    }

Using the @ExtendWith annotation on the class declaration creates a per-class extension, registration on the method-level creates a per-method extension.

Declarative registration is equivalent to registering MultiDatabaseBuilder.instanceWithDefaults() programmatically.

Parameter resolution

When using declarative registration (and unambiguous programmatic registration), test methods can declare parameters which will be resolved at runtime.

The EmbeddedPgExtension supports the following parameter types:

EmbeddedPostgres instance used by the extension
DatabaseInfo, the value is equivalent to calling EmbeddedPgExtension.createDatabaseInfo()
DataSource, the value is equivalent to calling EmbeddedPgExtension.createDataSource().

Conditional test execution based on PostgreSQL version

Some tests may be database version specific and should be executed only for certain PostgreSQL versions. The RequirePostgresVersion annotation can be used for this:

@RequirePostgresVersion(atLeast = "10")
public class TestsRequirePostgres10 {
...
}

Or on method level:

public class TestPostgresQuirks() {

    @RequirePostgresVersion(atLeast = "10.1" lessThan="10.2")
    testPostgres10_1Bug() {
    ...
    }

    @RequirePostgresVersion(atLeast = "14")
    testSpecialPostgres14() {
    ...
    }

    @RequirePostgresVersion(lessThan = "10")
    testSpecialPostgres9LegacyCode() {
    ...
    }
}

The annotation supports inclusive version matching for the lower boundary (minimum version required) and exclusive matching for the upper boundary (version must be less than).