ebean-orm.github.io/docs/testing/index.html at master · ebean-orm/ebean-orm.github.io

712 lines (651 loc) · 33.3 KB
<!doctype html>
<html lang="en">
  <title>Testing | Ebean</title>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
  <link rel="shortcut icon" href="/images/favicon.ico">
  <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto|Source+Sans+Pro|Ubuntu&display=swap">
  <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.1.0/css/all.css" integrity="sha384-lKuwvrZot6UHsBSfcMvOkWwlCMgc0TaWr+30HWe3a4ltaBwTZhyTEggF5tJv8tbt" crossorigin="anonymous">
  <link rel="stylesheet" href="/css/reset3.css">
  <link rel="stylesheet" href="/css/site3.css">
  <link rel="stylesheet" href="/css/pygments3.css">
<div id="main">
<div id="banner">
    <nav id="top">
      <h1 id="breadcrumb">
        <a class="nav-logo" href="/"><img src="/images/logo-200.png" height="35"></a>&nbsp;&nbsp;<a href="/docs">Documentation</a><span class="sep">&nbsp;/&nbsp;</span><span class="last">Testing</span>
      </h1>
        <li><a onclick="toggleTheme();" title="switch dark light theme"><i class="fas fa-adjust"></i></a></li>
      </ul>
  </header>
<div class="grid grid-docs">
<nav class="side">
      <li class="nav0 ">
    <a  href="/docs/getting-started">Getting started</a>
  <li class="nav0 ">
    <a  href="/docs/intro">Introduction</a>
  <li class="nav0 active">
    <a class="active" href="/docs">Documentation</a>
  <li class="nav1 ">
    <a  href="/docs/agents">AI Agents</a>
  <li class="nav1 ">
    <a  href="/docs/best-practice">Best practice</a>
  <li class="nav1 ">
    <a  href="/docs/query">Query</a>
  <li class="nav1 ">
    <a  href="/docs/persist">Persist</a>
  <li class="nav1 ">
    <a  href="/docs/transactions">Transactions</a>
  <li class="nav1 ">
    <a  href="/docs/mapping">Mapping</a>
  <li class="nav1 ">
    <a  href="/docs/ddl-generation">DDL & Migrations</a>
  <li class="nav1 ">
    <a  href="/docs/logging">Logging</a>
  <li class="nav1 active">
    <a class="active" href="/docs/testing">Testing</a>
<ul class="nav nav-scroll">
  <li><a href="#third-age">Third age of testing</a></li>
  <li><a href="#ebean-test">ebean-test dependency</a></li>
  <li><a href="#ddlmode">DDL Mode</a></li>
  <li><a href="#docker">Docker test containers</a></li>
    <a  href="/docs/testing/#scriptRunner#container-startup">Container startup</a>
    <a  href="/docs/testing/#container-shutdown">Container shutdown</a>
    <a  href="/docs/testing/#not-docker">Not using docker</a>
    <a  href="/docs/testing/#current-user">Current User & Tenant</a>
    <a  href="/docs/testing/#ddl-generation-properties">DDL generation properties</a>
    <a  href="/docs/testing/#scriptRunner">DDL/SQL Script runner</a>
    <a  href="/docs/testing/test-entity-builder">Test Entity Builder</a>
    <a  href="/docs/testing/ci-testing">CI - Jenkins etc</a>
  <li class="nav1 ">
    <a  href="/docs/read-replicas">Read Replicas</a>
  <li class="nav1 ">
    <a  href="/docs/database">Database platforms</a>
  <li class="nav1 ">
    <a  href="/docs/multi-database">Multiple databases</a>
  <li class="nav1 ">
    <a  href="/docs/kotlin">Kotlin</a>
        <li><a href="/docs/tuning">Tuning</a></li>
  <li class="nav1 ">
    <a  href="/docs/features">Features</a>
      </ul>
  <li class="nav0 ">
    <a  href="/support">Getting help</a>
    <li class="nav0 ">
      <a target="_blank" href="/apidoc/13">API Javadoc</a>
  <li class="nav0 ">
    <a  href="/videos">Videos</a>
  <li class="nav0 ">
    <a  href="/docs/upgrading">Upgrading</a>
  <li class="nav0 ">
    <a  href="/docs/deprecated">Deprecated</a>
  <li class="nav0 ">
    <a  href="/releases">Releases</a>
  <article>
<form action="https://www.google.com/search" method="get" class="inline-form">
  <input type="hidden" name="as_sitesearch" value="ebean.io">
  <div id="page-search">
    <div class="input-group">
      <input class="frm" name="q" id="searchinput" type="text" placeholder="Search... (press 's' to focus)" data-placeholder-focus="Search... (use '↑', '↓' and '⏎' to select results)" data-placeholder-blur="Search... (press 's' to focus)" autocomplete="off">
      <div class="input-group-btn">
        <button class="frm" type="submit"><i class="fas fa-search"></i></button>
      </div>
    <div id="page-search-results" style="display: none;">
      <ul id="search-results-container" class="search-results"><li class=" active"><a href="/docs" title="Docs"><span style="color:#777;">Docs</span> Documentation </a></li><li class=""><small style="color:#999;">And 101 more...</small></li></ul>
<h2 id="third-age">Third age of testing</h2>
  Rob Opinion: I believe with respect to testing and persistence we are now in
  the "3rd age" of testing.
<h3>(I) First age - all persistence mocked/stubbed</h3>
  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".
<h3>(II) Second age - in memory DB's</h3>
  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.
  This resulted in far less mocking/stubbing used in tests.
  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).
<h3>(III) Third age - testing using docker DB's</h3>
  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).
  <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>
  <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.
  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.
  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.
  ebean-test also supports using <a href="#elasticsearch">ElasticSearch</a> and
  <a href="#redis">Redis</a> containers.
<h2 id="ebean-test">ebean-test dependency</h2>
<h3>1. Add ebean-test as a test dependency</h3>
<div class="syntax xml"><div class="highlight"><pre><span></span><span class="nt">&lt;dependency&gt;</span>
  <span class="nt">&lt;groupId&gt;</span>io.ebean<span class="nt">&lt;/groupId&gt;</span>
  <span class="nt">&lt;artifactId&gt;</span>ebean-test<span class="nt">&lt;/artifactId&gt;</span>
  <span class="nt">&lt;version&gt;</span>17.2.0<span class="nt">&lt;/version&gt;</span>
  <span class="nt">&lt;scope&gt;</span>test<span class="nt">&lt;/scope&gt;</span>
<span class="nt">&lt;/dependency&gt;</span>
</pre></div>
<h3 id="application-test">2. Add application-test.yaml</h3>
  Add into <code>src/test/resources</code> a <code>application-test.yaml</code> configuration file
  that we use for testing.
<div class="syntax yml"><div class="highlight"><pre><span></span><span class="nt">ebean</span><span class="p">:</span>
  <span class="nt">test</span><span class="p">:</span>
    <span class="nt">platform</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">h2</span> <span class="c1">#, h2, postgres, mysql, oracle, sqlserver, hana, clickhouse, sqlite</span>
    <span class="nt">ddlMode</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">dropCreate</span> <span class="c1"># none | dropCreate | migrations | create</span>
    <span class="nt">dbName</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">my_app</span>
</pre></div>
  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).
<h3>3. Add ~/.ebean/ignore-docker-shutdown</h3>
<div class="syntax sh"><div class="highlight"><pre><span></span>mkdir ~/.ebean
touch ~/.ebean/ignore-docker-shutdown
</pre></div>
  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.
  Adding a marker file <code>~/.ebean/ignore-docker-shutdown</code> means the docker containers
  will stay running (which is good for local development).
  ebean-test will take care of:
  <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>
<h2 id="testEntityBuilder">Test Entity Builder</h2>
  The <code>TestEntityBuilder</code> class is a utility for rapidly creating test entity instances
  with auto-populated random values. This is particularly useful for integration tests where you need
  representative data without manually setting each field.
  Key features:
  <li>Auto-generates appropriate random values for all supported types</li>
  <li>Respects column length and decimal precision constraints</li>
  <li>Handles entity relationships with cascade persist</li>
  <li>Cycle detection prevents infinite recursion</li>
  <li>Customizable via subclassing <code>RandomValueGenerator</code></li>
  The recommended way to use <code>TestEntityBuilder</code> in a DI-managed test context (Spring or Avaje Inject)
  is to register it as a bean so it can be injected directly — no <code>@BeforeEach</code> setup required:
<div class="syntax java"><div class="highlight"><pre><span></span><span class="c1">// Spring Boot — add to a @TestConfiguration class</span>
<span class="nd">@Bean</span>
<span class="n">TestEntityBuilder</span> <span class="nf">testEntityBuilder</span><span class="o">(</span><span class="n">Database</span> <span class="n">database</span><span class="o">)</span> <span class="o">{</span>
  <span class="k">return</span> <span class="n">TestEntityBuilder</span><span class="o">.</span><span class="na">builder</span><span class="o">(</span><span class="n">database</span><span class="o">).</span><span class="na">build</span><span class="o">();</span>
<span class="o">}</span>
<span class="c1">// Then inject in test classes:</span>
<span class="nd">@Autowired</span> <span class="nx">TestEntityBuilder</span> <span class="nx">builder</span><span class="o">;</span>
</pre></div>
  <a href="/docs/testing/test-entity-builder">See the full Test Entity Builder guide</a> for detailed setup,
  DI integration patterns (Spring and Avaje Inject), examples, and best practices.
  <strong>For AI Agents:</strong> Step-by-step guides for using TestEntityBuilder and other tasks are available at
  <a href="https://github.com/ebean-orm/ebean/blob/HEAD/docs/guides/README.md">docs/guides/README.md</a>
  in the GitHub repository.
<h2 id="test-platform">ebean.test.platform - application-test.yaml</h2>
  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.
<h5>e.g. Testing against Postgres</h5>
<div class="syntax yml"><div class="highlight"><pre><span></span><span class="nt">ebean</span><span class="p">:</span>
  <span class="nt">test</span><span class="p">:</span>
    <span class="nt">platform</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">postgres</span> <span class="c1"># h2, postgres, ...</span>
    <span class="nt">ddlMode</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">dropCreate</span> <span class="c1"># none | dropCreate | migrations | create</span>
    <span class="nt">dbName</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">my_app</span>
</pre></div>
<h5>e.g. Testing against MariaDB</h5>
<div class="syntax yml"><div class="highlight"><pre><span></span><span class="nt">ebean</span><span class="p">:</span>
  <span class="nt">test</span><span class="p">:</span>
    <span class="nt">platform</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">mariadb</span>
    <span class="nt">ddlMode</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">dropCreate</span> <span class="c1"># none | dropCreate | migrations | create</span>
    <span class="nt">dbName</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">my_app</span>
</pre></div>
  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>
<h2 id="ddlmode">DDL Mode</h2>
  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.
  We use <em>migrations</em> to test database migrations.
<table class="table">
    <th>Mode</th>
    <th>Description</th>
    <td>dropCreate</td>
    <td>Drop and then create all the tables etc. Most commonly used mode.</td>
    <td>none</td>
    <td>Do not run any DDL. Useful if we want to run 1 particular test without any DDL change.</td>
    <td>migrations</td>
    <td>Run the DB migration but first delete the database first ensuring the migration runs against a new database.</td>
    <td>create</td>
    <td>Run the create-all.sql DDL script but delete and recreate the database first.</td>
<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.
<h2 id="docker">Docker test containers</h2>
  Ebean provides docker test containers for Postgres, MariaDB, MySql, SqlServer, Oracle, Hana, DB2, Clickhouse,
  CockroachDB, YugabyteDB, Redis, ElasticSearch plus DynamoDB and Localstack.
  <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:
  <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>
  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:
<div class="syntax text"><div class="highlight"><pre><span></span>... 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 = &#39;test_ex&#39;
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 = &#39;test_ex&#39;
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></div>
<h2 id="container-startup">Container startup</h2>
  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.
  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.
  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).
<h2 id="container-shutdown">Container shutdown</h2>
  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.
  To keep docker containers running on developer machines we put a marker file at
  <code>~/.ebean/ignore-docker-shutdown</code>.
  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).
<div class="syntax yml"><div class="highlight"><pre><span></span><span class="nt">ebean</span><span class="p">:</span>
  <span class="nt">test</span><span class="p">:</span>
    <span class="nt">shutdown</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">remove</span>  <span class="c1"># stop | remove</span>
    <span class="nt">platform</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">postgres</span> <span class="c1"># h2, postgres, mysql, oracle, sqlserver</span>
    <span class="nt">ddlMode</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">dropCreate</span> <span class="c1"># none | dropCreate | migrations</span>
    <span class="nt">dbName</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">my_app</span>
</pre></div>
<h2 id="not-docker">Not using Docker</h2>
  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>.
  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  <code>useDocker: false</code> the database and user are expected to already exist.
<div class="syntax yml"><div class="highlight"><pre><span></span><span class="nt">ebean</span><span class="p">:</span>
  <span class="nt">test</span><span class="p">:</span>
    <span class="nt">useDocker</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">false</span>  <span class="c1">## DO NOT USE DOCKER</span>
    <span class="nt">platform</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">postgres</span> <span class="c1"># h2, postgres, mysql, oracle, sqlserver</span>
    <span class="nt">ddlMode</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">dropCreate</span> <span class="c1"># none | dropCreate | migrations | create</span>
    <span class="nt">dbName</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">test</span>
    <span class="nt">postgres</span><span class="p">:</span>
      <span class="nt">username</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">test</span>
      <span class="nt">password</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">test</span>
      <span class="nt">url</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">jdbc:postgresql://localhost:5432/test</span>
</pre></div>
<h2 id="current-user">Current User and Tenant</h2>
  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.
  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.
<div class="syntax java"><div class="highlight"><pre><span></span><span class="c1">// set the current userId which will be put</span>
<span class="c1">// into &#39;WhoCreated&#39; and &#39;WhoModified&#39; properties</span>
<span class="n">UserContext</span><span class="o">.</span><span class="na">setUserId</span><span class="o">(</span><span class="s">&quot;U1&quot;</span><span class="o">);</span>
</pre></div>
<h2 id="ddl-generation-properties">DDL generation properties</h2>
  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>.
<table class="table">
    <th>Property</th>
    <th>Description</th>
    <td>ddl.generate</td>
    <td>Set to true to generate the db-create-all.sql and db-drop-all.sql DDL scripts.</td>
    <td>ddl.run</td>
    <td>Set to true to run the db-create-all.sql, db-drop-all.sql and extra DDL scripts</td>
    <td>ddl.createOnly</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>ddl.initSql</td>
      Specify a SQL script to run prior to running the create-all ddl.
    <td>ddl.seedSql</td>
      Specify a SQL script to run after to running the create-all ddl. Typically this inserts seed data into the test database.
    <td>ebean.migraton.run</td>
    <td>Set to true or false to run the migrations when the Database starts</td>
<h3>Example application-test.properties</h3>
<div class="syntax properties"><div class="highlight"><pre><span></span><span class="na">ebean.db.ddl.generate</span><span class="o">=</span><span class="s">true</span>
<span class="na">ebean.db.ddl.run</span><span class="o">=</span><span class="s">true</span>
<span class="na">ebean.db.ddl.initSql</span><span class="o">=</span><span class="s">initialise-test-db.sql</span>
<span class="na">ebean.db.ddl.seedSql</span><span class="o">=</span><span class="s">seed-test-db.sql</span>
<span class="na">datasource.db.username</span><span class="o">=</span><span class="s">sa</span>
<span class="na">datasource.db.password</span><span class="o">=</span>
<span class="na">datasource.db.databaseUrl</span><span class="o">=</span><span class="s">jdbc:h2:mem:tests</span>
<span class="na">datasource.db.databaseDriver</span><span class="o">=</span><span class="s">org.h2.Driver</span>
</pre></div>
<h2 id="scriptRunner">DDL/SQL Script Runner</h2>
  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.
  Scripts are executed in their own transaction and committed on successful completion.
<h4>Example of simple use</h4>
<div class="syntax java"><div class="highlight"><pre><span></span><span class="n">Database</span> <span class="n">database</span> <span class="o">=</span> <span class="o">...;</span> <span class="c1">// injected or created with Database.builder()</span>
<span class="n">database</span><span class="o">.</span><span class="na">script</span><span class="o">().</span><span class="na">run</span><span class="o">(</span><span class="s">&quot;/scripts/test-script.sql&quot;</span><span class="o">);</span>
</pre></div>
<h4>Example using place holders in the script</h4>
<div class="syntax java"><div class="highlight"><pre><span></span><span class="n">Map</span><span class="o">&lt;</span><span class="n">String</span><span class="o">,</span><span class="n">String</span><span class="o">&gt;</span> <span class="n">placeholders</span> <span class="o">=</span> <span class="k">new</span> <span class="n">HashMap</span><span class="o">();</span>
<span class="n">placeholders</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">&quot;tableName&quot;</span><span class="o">,</span> <span class="s">&quot;e_basic&quot;</span><span class="o">);</span>
<span class="n">Database</span> <span class="n">database</span> <span class="o">=</span> <span class="o">...;</span> <span class="c1">// injected or created with Database.builder()</span>
<span class="n">database</span><span class="o">.</span><span class="na">script</span><span class="o">().</span><span class="na">run</span><span class="o">(</span><span class="s">&quot;/scripts/test-script.sql&quot;</span><span class="o">,</span> <span class="n">placeholders</span><span class="o">);</span>
</pre></div>
  In our SQL scripts the way to reference the placeholder is:
<code>delete from ${tableName}</code><br />
<code>select count(*) from ${tableName}</code> <br/><br/>
  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.
<h2 id="elasticsearch">ElasticSearch</h2>
  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).
  To automatically start ElasticSearch as a docker container set <code>ebean.docstore</code>
  properties like those below in application-test.yaml:
<div class="syntax yml"><div class="highlight"><pre><span></span><span class="nt">ebean</span><span class="p">:</span>
  <span class="nt">test</span><span class="p">:</span>
    <span class="nt">platform</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">h2</span>
    <span class="nt">ddlMode</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">dropCreate</span> <span class="c1"># none | dropCreate | migrations | create</span>
    <span class="nt">dbName</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">myapp</span>
  <span class="nt">docstore</span><span class="p">:</span>
    <span class="nt">url</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">http://127.0.0.1:9201</span>
    <span class="nt">active</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">true</span>
    <span class="nt">generateMapping</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">true</span>
    <span class="nt">dropCreate</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">true</span>
    <span class="nt">elastic</span><span class="p">:</span>
      <span class="nt">version</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">5.6.0</span>
      <span class="nt">port</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">9201</span>
</pre></div>
  Goto <a href="/docs/database/elasticsearch">database / elasticsearch</a> for more details.
<h2 id="redis">Redis</h2>
  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:
<div class="syntax yml"><div class="highlight"><pre><span></span><span class="nt">ebean</span><span class="p">:</span>
  <span class="nt">test</span><span class="p">:</span>
    <span class="nt">redis</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">latest</span>
    <span class="nt">platform</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">h2</span> <span class="c1"># h2, postgres, mysql, oracle, sqlserver, sqlite</span>
    <span class="nt">ddlMode</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">dropCreate</span> <span class="c1"># none | dropCreate | migrations | create</span>
    <span class="nt">dbName</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">my_app</span>
</pre></div>
  Goto <a href="/docs/database/redis">database / redis</a> for more details.
  <nav class="next">
    <p class="edit-page">
      <a href="https://github.com/ebean-orm/website-source/blob/master/docs/testing/index.html"><i class="fab fa-github"></i> Edit Page</a>
    <p class="next">
      <a href="/docs/ci-testing" class="btn btn-info">Next: CI Testing</a>
  </article>
<script src="https://code.jquery.com/jquery-3.4.1.slim.min.js" integrity="sha384-J6qa4849blE2+poT4WnyKhv5vZF5SrPo0iEjwBvKU7imGFAV0wwj1yYfoRSJoZ+n" crossorigin="anonymous"></script>
<script src="/js/site3.js"></script>
<script src="/js/search3.js"></script>
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-75181644-1"></script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'UA-75181644-1');
Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

index.html

Latest commit

History

index.html

File metadata and controls
