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. Support for jacobalberty/firebird is deprecated. Although we currently we have no plans to remove support, we strongly recommend to switch to the firebirdsql/firebird image.

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.

• Docker
• A supported JVM testing framework
• Java 8 or higher
  • NOTE: Our tests require Java 17 or higher

See General Container runtime requirements for details.

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

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

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

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

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:

package org.firebirdsql.testcontainers.examples;

import org.firebirdsql.testcontainers.FirebirdContainer;
import org.junit.jupiter.api.Test;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

import java.sql.*;

import static org.junit.jupiter.api.Assertions.*;

/**
 * Simple test demonstrating use of {@code @Testcontainers} and {@code @Container}.
 */
@Testcontainers
public class ExampleContainerTest {

  @Container
  public final FirebirdContainer container = new FirebirdContainer("firebirdsql/firebird:5.0.4")
          .withUsername("testuser")
          .withPassword("testpassword");

  @Test
  public void canConnectToContainer() throws Exception {
    try (Connection connection = DriverManager
            .getConnection(container.getJdbcUrl(), container.getUsername(), container.getPassword());
         Statement stmt = connection.createStatement();
         ResultSet rs = stmt.executeQuery("select CURRENT_USER from RDB$DATABASE")) {
      assertTrue(rs.next(), "has row");
      assertEquals("TESTUSER", rs.getString(1), "user name");
    }
  }
}

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:

import org.junit.jupiter.api.Test;

import java.sql.*;

import static org.junit.jupiter.api.Assertions.*;

/**
 * Simple test demonstrating use of url to instantiate container.
 */
class ExampleUrlTest {

  @Test
  void canConnectUsingUrl() throws Exception {
    try (Connection connection = DriverManager
            .getConnection("jdbc:tc:firebird://hostname/databasename?user=someuser&password=somepwd");
         Statement stmt = connection.createStatement();
         ResultSet rs = 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.

See LICENSE