Skip to content
Permalink
master
Switch branches/tags
Go to file
 
 
Cannot retrieve contributors at this time
<html>
<head>
<title>Testing | Ebean</title>
<meta name="layout" content="_layout2/base-docs.html"/>
<meta name="bread1" content="Testing" href="/docs/testing"/>
<#assign n0_docs="active">
<#assign n1_testing="active">
</head>
<body>
<h2 id="third-age">Third age of testing</h2>
<p>
Rob Opinion: I believe with respect to testing and persistence we are now in
the "3rd age" of testing.
</p>
<h3>(I) First age - all persistence mocked/stubbed</h3>
<p>
In the first age testing against real databases was generally too slow,
expensive and difficult. Tests mocked/stubbed out all persistence
(often via Repository API's). Tests only ran against real databases
on an "integration server".
</p>
<h3>(II) Second age - in memory DB's</h3>
<p>
In the second age of testing in memory databases like H2 became available.
This allowed developers to use these in memory databases rather than mocking
out all persistence API's.
</p>
<p>
This resulted in far less mocking/stubbing used in tests.
</p>
<p>
The limitations of testing using in memory DB's like H2 for testing is around
the functional difference compared to the "real" target database like Postgres
or Oracle etc. Differences in types (e.g. UUID, Array, Json, Hstore, Range types)
and features (sql functions, advanced locking, table partitioning etc).
</p>
<h3>(III) Third age - testing using docker DB's</h3>
<p>
The limitations with testing against H2 can now be addressed in this
"third age" of persistence testing. Docker has made it easier to automate
the install/setup of databases on developer machines. Developer machines
are powerful enough to run tests fast enough against the "real" target database
(where docker versions of databases are functionally the same as the real thing).
</p>
<ul>
<li>Tests can cover database specific functionality and types (no excuses on test coverage)</li>
<li>The ease of using docker test containers needs to match the ease of using H2</li>
<li>We want tests to run against new/clean ephemeral databases</li>
<li>We need tests to run fast - match in memory database experience</li>
<li>build/tests run on the CI server match build/tests run on the developer machine</li>
</ul>
<p>
<code>ebean-test</code> is provided to make testing against docker test containers
as simple and good as using H2. Developers new to a project can just <code>git clone</code>
and <code>mvn clean test</code> and it "just works" without any setup steps.
</p>
<p>
For Postgres, MySql, SQL Server we can very successfully use docker test containers today.
For the relatively heavier databases like Oracle, SAP Hana and DB2 we can be successful but
there can be some argument for staying with H2 for testing depending on the situation.
</p>
<p>
Personally I have had great results using ebean-test / docker test containers
over the last few years (largely Postgres). I highly recommend people look at this
approach aiming for great test coverage, simpler test code and reduced variation between
developer, CI and Production.
</p>
<p>
ebean-test also supports using <a href="#elasticsearch">ElasticSearch</a> and
<a href="#redis">Redis</a> containers.
</p>
<h2 id="ebean-test">ebean-test dependency</h2>
<h3>1. Add ebean-test as a test dependency</h3>
```xml
<dependency>
<groupId>io.ebean</groupId>
<artifactId>ebean-test</artifactId>
<version>12.12.1</version>
<scope>test</scope>
</dependency>
```
<h3 id="application-test">2. Add application-test.yaml</h3>
<p>
Add into <code>src/test/resources</code> a <code>application-test.yaml</code> configuration file
that we use for testing.
</p>
```yml
ebean:
test:
platform: h2 #, h2, postgres, mysql, oracle, sqlserver, hana, clickhouse, sqlite
ddlMode: dropCreate # none | dropCreate | migrations | create
dbName: my_app
```
<p>
We can modify this test configuration to control what DDL is executed (create-all.sql or migrations)
and the database platform we want to test against (potentially using docker).
</p>
<h3>3. Add ~/.ebean/ignore-docker-shutdown</h3>
```sh
mkdir ~/.ebean
touch ~/.ebean/ignore-docker-shutdown
```
<p>
For running tests on CI servers we typically want to stop and remove the docker containers
when the tests have completed. However, for local development we want to keep the docker containers
running making it faster to run tests.
</p>
<p>
Adding a marker file <code>~/.ebean/ignore-docker-shutdown</code> means the docker containers
will stay running (which is good for local development).
</p>
<p>
ebean-test will take care of:
</p>
<ul>
<li>DDL generation and execution modes</li>
<li>Docker test container setup and execution based on the database platform</li>
<li>Current user and tenant provider if not already specified (to ease testing with @Who properties etc)</li>
</ul>
<h2 id="ddlmode">DDL Mode</h2>
<p>
Most of the time we use <code>dropCreate</code> mode which means that the database will
be dropped and then re-created before we run all the tests.
</p>
<p>
We use <em>migrations</em> to test database migrations.
</p>
<table class="table">
<tr>
<th>Mode</th>
<th>Description</th>
</tr>
<tr>
<td>dropCreate</td>
<td>Drop and then create all the tables etc. Most commonly used mode.</td>
</tr>
<tr>
<td>none</td>
<td>Do not run any DDL. Useful if we want to run 1 particular test without any DDL change.</td>
</tr>
<tr>
<td>migrations</td>
<td>Run the DB migration but first delete the database first ensuring the migration runs against a new database.</td>
</tr>
<tr>
<td>create</td>
<td>Run the create-all.sql DDL script but delete and recreate the database first.</td>
</tr>
</table>
<p class="mtm">
Note that <code>dropCreate</code> will generate <code>db-create-all.sql</code>
and <code>db-drop-all.sql</code> scripts and these can be found in the maven <code>target</code>
or gradle <code>build</code> directory.
</p>
<h2 id="docker">Docker test containers</h2>
<p>
Ebean provides docker test containers for Postgres, MySql, SqlServer, Oracle, Hana, Clickhouse, Redis
and ElasticSearch.
</p>
<p>
<em>ebean-test</em> 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:
</p>
<ul>
<li>Start a docker container(s)</li>
<li>Wait for the container to be ready</li>
<li>Create the database and user setting any permissions as necessary</li>
<li>When ready allow the tests to run</li>
</ul>
<p>
We can see/review what is occurring by increasing the logging for <code>io.ebean.docker</code>
to <code>TRACE</code>. When we do that we can see log messages like:
</p>
```text
... 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...
```
<h2 id="container-startup">Container startup</h2>
<p>
To startup the docker containers <code>ebean-test</code> hooks 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. This approach also avoids the need to modify test code.
</p>
<p>
This docker test container integration provides a similar developer experience to using H2 database.
That is, ebean-test brings up the database (if needed), sets up the database user, roles, schema etc
(if needed) and gets the database ready for testing by running DDL (typically drop and recreate tables etc)
... and then run all tests.
</p>
<p>
Developers new to a project can just <code>git clone</code> and <code>mvn clean test</code>
and it "just works" without any setup steps (as long as the developer machine has docker installed).
</p>
<h2 id="container-shutdown">Container shutdown</h2>
<p>
On developer machines we generally want to keep the docker container running such that running tests
is fast. For a developer running a single test via the IDE - most often this will just drop and
recreate tables as the container is already running closely matching the speed of using in-memory H2.
</p>
<p>
To keep docker containers running on developer machines we put a marker file at
<code>~/.ebean/ignore-docker-shutdown</code>.
</p>
<p>
On CI servers we want the docker containers to be stopped and removed at completion of tests. To do this we
set <code>shutdown</code> to either <code>remove</code> (to stop and remove the container) or <code>stop</code>
(to just stop the container).
</p>
```yml
ebean:
test:
shutdown: remove # stop | remove
platform: postgres # h2, postgres, mysql, oracle, sqlserver
ddlMode: dropCreate # none | dropCreate | migrations
dbName: my_app
```
<h2 id="not-docker">Not using Docker</h2>
<p>
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 <code>useDocker: false</code>.
</p>
<p>
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.
</p>
<p>
When we are using <code>useDocker: false</code> the database and user are expected to already exist.
</p>
```yml
ebean:
test:
useDocker: false ## DO NOT USE DOCKER
platform: postgres # h2, postgres, mysql, oracle, sqlserver
ddlMode: dropCreate # none | dropCreate | migrations | create
dbName: test
postgres:
username: test
password: test
url: jdbc:postgresql://localhost:5432/test
```
<h2 id="current-user">Current User and Tenant</h2>
<p>
ebean-test will automatically register a <em>current user provider</em> and a
<em>current tenant provider</em>. These are only set if you don't set them yourself.
</p>
<p>
This means is that without doing anything we can use <code>@WhoCreated / @WhoModified</code>
in tests and via <code>io.ebean.test.UserContext</code> we can set current user and tenant in tests.
</p>
```java
// set the current userId which will be put
// into 'WhoCreated' and 'WhoModified' properties
UserContext.setUserId("U1");
```
<h2 id="ddl-generation-properties">DDL generation properties</h2>
<p>
If we are <b>NOT</b> using <code>ebean-test</code> then we need to set appropriate properties to
control the generation and running of DDL. We use the properties below to control DDL generation
and execution of <code>db-create-all.sql</code> and <code>db-drop-all.sql</code>.
</p>
<table class="table">
<tr>
<th>Property</th>
<th>Description</th>
</tr>
<tr>
<td>ddl.generate</td>
<td>Set to true to generate the db-create-all.sql and db-drop-all.sql DDL scripts.</td>
</tr>
<tr>
<td>ddl.run</td>
<td>Set to true to run the db-create-all.sql, db-drop-all.sql and extra DDL scripts</td>
</tr>
<tr>
<td>ddl.createOnly</td>
<td>
Set to true to run the db-create-all.sql but <b>NOT</b> run the db-drop-all.sql. Mostly used with H2 database
in-memory testing when we know that the database is not populated / there are no tables to drop first.
</td>
</tr>
<tr>
<td>ddl.initSql</td>
<td>
Specify a SQL script to run prior to running the create-all ddl.
</td>
</tr>
<tr>
<td>ddl.seedSql</td>
<td>
Specify a SQL script to run after to running the create-all ddl. Typically this inserts seed data into the test database.
</td>
</tr>
<tr>
<td>ebean.migraton.run</td>
<td>Set to true or false to run the migrations when the EbeanServer starts</td>
</tr>
</table>
<h3>Example application-test.properties</h3>
```properties
ebean.db.ddl.generate=true
ebean.db.ddl.run=true
ebean.db.ddl.initSql=initialise-test-db.sql
ebean.db.ddl.seedSql=seed-test-db.sql
datasource.db.username=sa
datasource.db.password=
datasource.db.databaseUrl=jdbc:h2:mem:tests
datasource.db.databaseDriver=org.h2.Driver
```
<h2 id="scriptRunner">DDL/SQL Script Runner</h2>
<p>
We can use <code>ScriptRunner</code> to runs DDL and SQL scripts.
Typically these are scripts used for testing such as seed SQL scripts
or truncate SQL scripts.
</p>
<p>
Scripts are executed in their own transaction and committed on successful completion.
</p>
<h4>Example of simple use</h4>
```java
Database database = DB.getDefault();
database.script().run("/scripts/test-script.sql");
```
<h4>Example using place holders in the script</h4>
```java
Map<|String,String> placeholders = new HashMap();
placeholders.put("tableName", "e_basic");
Database database = DB.getDefault();
database.script().run("/scripts/test-script.sql", placeholders);
```
<p>
In our SQL scripts the way to reference the placeholder is:
</p>
<code>delete from ${r"${tableName}"}</code><br />
<code>select count(*) from ${r"${tableName}"}</code> <br/><br/>
<p>
Notice that, the path to the script should start with "/". Ebean will load the script as a
resource using <code>this.getClass().getResource(PATH_TO_RESOURCE)</code> so the resource should be
available in the class path.
</p>
<h2 id="elasticsearch">ElasticSearch</h2>
<p>
With Ebean we can use ElasticSearch by itself without another database (Postgres etc) or we
can use ElasticSearch in conjunction with another [source of truth] database (Postgres etc).
</p>
<p>
To automatically start ElasticSearch as a docker container set <code>ebean.docstore</code>
properties like those below in application-test.yaml:
</p>
```yml
ebean:
test:
platform: h2
ddlMode: dropCreate # none | dropCreate | migrations | create
dbName: myapp
docstore:
url: http://127.0.0.1:9201
active: true
generateMapping: true
dropCreate: true
elastic:
version: 5.6.0
port: 9201
```
<p>
Goto <a href="/docs/database/elasticsearch">database / elasticsearch</a> for more details.
</p>
<h2 id="redis">Redis</h2>
<p>
When we want to use Redis for L2 caching we can get <code>ebean-test</code> to automatically
start a redis docker test container. To do this add <code>ebean.test.redis=latest</code>
property like the example below:
</p>
```yml
ebean:
test:
redis: latest
platform: h2 # h2, postgres, mysql, oracle, sqlserver, sqlite
ddlMode: dropCreate # none | dropCreate | migrations | create
dbName: my_app
```
<p>
Goto <a href="/docs/database/redis">database / redis</a> for more details.
</p>
<@next_edit "CI Testing" "/docs/ci-testing" "/docs/testing/index.html"/>
</body>
</html>