firebird-testcontainers-java

Firebird-testcontainers-java is a module for Testcontainers to provide lightweight, throwaway instances of Firebird for JUnit tests.

The default Docker image used is firebirdsql/firebird, and also supports jacobalberty/firebird.

If you want to use Firebird 2.5, use the 2.5.x-sc (SuperClassic) variant of the jacobalberty/firebird image, or 2.5.9-ss as earlier versions of the 2.5.x-ss (SuperServer) variant seem to be broken. However, recently, it seems that the 2.5.x-sc variants also no longer work reliably.

Prerequisites

• Docker
• A supported JVM testing framework

See Testcontainers prerequisites for details.

Dependency

In addition to the firebird-testcontainers-java dependency, you will also need to explicitly depend on Jaybird.

Gradle

testImplementation "org.firebirdsql:firebird-testcontainers-java:2.0.0"

Maven

<dependency>
<groupId>org.firebirdsql</groupId>
<artifactId>firebird-testcontainers-java</artifactId>
<version>2.0.0</version>
<scope>test</scope>
</dependency>

Usage

For extensive documentation, consult https://www.testcontainers.org/modules/databases/

JUnit support

Starting with firebird-testcontainers-java 2.0.0, use of JUnit 4 is no longer supported directly. If you still need JUnit 4 support, use firebird-testcontainers-java 1.6.1, use URL based, or derive your own rule implementation to start and stop the container.

For JUnit 5 support, add org.testcontainers:testcontainers-junit-jupiter as a test dependency. Annotate the test class with @Testcontainers. Define a FirebirdContainer static (shared by all tests), or instance (per test) field. Annotate this field with @Container.

The container defines several withXXX methods for configuration.

Important standard options are:

• withUsername(String) - Sets the username to create (defaults to test); sets docker environment variable FIREBIRD_USER.
  For jacobalberty/firebird, if the value is sysdba, FIREBIRD_USER is not set.
• withPassword(String) - Sets the password of the user (defaults to test); sets the docker environment variable FIREBIRD_PASSWORD.
  For jacobalberty/firebird, if the username is sysdba, ISC_PASSWORD is set instead of FIREBIRD_PASSWORD.
  For firebirdsql/firebird, if the username is sysdba, it also sets FIREBIRD_ROOT_PASSWORD.
• withDatabaseName(String) - Sets the database name (defaults to test); sets docker environment variable FIREBIRD_DATABASE

Firebird specific options are:

• withEnableLegacyClientAuth() - (Firebird 3+) Enables LegacyAuth and uses it as the default for creating users, also relaxes WireCrypt to Enabled; sets docker environment variable EnableLegacyClientAuth (jacobalberty/firebird) or FIREBIRD_USE_LEGACY_AUTH (firebirdsql/firebird) to true; passes connection property authPlugins with value Srp256,Srp,Legacy_Auth if this property is not explicitly set through withUrlParam.
• withEnableWireCrypt - (Firebird 3+) Relaxes WireCrypt from Required to Enabled; sets docker environment variable EnableWireCrypt (jacobalberty/firebird) to true, or FIREBIRD_CONF_WireCrypt (firebirdsql/firebird) to Enabled.
• withTimeZone(String) - Sets the time zone (defaults to JVM default time zone);
• sets docker environment variable TZ to the specified value
• withSysdbaPassword(String) - Sets the SYSDBA password, but if withUsername(String) is set to sysdba (case-insensitive), this property is ignored and the value of withPassword is used instead; sets docker environment variable ISC_PASSWORD (jacobalberty/firebird) or FIREBIRD_ROOT_PASSWORD (firebirdsql/firebird) to the specified value.

Example of use:

packageorg.firebirdsql.testcontainers.examples;
importorg.firebirdsql.testcontainers.FirebirdContainer;
importorg.junit.jupiter.api.Test;
importorg.testcontainers.junit.jupiter.Container;
importorg.testcontainers.junit.jupiter.Testcontainers;
importjava.sql.*;
importstaticorg.junit.jupiter.api.Assertions.*;
/** * Simple test demonstrating use of {@code @Testcontainers} and {@code @Container}. */@TestcontainerspublicclassExampleContainerTest {
@ContainerpublicfinalFirebirdContainercontainer = newFirebirdContainer("firebirdsql/firebird:5.0.3")
.withUsername("testuser")
.withPassword("testpassword");
@TestpublicvoidcanConnectToContainer() throwsException {
try (Connectionconnection = DriverManager
.getConnection(container.getJdbcUrl(), container.getUsername(), container.getPassword());
Statementstmt = connection.createStatement();
ResultSetrs = stmt.executeQuery("select CURRENT_USER from RDB$DATABASE")) {
assertTrue(rs.next(), "has row");
assertEquals("TESTUSER", rs.getString(1), "user name");
}
}
}

Testcontainers URL

The testcontainers URL defines the container and connects to it. As long as there are active connections, the container will stay up.

For Firebird the URL format is:

• jdbc:tc:firebird[:<image-tag>]://hostname/<databasename>[?<property>=<value>[&<property>=<value>...]]
• jdbc:tc:firebirdsql[:<image-tag>]://hostname/<databasename>[?<property>=<value>[&<property>=<value>...]]

Where:

• <image-tag> (optional, but recommended) is the tag of the docker image to use, otherwise the default is used (which might change between versions)
• <databasename> (optional) is the name of the database (defaults to test)
• <property> is a connection property (Jaybird properties and testcontainers properties are possible)
  Of special note are the properties:
  • user (optional) specifies the username to create and connect (defaults to test)
  • password (optional) specifies the password for the user (defaults to test)
• <value> is the value of the property

These URLs use the firebirdsql/firebird images, except for tags starting with 2., v2, v3, v4 or v5, which will select the jacobalberty/firebird images for backwards compatibility.

Example of use:

importorg.junit.jupiter.api.Test;
importjava.sql.*;
importstaticorg.junit.jupiter.api.Assertions.*;
/** * Simple test demonstrating use of url to instantiate container. */classExampleUrlTest {
@TestvoidcanConnectUsingUrl() throwsException {
try (Connectionconnection = DriverManager
.getConnection("jdbc:tc:firebird://hostname/databasename?user=someuser&password=somepwd");
Statementstmt = connection.createStatement();
ResultSetrs = stmt.executeQuery("select CURRENT_USER from RDB$DATABASE")) {
assertTrue(rs.next(), "has row");
assertEquals("SOMEUSER", rs.getString(1), "user name");
}
}
}

For this type of use, it is not necessary to add org.testcontainers:testcontainers-junit-jupiter as a test dependency.

License

See LICENSE