feat(engine): add testcontainers integration to test suite

* Add TC integration module to the project. * Add a 'testcontainers' profile to settings.xml. * Add Testcontainers integration usage in TESTING.md. Related to CAM-11281, closes #1359
camunda · Aug 30, 2021 · 6ec14c1 · 6ec14c1
1 parent 7dc6bbc
commit 6ec14c1
Show file tree

Hide file tree

Showing 24 changed files with 617 additions and 15 deletions.
diff --git a/TESTING.md b/TESTING.md
@@ -120,6 +120,25 @@ To run the test suite against a given database, select the `database` profile an
 mvn test -Pdatabase,postgresql -Ddatabase.url=jdbc:postgresql:pgdb -Ddatabase.username=pguser -Ddatabase.password=pgpassword
 ```
 
+## Testing a Camunda-supported Database with Testcontainers
+
+It is also possible to use Testcontainers to run the test suite agains a given database. To ensure that your database 
+Docker image can be used this way, please perform the following steps:
+
+1. Ensure that your Docker image is compatible with Testcontainers;
+1. Provide the repository name of your Docker image in the [testcontainers.properties](./engine/src/test/resources/testcontainers.properties) file;
+   * If you use a private Docker repository, please include it in the Docker image name (e.g. private.registry.org/postgres)
+1. In the `pom.xml` file located in the `./database` folder, check out the `database.tc.url` property to ensure that 
+   the Docker tags match.
+
+At the moment, Testcontainers can be used with the Camunda-supported versions of the following databases. Please make 
+sure that the database image is configured according to [this guide](https://docs.camunda.org/manual/latest/user-guide/process-engine/database/database-configuration/#isolation-level-configuration):
+* PostgreSQL
+* MariaDB
+* MySQL
+* CockroachDB
+* MS-SQL 2017/2019 ([MSSQL-specific configuraion guide](https://docs.camunda.org/manual/latest/user-guide/process-engine/database/mssql-configuration/))
+
 # Limiting the Number of Engine Unit Tests
 
 Due to the fact that the number of unit tests in the camunda engine increases daily and that you might just want to test a certain subset of tests the maven-surefire-plugin is configured in a way that you can include/exclude certain packages in your tests.

diff --git a/database/pom.xml b/database/pom.xml
@@ -38,6 +38,9 @@
 
     <!-- needed for sql script and backward compatibility checks -->
     <camunda.version.old>7.15.0</camunda.version.old>
+
+    <!-- Testcontainers JDBC URL parameters. By default, an empty string -->
+    <database.tc.params></database.tc.params>
   </properties>
 
   <dependencyManagement>
@@ -259,6 +262,8 @@
         <database.type>mariadb</database.type>
         <database.driver>org.mariadb.jdbc.Driver</database.driver>
         <database.datasource.class>org.mariadb.jdbc.MySQLDataSource</database.datasource.class>
+        <database.tc.url>cammariadb:10.3</database.tc.url>
+        <database.tc.params>/${database.name}?user=${database.username}&amp;amp;password=${database.password}</database.tc.params>
       </properties>
 
       <dependencies>
@@ -292,13 +297,21 @@
         <version.mariadb>${version.mariadb.galera}</version.mariadb>
       </properties>
     </profile>
+    <profile>
+      <id>mariadb-10.2</id>
+      <properties>
+        <database.tc.url>cammariadb:10.2</database.tc.url>
+      </properties>
+    </profile>
 
     <profile>
       <id>mysql</id>
       <properties>
         <database.type>mysql</database.type>
         <database.driver>com.mysql.cj.jdbc.Driver</database.driver>
         <database.datasource.class>com.mysql.cj.jdbc.MysqlDataSource</database.datasource.class>
+        <database.tc.url>cammysql:8.0</database.tc.url>
+        <database.tc.params>/${database.name}?sendFractionalSeconds=false&amp;amp;user=${database.username}&amp;amp;password=${database.password}</database.tc.params>
       </properties>
 
       <dependencies>
@@ -326,6 +339,12 @@
         </pluginManagement>
       </build>
     </profile>
+    <profile>
+      <id>mysql-5.7</id>
+      <properties>
+        <database.tc.url>cammysql:5.7</database.tc.url>
+      </properties>
+    </profile>
 
     <profile>
       <id>oracle</id>
@@ -436,6 +455,7 @@
         <database.datasource.class>org.postgresql.ds.PGSimpleDataSource</database.datasource.class>
         <jboss.datasource.filename>postgresql-ds.xml</jboss.datasource.filename>
         <hibernate.dialect>org.hibernate.dialect.PostgreSQLDialect</hibernate.dialect>
+        <database.tc.url>campostgresql:13.2</database.tc.url>
       </properties>
 
       <dependencies>
@@ -478,6 +498,7 @@
         <database.datasource.class>org.postgresql.ds.PGSimpleDataSource</database.datasource.class>
         <jboss.datasource.filename>postgresql-ds.xml</jboss.datasource.filename>
         <hibernate.dialect>org.hibernate.dialect.PostgreSQLDialect</hibernate.dialect>
+        <database.tc.url>camcockroachdb:20.1.3</database.tc.url>
       </properties>
 
       <dependencies>
@@ -513,6 +534,8 @@
         <database.type>mssql</database.type>
         <database.driver>com.microsoft.sqlserver.jdbc.SQLServerDriver</database.driver>
         <database.datasource.class>com.microsoft.sqlserver.jdbc.SQLServerDataSource</database.datasource.class>
+        <database.tc.url>camsqlserver:2019</database.tc.url>
+        <database.tc.params>;DatabaseName=${database.name};user=${database.username};password=${database.password};</database.tc.params>
       </properties>
 
       <dependencies>
@@ -540,6 +563,26 @@
         </pluginManagement>
       </build>
     </profile>
+    <profile>
+      <id>sqlserver-2017</id>
+      <properties>
+        <database.tc.url>camsqlserver:2017</database.tc.url>
+      </properties>
+    </profile>
+
+    <profile>
+      <id>testcontainers</id>
+      <dependencies>
+        <!-- Testcontainers depends on docker-java which depends on jackson-annotations -->
+        <dependency>
+          <artifactId>jackson-annotations</artifactId>
+          <groupId>com.fasterxml.jackson.core</groupId>
+          <version>2.12.1</version>
+          <scope>test</scope>
+        </dependency>
+      </dependencies>
+    </profile>
+
   </profiles>
 
 </project>
diff --git a/engine/pom.xml b/engine/pom.xml
@@ -124,7 +124,7 @@
       <groupId>org.camunda.connect</groupId>
       <artifactId>camunda-connect-connectors-all</artifactId>
       <scope>runtime</scope>
-    </dependency> 
+    </dependency>
 
     <!-- provided dependencies -->
 
@@ -139,7 +139,7 @@
       <artifactId>hibernate-jpa-2.0-api</artifactId>
       <scope>provided</scope>
     </dependency>
-    
+
     <dependency>
       <groupId>org.apache.geronimo.specs</groupId>
       <artifactId>geronimo-jta_1.1_spec</artifactId>
@@ -235,6 +235,13 @@
       <scope>test</scope>
     </dependency>
 
+    <dependency>
+      <groupId>org.camunda.bpm</groupId>
+      <artifactId>camunda-test-utils-testcontainers</artifactId>
+      <version>${project.version}</version>
+      <scope>test</scope>
+    </dependency>
+
     <dependency>
       <groupId>org.hamcrest</groupId>
       <artifactId>hamcrest-library</artifactId>
@@ -270,7 +277,7 @@
       <artifactId>wiremock</artifactId>
       <scope>test</scope>
     </dependency>
-    
+
     <dependency>
       <groupId>org.codehaus.groovy</groupId>
       <artifactId>groovy-all</artifactId>
@@ -288,18 +295,19 @@
       <artifactId>jruby-complete</artifactId>
       <scope>test</scope>
     </dependency>
-    
+
     <dependency>
       <groupId>org.graalvm.js</groupId>
       <artifactId>js</artifactId>
       <scope>test</scope>
     </dependency>
-    
+
     <dependency>
       <groupId>org.graalvm.js</groupId>
       <artifactId>js-scriptengine</artifactId>
       <scope>test</scope>
     </dependency>
+
   </dependencies>
 
 
@@ -311,7 +319,7 @@
     <mail.server.port>5025</mail.server.port>
     <authorizationCheckRevokes>auto</authorizationCheckRevokes>
     <jdbcBatchProcessing>true</jdbcBatchProcessing>
-    
+
     <!-- We shade artifacts into the jar, so we need to generate a dependency BOM
     for the license book -->
     <skip-third-party-bom>false</skip-third-party-bom>
@@ -373,6 +381,7 @@
           <include>**/*camunda.cfg.xml</include>
           <include>**/camunda.cfg.*.xml</include>
           <include>testconfig.properties</include>
+          <include>**/testcontainers.properties</include>
         </includes>
       </testResource>
     </testResources>
@@ -861,7 +870,7 @@
         </plugins>
       </build>
     </profile>
-    
+
     <profile>
       <id>java15</id>
       <activation>

diff --git a/engine/src/test/resources/container-license-acceptance.txt b/engine/src/test/resources/container-license-acceptance.txt
@@ -0,0 +1,2 @@
+registry.camunda.cloud/team-cambpm/camunda-ci-sqlserver:2017
+registry.camunda.cloud/team-cambpm/camunda-ci-sqlserver:2019
diff --git a/engine/src/test/resources/logback-test.xml b/engine/src/test/resources/logback-test.xml
@@ -21,11 +21,14 @@
 
   <logger name="org.camunda.bpm.engine.test" level="debug" />
 
+  <!-- Ignore Testcontainers debug logs -->
+  <logger name="org.testcontainers" level="info" />
+  <logger name="com.github" level="info" />
+
 <!--  <logger name="org.camunda.bpm.engine.impl.persistence.entity" level="debug" />-->
 <!--  <logger name="org.camunda.bpm.engine.impl.persistence.entity.JobEntity" level="debug" />-->
 <!--  <logger name="org.camunda.bpm.engine.impl.persistence.entity.HistoricJobLogEntity" level="debug" />-->
 
-
 <!--   <logger name="org.camunda.bpm.engine.history" level="debug" /> -->
 
 <!--   <logger name="org.camunda.bpm.engine.bpmn.parser" level="debug" /> -->

diff --git a/internal-dependencies/pom.xml b/internal-dependencies/pom.xml
@@ -347,6 +347,37 @@
         <version>1.5.0</version>
       </dependency>
 
+      <!-- TestContainers dependencies -->
+      <dependency>
+        <groupId>org.testcontainers</groupId>
+        <artifactId>testcontainers</artifactId>
+        <version>${version.testcontainers}</version>
+      </dependency>
+      <dependency>
+        <groupId>org.testcontainers</groupId>
+        <artifactId>mysql</artifactId>
+        <version>${version.testcontainers}</version>
+      </dependency>
+      <dependency>
+        <groupId>org.testcontainers</groupId>
+        <artifactId>mariadb</artifactId>
+        <version>${version.testcontainers}</version>
+      </dependency>
+      <dependency>
+        <groupId>org.testcontainers</groupId>
+        <artifactId>postgresql</artifactId>
+        <version>${version.testcontainers}</version>
+      </dependency>
+      <dependency>
+        <groupId>org.testcontainers</groupId>
+        <artifactId>mssqlserver</artifactId>
+        <version>${version.testcontainers}</version>
+      </dependency>
+      <dependency>
+        <groupId>org.testcontainers</groupId>
+        <artifactId>cockroachdb</artifactId>
+        <version>${version.testcontainers}</version>
+      </dependency>
     </dependencies>
   </dependencyManagement>
 </project>
diff --git a/parent/pom.xml b/parent/pom.xml
@@ -39,6 +39,7 @@
     <version.assertj>2.9.1</version.assertj>
     <version.mockito>1.9.5</version.mockito>
     <version.wiremock>1.58</version.wiremock>
+    <version.testcontainers>1.16.0</version.testcontainers>
 
     <version.commonj>1.1.0</version.commonj>
     <version.bouncycastle>1.47</version.bouncycastle>

diff --git a/pom.xml b/pom.xml
@@ -79,6 +79,7 @@
         <module>model-api</module>
         <module>typed-values</module>
         <module>engine-dmn</module>
+        <module>test-utils/testcontainers</module>
 
         <module>engine</module>
         <module>engine-cdi</module>

diff --git a/settings/maven/nexus-settings.xml b/settings/maven/nexus-settings.xml
@@ -20,7 +20,6 @@
         <database.name>postgres</database.name>
         <database.username>root</database.username>
         <database.password></database.password>
-        <database.url>jdbc:postgresql://${database.host}:${database.port}/${database.name}</database.url>
       </properties>
     </profile>
     <profile>
@@ -31,7 +30,6 @@
         <database.name>engine</database.name>
         <database.username>camunda</database.username>
         <database.password>camunda</database.password>
-        <database.url>jdbc:db2://${database.host}:${database.port}/${database.name}</database.url>
       </properties>
     </profile>
     <profile>
@@ -52,7 +50,6 @@
         <database.name>process-engine</database.name>
         <database.username>camunda</database.username>
         <database.password>camunda</database.password>
-        <database.url>jdbc:mariadb://${database.host}:${database.port}/${database.name}</database.url>
       </properties>
     </profile>
     <profile>
@@ -63,7 +60,6 @@
         <database.name>process-engine</database.name>
         <database.username>camunda</database.username>
         <database.password>camunda</database.password>
-        <database.url>jdbc:mysql://${database.host}:${database.port}/${database.name}?sendFractionalSeconds=false</database.url>
       </properties>
     </profile>
     <profile>
@@ -74,7 +70,6 @@
         <database.name>xe</database.name>
         <database.username>camunda</database.username>
         <database.password>camunda</database.password>
-        <database.url>jdbc:oracle:thin:@${database.host}:${database.port}:${database.name}</database.url>
       </properties>
     </profile>
     <profile>
@@ -97,7 +92,6 @@
         <database.name>process-engine</database.name>
         <database.username>camunda</database.username>
         <database.password>camunda</database.password>
-        <database.url>jdbc:postgresql://${database.host}:${database.port}/${database.name}</database.url>
       </properties>
     </profile>
     <profile>
@@ -108,7 +102,14 @@
         <database.name>process-engine</database.name>
         <database.username>camunda</database.username>
         <database.password>Camunda-BPM123</database.password>
-        <database.url>jdbc:sqlserver://${database.host}:${database.port};DatabaseName=${database.name}</database.url>
+      </properties>
+    </profile>
+    <profile>
+      <!-- This profile must always be put last to ensure that
+      the correct DB url is set when Testcontainers is used -->
+      <id>testcontainers</id>
+      <properties>
+        <database.url>jdbc:tc:${database.tc.url}://localhost:${database.port}${database.tc.params}</database.url>
       </properties>
     </profile>
   </profiles>

diff --git a/test-utils/testcontainers/README.md b/test-utils/testcontainers/README.md
@@ -0,0 +1,13 @@
+# Usage of the Testcontainers wrapper
+
+1. Add a `testcontainers.properties` file to the root of your test resources directory ([example file](./testing/src/test/resources/testcontainers.properties));
+1. Add the repository names of the Docker images you would like to use. The following custom properties are available:
+   * `postgresql.container.image`
+   * `cockroachdb.container.image`
+   * `mariadb.container.image`
+   * `mysql.container.image`
+   * `mssql.container.image`
+1. If using MS-SQL, add a `container-license-acceptance.txt` file to the root of your test resources directory [example file](./testing/src/test/resources/container-license-acceptance.txt). 
+   * Add the repository names of the MS-SQL Docker images your are planning to use.
+1. Modify your JDBC url to contain the `tc:cam[DB_NAME]:[DB_VERSION]` segment. E.g. `jdbc:tc:campostgresql:13.2:///process-engine` 
+   More details [here](https://www.testcontainers.org/modules/databases/jdbc/).