-
Notifications
You must be signed in to change notification settings - Fork 29
/
index.html
500 lines (451 loc) · 18.5 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
<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>
<pre content="xml">
<dependency>
<groupId>io.ebean</groupId>
<artifactId>ebean-test</artifactId>
<version>14.1.0</version>
<scope>test</scope>
</dependency>
</pre>
<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>
<pre content="yml">
ebean:
test:
platform: h2 #, h2, postgres, mysql, oracle, sqlserver, hana, clickhouse, sqlite
ddlMode: dropCreate # none | dropCreate | migrations | create
dbName: my_app
</pre>
<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>
<pre content="sh">
mkdir ~/.ebean
touch ~/.ebean/ignore-docker-shutdown
</pre>
<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="test-platform">ebean.test.platform - application-test.yaml</h2>
<p>
We use <code>ebean.test.platform</code> to specify the database platform we want to use when running tests.
For example, we can specify <em>h2, postgres, mysql</em> etc as the platform to run the tests.
</p>
<h5>e.g. Testing against Postgres</h5>
<pre content="yml">
ebean:
test:
platform: postgres # h2, postgres, ...
ddlMode: dropCreate # none | dropCreate | migrations | create
dbName: my_app
</pre>
<h5>e.g. Testing against MariaDB</h5>
<pre content="yml">
ebean:
test:
platform: mariadb
ddlMode: dropCreate # none | dropCreate | migrations | create
dbName: my_app
</pre>
<p>
For more details on each database platform see: <br/>
<a href="/docs/database/clickhouse">clickhouse</a>
, <a href="/docs/database/cockroach">cockroach</a>
, <a href="/docs/database/db2">db2</a>
, <a href="/docs/database/h2">h2</a>
, <a href="/docs/database/hana">hana</a>
, <a href="/docs/database/mariadb">mariadb</a>
, <a href="/docs/database/mysql">mysql</a>
, <a href="/docs/database/nuodb">nuodb</a>
, <a href="/docs/database/oracle">oracle</a>
, <a href="/docs/database/postgres">postgres</a>
, <a href="/docs/database/sqlite">sqlite</a>
, <a href="/docs/database/sqlserver">sqlserver</a>
, <a href="/docs/database/yugabyte">yugabytedb</a>
</p>
<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, MariaDB, MySql, SqlServer, Oracle, Hana, DB2, Clickhouse,
CockroachDB, YugabyteDB, Redis, ElasticSearch plus DynamoDB and Localstack.
</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>
<pre content="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...
</pre>
<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>
<pre content="yml">
ebean:
test:
shutdown: remove # stop | remove
platform: postgres # h2, postgres, mysql, oracle, sqlserver
ddlMode: dropCreate # none | dropCreate | migrations
dbName: my_app
</pre>
<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>
<pre content="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
</pre>
<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>
<pre content="java">
// set the current userId which will be put
// into 'WhoCreated' and 'WhoModified' properties
UserContext.setUserId("U1");
</pre>
<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>
<pre content="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
</pre>
<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>
<pre content="java">
Database database = DB.getDefault();
database.script().run("/scripts/test-script.sql");
</pre>
<h4>Example using place holders in the script</h4>
<pre content="java">
Map<|String,String> placeholders = new HashMap();
placeholders.put("tableName", "e_basic");
Database database = DB.getDefault();
database.script().run("/scripts/test-script.sql", placeholders);
</pre>
<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>
<pre content="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
</pre>
<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>
<pre content="yml">
ebean:
test:
redis: latest
platform: h2 # h2, postgres, mysql, oracle, sqlserver, sqlite
ddlMode: dropCreate # none | dropCreate | migrations | create
dbName: my_app
</pre>
<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>