testcontainers-extensions

Testcontainers Extensions Oracle

Minimum required Java version Maven Central GitHub Action Coverage Maintainability Rating Lines of Code

Testcontainers Oracle Extension with advanced testing capabilities.

Features:

Dependency :rocket:

Gradle

testImplementation "io.goodforgod:testcontainers-extensions-oracle:0.12.1"

Maven

<dependency>
    <groupId>io.goodforgod</groupId>
    <artifactId>testcontainers-extensions-oracle</artifactId>
    <version>0.12.1</version>
    <scope>test</scope>
</dependency>

JDBC Driver

Oracle JDBC Driver must be on classpath, if it is somehow not on your classpath already, don’t forget to add:

Gradle

testRuntimeOnly "com.oracle.database.jdbc:ojdbc8:21.5.0.0"

Maven

<dependency>
    <groupId>com.oracle.database.jdbc</groupId>
    <artifactId>ojdbc8</artifactId>
    <version>21.5.0.0</version>
    <scope>test</scope>
</dependency>

Oracle behavior differently based on Database version / JDBC driver version / JDK version / migration engines. Extension tested against image gvenzl/oracle-xe:18.4.0-faststart and driver com.oracle.database.jdbc:ojdbc8:21.5.0.0.

Content

Usage

Test with container start in PER_RUN mode and migration per method will look like:

@TestcontainersOracle(mode = ContainerMode.PER_RUN,
        migration = @Migration(
                engine = Migration.Engines.FLYWAY,
                apply = Migration.Mode.PER_METHOD,
                drop = Migration.Mode.PER_METHOD))
class ExampleTests {

  @ConnectionOracle
  private JdbcConnection connection;

  @Test
  void test() {
    connection.execute("INSERT INTO users VALUES(1)");
    var usersFound = connection.queryMany("SELECT * FROM users", r -> r.getInt(1));
    assertEquals(1, usersFound.size());
  }
}

Connection

JdbcConnection is an abstraction with asserting data in database container and easily manipulate container connection settings. You can inject connection via @ConnectionOracle as field or method argument or manually create it from container or manual settings.

class ExampleTests {

    private static final OracleContainer container = new OracleContainer();
    
    @Test
    void test() {
      container.start();
      JdbcConnection connection = JdbcConnection.forContainer(container);
      connection.execute("INSERT INTO users VALUES(1);");
    }
}

Connection Migration

Migrations allow easily migrate database between test executions and drop after tests. You can migrate container via @TestcontainersOracle#migration annotation parameter or manually using JdbcConnection.

@TestcontainersOracle
class ExampleTests {

    @Test
    void test(@ConnectionOracle JdbcConnection connection) {
      connection.migrationEngine(Migration.Engines.FLYWAY).apply("db/migration");
      connection.execute("INSERT INTO users VALUES(1);");
      connection.migrationEngine(Migration.Engines.FLYWAY).drop("db/migration");
    }
}

Available migration engines:

Annotation

@TestcontainersOracle - allow automatically start container with specified image in different modes without the need to configure it.

Available containers modes:

Simple example on how to start container per class, no need to configure container:

@TestcontainersOracle(mode = ContainerMode.PER_CLASS)
class ExampleTests {

    @Test
    void test(@ConnectionOracle JdbcConnection connection) {
        assertNotNull(connection);
    }
}

That’s all you need.

It is possible to customize image with annotation image parameter.

Image also can be provided from environment variable:

@TestcontainersOracle(image = "${MY_IMAGE_ENV|gvenzl/oracle-xe:18.4.0-faststart}")
class ExampleTests {

    @Test
    void test() {
        // test
    }
}

Image syntax:

Manual Container

When you need to manually configure container with specific options, you can provide such container as instance that will be used by @TestcontainersOracle, this can be done using @ContainerOracle annotation for container.

@TestcontainersOracle(mode = ContainerMode.PER_CLASS)
class ExampleTests {

    @ContainerOracle
    private static final OracleContainer container = new OracleContainer(dockerImage)
            .withPassword("test")
            .withDatabaseName("oracle");
    
    @Test
    void test(@ConnectionOracle JdbcConnection connection) {
        assertEquals("oracle", connection.params().database());
        assertEquals("test", connection.params().password());
    }
}

Network

In case you want to enable Network.SHARED for containers you can do this using network & shared parameter in annotation:

@TestcontainersOracle(network = @Network(shared = true))
class ExampleTests {

    @Test
    void test() {
        // test
    }
}

Default alias will be created by default, even if nothing was specified (depends on implementation).

You can provide also custom alias for container. Alias can be extracted from environment variable also or default value can be provided if environment is missing.

In case specified environment variable is missing default alias will be created:

@TestcontainersOracle(network = @Network(alias = "${MY_ALIAS_ENV|my_default_alias}"))
class ExampleTests {

    @Test
    void test() {
        // test
    }
}

Image syntax:

Annotation Connection

JdbcConnection - can be injected to field or method parameter and used to communicate with running container via @ConnectionOracle annotation. JdbcConnection provides connection parameters, useful asserts, checks, etc. for easier testing.

@TestcontainersOracle(mode = ContainerMode.PER_CLASS, image = "gvenzl/oracle-xe:18.4.0-faststart")
class ExampleTests {

    @ConnectionOracle
    private JdbcConnection connection;

    @Test
    void test() {
        connection.execute("CREATE TABLE users (id INT NOT NULL PRIMARY KEY)");
        connection.execute("INSERT INTO users VALUES(1)");
        connection.assertInserted("INSERT INTO users VALUES(2)");
        var usersFound = connection.queryMany("SELECT * FROM users", r -> r.getInt(1));
        assertEquals(2, usersFound.size());
        connection.assertQueriesEquals(2, "SELECT * FROM users");
    }
}

External Connection

In case you want to use some external Oracle instance that is running in CI or other place for tests (due to docker limitations or other), you can use special environment variables and extension will use them to propagate connection and no Oracle containers will be running in such case.

Special environment variables:

Use can use either EXTERNAL_TEST_ORACLE_JDBC_URL to specify connection with username & password combination or use combination of EXTERNAL_TEST_ORACLE_HOST & EXTERNAL_TEST_ORACLE_PORT & EXTERNAL_TEST_ORACLE_DATABASE.

EXTERNAL_TEST_ORACLE_JDBC_URL env have higher priority over host & port & database.

Annotation Migration

@Migrations allow easily migrate database between test executions and drop after tests.

Annotation parameters:

Available migration engines:

Given engine is Flyway and migration file named V1__flyway.sql is in resource directory on default path db/migration:

CREATE TABLE IF NOT EXISTS users
(
    id INT NOT NULL PRIMARY KEY
);

Test with container and migration per method will look like:

@TestcontainersOracle(mode = ContainerMode.PER_CLASS,
        migration = @Migration(
                engine = Migration.Engines.FLYWAY,
                apply = Migration.Mode.PER_METHOD,
                drop = Migration.Mode.PER_METHOD))
class ExampleTests {

    @Test
    void test(@ConnectionOracle JdbcConnection connection) {
        connection.execute("INSERT INTO users VALUES(1)");
        var usersFound = connection.queryMany("SELECT * FROM users", r -> r.getInt(1));
        assertEquals(1, usersFound.size());
    }
}

License

This project licensed under the Apache License 2.0 - see the LICENSE file for details.

This site is open source. Improve this page.