Docker test containers

Ebean provides docker test containers for Postgres, MySql, SqlServer, Oracle, Hana, Clickhouse, Redis and ElasticSearch.

ebean-test-docker automatically manages the docker containers and sets them up ready for running tests. As developers we just need to specify the platform (e.g. postgres) and Ebean will do the rest:

  • Start a docker container(s)
  • Wait for the container to be ready
  • Create the database and user setting any permissions as necessary
  • When ready allow the tests to run

We can see/review what is occurring by increasing the logging for io.ebean.docker to TRACE. When we do that we can see log messages like:

... Docker test container start and setup

15:15:02.537 INFO  io.ebean.docker.commands.Commands - Container ut_postgres running with port:6432 db:test_ex user:test_ex mode:Create shutdown:
15:15:02.538 DEBUG io.ebean.docker.commands.Commands - docker exec -i ut_postgres pg_isready -h localhost -p 5432
15:15:02.645 DEBUG io.ebean.docker.commands.Commands - docker exec -i ut_postgres psql -U postgres -c select datname from pg_database
15:15:02.753 DEBUG io.ebean.docker.commands.Commands - docker exec -i ut_postgres psql -U postgres -c select rolname from pg_roles where rolname = 'test_ex'
15:15:02.871 DEBUG io.ebean.docker.commands.Commands - docker exec -i ut_postgres psql -U postgres -c select 1 from pg_database where datname = 'test_ex'
15:15:02.960 DEBUG io.ebean.docker.commands.Commands - create database extensions hstore,pgcrypto
15:15:02.960 DEBUG io.ebean.docker.commands.Commands - docker exec -i ut_postgres psql -U postgres -d test_ex -c create extension if not exists hstore
15:15:03.058 DEBUG io.ebean.docker.commands.Commands - docker exec -i ut_postgres psql -U postgres -d test_ex -c create extension if not exists pgcrypto
15:15:03.143 DEBUG io.ebean.docker.commands.Commands - waitForConnectivity ut_postgres ...
15:15:03.143 DEBUG io.ebean.docker.commands.Commands - checkConnectivity on ut_postgres ...
15:15:03.190 DEBUG io.ebean.docker.commands.Commands - connectivity confirmed for ut_postgres
15:15:03.190 DEBUG io.ebean.docker.commands.Commands - Container ut_postgres ready with port 6432

...

15:15:03.239 [main] INFO  o.a.datasource.pool.ConnectionPool - DataSourcePool [db] autoCommit[false] transIsolation[READ_COMMITTED] min[2] max[200]
15:15:03.277 [main] INFO  io.ebean.internal.DefaultContainer - DatabasePlatform name:db platform:postgres


... DDL Execution

15:15:03.618 [main] INFO  io.ebean.DDL - Executing extra-dll - 0 statements
15:15:03.618 [main] INFO  io.ebean.DDL - Executing db-drop-all.sql - 26 statements
15:15:03.649 [main] DEBUG io.ebean.DDL - executing 1 of 26 alter table if exists address drop constraint if exists fk_address_country_code
15:15:03.651 [main] DEBUG io.ebean.DDL - executing 2 of 26 drop index if exists ix_address_country_code
...
15:15:03.701 [main] INFO  io.ebean.DDL - Executing db-create-all.sql - 28 statements
15:15:03.701 [main] DEBUG io.ebean.DDL - executing 1 of 28 create table address ( id                            bigserial not null, line1...
15:15:03.709 [main] DEBUG io.ebean.DDL - executing 2 of 28 create table contact ( id                            bigserial not null, first_n...
...
15:15:03.841 [main] INFO  io.ebean.DDL - Executing extra-dll - 1 statements
15:15:03.842 [main] DEBUG io.ebean.DDL - executing 1 of 1 create or replace view order_agg_vw as select d.order_id as id, d.order_id as or...

Container startup

To startup the docker containers we hook into the Ebean lifecycle. This means that it will "just work" whether the tests are run from the IDE, maven, gradle or any build tool. In prior iterations the startup of docker containers was hooked specifically into the maven lifecycle but this proved to be less than ideal.

In general this is providing a similar experience to the one we have when using H2 database. That is, we bring up the database (if needed), setup the database, user, roles etc (if needed) get it ready for testing by running DDL ... and then run all tests.

Container shutdown

On developer machines we generally keep the docker container running. We can do this by having a marker file ~/.ebean/ignore-docker-shutdown.

On CI servers we want the docker containers to be stopped and removed at completion of tests. To do this we set shutdown to either remove (to stop and remove the container) or stop (to just stop the container).

ebean:
  test:
    shutdown: remove  # stop | remove
    platform: postgres # h2, postgres, mysql, oracle, sqlserver
    ddlMode: dropCreate # none | dropCreate | create | migration | createOnly | migrationDropCreate
    dbName: my_app

Not using Docker

If we don't want to start and run a Docker container but instead test against some other existing database we can do that via setting useDocker: false.

The below configuration runs against an existing Postgres database. Typically when not using docker we need to set the username, password and url to appropriate values.

When we are using useDocker: false the database and user are expected to already exist.

ebean:
  test:
    useDocker: false  ## DO NOT USE DOCKER
    platform: postgres # h2, postgres, mysql, oracle, sqlserver
    ddlMode: dropCreate # none | dropCreate | create | migration | createOnly | migrationDropCreate
    dbName: test
    postgres:
      username: test
      password: test
      url: jdbc:postgresql://localhost:5432/test

Edit Page