This is an automated email from the ASF dual-hosted git repository.
asf-gitbox-commits pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/cayenne-website.git
The following commit(s) were added to refs/heads/master by this push:
new f92e75572 documenting new instructions for running tests with a
specific DB
f92e75572 is described below
commit f92e7557265dd6a2ebf1419762213bb8cf14e179
Author: Andrus Adamchik <[email protected]>
AuthorDate: Sun May 17 10:07:26 2026 -0400
documenting new instructions for running tests with a specific DB
---
src/main/site/content/dev/running-unit-tests.md | 214 ++++++++++++------------
1 file changed, 107 insertions(+), 107 deletions(-)
diff --git a/src/main/site/content/dev/running-unit-tests.md
b/src/main/site/content/dev/running-unit-tests.md
index b0b6570b6..d1c1b6627 100644
--- a/src/main/site/content/dev/running-unit-tests.md
+++ b/src/main/site/content/dev/running-unit-tests.md
@@ -4,8 +4,9 @@ weight: 70
url: /dev/running-unit-tests.html
---
-Cayenne provides a comprehensive suite of unit tests. To execute unit tests
-you must first get Cayenne from Git, install JDK 1.8 and obtain the latest
Maven.
+Cayenne provides a comprehensive suite of unit and integration tests. To
+execute tests you must first get Cayenne from Git and satisfy the Maven build
+prerequisites.
## Prerequisites
@@ -13,108 +14,73 @@ Maven [build prerequisites and recommended
settings](/dev/building-cayenne.html)
{{% gap 2 %}}
-## Running Against Embedded HSQLDB
+## Running Against a Test Database
-No extra setup is required. Just run Maven:
+No extra setup is required to run the default test suite. By default,
+*cayenneTestConnection* is *hsql*:
$ cd cayenne
- $ mvn install
+ $ mvn verify
-or
+The *cayenneTestConnection* property selects the database backend for tests.
+Cayenne has preconfigured local backends that do not require Docker:
- $ cd cayenne
- $ mvn clean verify
-
-{{% gap %}}
-
-
-## Running Against In-memory Database
-
-Besides HSQLDB mentioned above Cayenne has preconfigured connection
information for
-following databases that support in-memory mode:
-
-* derby
+* hsql
* h2
+* derby
* sqlite
-For this databases you can run tests without any additional configuration by
only specifying
-*cayenneTestConnection* property that will activate required Maven profile:
+For example:
- $ mvn verify -DcayenneTestConnection=derby
+ $ mvn verify -DcayenneTestConnection=derby
-{{% gap %}}
-
-
-## Running Against Database in Docker
-**(Before Cayenne 4.2)**
-
-Another handy option to run Cayenne tests is with preconfigured docker
profiles.
-The only thing you need is to install Docker.
-
-You can run tests using following *cayenneTestConnection* properties:
-
-* mysql-docker
-* postgres-docker
-* sqlserver-docker
-
-Like with in-memory databases no additional setup is required:
-
- $ mvn verify -DcayenneTestConnection=mysql-docker
+Cayenne also has preconfigured backends based on
+[Testcontainers](https://www.testcontainers.org/). To run these, Docker must be
+installed and running:
-{{% gap %}}
-
-
-## Running Against Database with TestContainer
-**(Since Cayenne 4.2)**
-
-Another handy option to run Cayenne tests is with
[TestContainer](https://www.testcontainers.org/) which use Docker.
-The only thing you need is to install Docker and run it.
+* mysql
+* mariadb
+* postgres
+* sqlserver
+* oracle
+* db2
-You can run tests using following *cayenneTestConnection* properties:
+For example:
-* mysql-tc
-* postgres-tc
-* sqlserver-tc
-* mariadb-tc
-* oracle-tc
-* db2-tc
+ $ mvn verify -DcayenneTestConnection=mysql
-Like with in-memory databases no additional setup is required:
+You can override the default Docker image tag for Testcontainers-backed
+databases with *cayenneTestDbVersion*:
- $ mvn verify -DcayenneTestConnection=mysql-tc
+ $ mvn verify -DcayenneTestConnection=mysql -DcayenneTestDbVersion=8.4
{{% gap %}}
-## Running Against a Specific Database
+## Using a Custom Database
-Final option to run tests against any supported database is with manual
configuration.
+You can configure your own database to be used with tests instead of the
built-in options by following these steps:
{{%gap 1l2 %}}
-##### Step 1. Install JDBC Driver Jars in a Local Maven Repo
+### Install Special Drivers
-Most commercial drivers are not present in the public Maven repositories.
-So they have to be installed by the tester locally. The group and artifact
-ids are arbitrarily assigned in the main Cayenne POM, so users must follow
-the POM or the examples below.
+Most drivers used by Cayenne tests are available from Maven Central. A few
+commercial drivers still have to be installed by the tester locally. The group
+and artifact ids are assigned in the main Cayenne POM, so users must follow the
+POM or the examples below.
**FrontBase:**
$ mvn install:install-file -Dfile=frontbasejdbc.jar
-DgroupId=com.frontbase \
-DartifactId=frontbase-driver -Dversion=4.1 -Dpackaging=jar
-DgeneratePom=true
-**OpenBase:**
-
- $ mvn install:install-file -Dfile=OpenBaseJDBC.jar -DgroupId=com.openbase \
- -DartifactId=openbase-driver -Dversion=9 -Dpackaging=jar
-DgeneratePom=true
-
-**Oracle:**
+**Ingres:**
- $ mvn install:install-file -Dfile=ojdbc5.jar -DgroupId=com.oracle \
- -DartifactId=oracle-driver -Dversion=11 -Dpackaging=jar
-DgeneratePom=true
+ $ mvn install:install-file -Dfile=ingres-jdbc.jar -DgroupId=com.ingres \
+ -DartifactId=ingres-driver -Dversion=4.0.7 -Dpackaging=jar
-DgeneratePom=true
**Sybase:**
@@ -123,73 +89,107 @@ the POM or the examples below.
{{% gap 3l2 %}}
-##### Step 2. Run Tests Against Configured Data Source
+### Define DataSource Explicitly with CLI Arguments
-Database type and connection information can be specified either on the
-command line or via a configuration file. First let's look at the command
-line options:
+Database connection information can be specified either on the command line or
+via a configuration file. Built-in datasource names may also be overridden this
+way. First let's look at the command line options:
- $ mvn verify -DcayenneTestConnection=<profile_name> \
- -DcayenneAdapter=org.apache.cayenne.dba.mysql.MySQLAdapter \
+ $ mvn verify
-DcayenneJdbcUsername=myuser \
-DcayenneJdbcPassword=mypassword \
-DcayenneJdbcUrl=jdbc:mysql://localhost/cayenne \
- -DcayenneJdbcDriver=com.mysql.jdbc.Driver
+ -DcayenneJdbcDriver=com.mysql.cj.jdbc.Driver
-*cayenneTestConnection* is a property activating a DB-specific Maven
-profile. *<profile_name>* can be one of:
+You can still use `-DcayenneTestConnection=<connection_name>` here to pick an
existing profile, and simply override some of its
+setting.
-* db2
-* derby
-* firebird
-* frontbase
-* h2
-* ingres
-* mysql
-* openbase
-* oracle
-* postgres
-* sqlite
-* sqlserver
-* sybase
+### Define DataSource Explicitly in `connection.properties`
-Another way to store this information permanently for each profile is to
-create a directory *$HOME/.cayenne/* and place a file called
-*connection.properties* in this directory. File contents should be
-similar to this example:
+Another way to store this information permanently for each connection name is
+to create a directory *$HOME/.cayenne/* and place a file called
+*connection.properties* in this directory. File contents should be similar to
+this example:
- mysql.cayenne.adapter = org.apache.cayenne.dba.mysql.MySQLAdapter
mysql.jdbc.username = someuser
mysql.jdbc.password = somepasswd
mysql.jdbc.url =
jdbc:mysql://mysql.host:3306/test_db?useUnicode=true&characterEncoding=UTF-8&generateSimpleParameterMetadata=true
- mysql.jdbc.driver = com.mysql.jdbc.Driver
+ mysql.jdbc.driver = com.mysql.cj.jdbc.Driver
- postgres.adapter = org.apache.cayenne.dba.postgres.PostgresAdapter
postgres.jdbc.username = someuser
postgres.jdbc.password = somepasswd
postgres.jdbc.url = jdbc:postgresql://postgresql.host:5432/test_db
postgres.jdbc.driver = org.postgresql.Driver
- oracle.cayenne.adapter = org.apache.cayenne.dba.oracle.OracleAdapter
oracle.jdbc.username = someuser
oracle.jdbc.password = somepasswd
oracle.jdbc.url = jdbc:oracle:thin:@//oracle.host:1521/XE
- oracle.jdbc.driver = oracle.jdbc.driver.OracleDriver
+ oracle.jdbc.driver = oracle.jdbc.OracleDriver
- sqlserver.adapter = org.apache.cayenne.dba.sqlserver.SQLServerAdapter
sqlserver.jdbc.url =
jdbc:sqlserver://sqlserver.host:1433;databaseName=test_db
sqlserver.jdbc.driver = com.microsoft.sqlserver.jdbc.SQLServerDriver
sqlserver.jdbc.username = someuser
sqlserver.jdbc.password = somepasswd
- db2.adapter = org.apache.cayenne.dba.db2.DB2Adapter
db2.jdbc.username = someuser
db2.jdbc.password = somepasswd
db2.jdbc.url = jdbc:db2://db2.host:50000/test_db
db2.jdbc.driver = com.ibm.db2.jcc.DB2Driver
-Each property starts with the Maven profile name ("mysql" and "oracle" in
-the example above). Note that in this case you should still use
+Each property starts with the connection name ("mysql" and "oracle" in the
+example above). Note that in this case you should still use
*cayenneTestConnection*. E.g.:
- $ mvn verify -DcayenneTestConnection=mysql
\ No newline at end of file
+ $ mvn verify -DcayenneTestConnection=mysql
+
+{{% gap %}}
+
+
+## Legacy Configuration
+
+In Cayenne 4.2 and earlier the DB adapter class had to be configured
explicitly for
+custom datasources. This is the main difference from current Cayenne versions:
+newer versions detect the adapter from the JDBC connection, while Cayenne 4.2
+expects you to provide it.
+
+For those versions, when passing connection settings on the command line, use
+*cayenneAdapter* in addition to the JDBC properties:
+
+ $ mvn verify -DcayenneTestConnection=<connection_name> \
+ -DcayenneAdapter=org.apache.cayenne.dba.mysql.MySQLAdapter \
+ -DcayenneJdbcUsername=myuser \
+ -DcayenneJdbcPassword=mypassword \
+ -DcayenneJdbcUrl=jdbc:mysql://localhost/cayenne \
+ -DcayenneJdbcDriver=com.mysql.cj.jdbc.Driver
+
+In *$HOME/.cayenne/connection.properties*, Cayenne 4.2 expects the same
+connection-name prefix, but also needs an adapter key. For example, this is a
+current Cayenne 5.0 style entry:
+
+ mysql.jdbc.username = someuser
+ mysql.jdbc.password = somepasswd
+ mysql.jdbc.url = jdbc:mysql://mysql.host:3306/test_db
+ mysql.jdbc.driver = com.mysql.cj.jdbc.Driver
+
+The Cayenne 4.2 version must add *mysql.adapter*:
+
+ mysql.adapter = org.apache.cayenne.dba.mysql.MySQLAdapter
+ mysql.jdbc.username = someuser
+ mysql.jdbc.password = somepasswd
+ mysql.jdbc.url = jdbc:mysql://mysql.host:3306/test_db
+ mysql.jdbc.driver = com.mysql.cj.jdbc.Driver
+
+The even older *mysql.cayenne.adapter* key is also recognized as a legacy
alias.
+
+Testcontainers-backed profiles are another key-name difference. Cayenne 4.2
+used the *-tc* suffix:
+
+ $ mvn verify -DcayenneTestConnection=mysql-tc
+
+Current Cayenne uses the database name without the suffix:
+
+ $ mvn verify -DcayenneTestConnection=mysql
+
+The same old-vs-new pattern applies to other Testcontainers-backed databases,
+for example *postgres-tc* became *postgres*, and *sqlserver-tc* became
+*sqlserver*.
