External Integration Tests

External Integration Tests

External integration tests run ExternalIT against a database reachable through an ordinary JDBC URL. They are intended for users and contributors who want to check this library against a real server/driver pair outside the in-memory test suite.

What ExternalIT Does

AbstractExternalIT currently exercises selected top-level metadata methods, including catalogs, schemas, tables, columns, attributes, procedures, procedure columns, functions, function columns, pseudo columns, super tables, super types, table privileges, table types, type info, UDTs, client info properties, SQL keywords, and metadata function lists.

Each successful sweep writes target/{prefix}-{name}.xml and target/{prefix}-{name}.json. After a connection and Context are created, SQLException from individual metadata calls is logged and does not fail the whole external test class.

The filename prefix is derived from database product/version and JDBC driver name/version. Avoid Maven's clean phase when you want to keep previously generated artifacts under target/.

Profiles

External tests are enabled by combining failsafe, the base external profile, and one database-specific external profile.

Profile	Test sources	driver.groupId default	driver.artifactId default	driver.version default
external	src/test/java-external
external-mariadb	src/test/java-external-mariadb	org.mariadb.jdbc	mariadb-java-client	${version.mariadb-java-client}
external-mysql	src/test/java-external-mysql	com.mysql	mysql-connector-j	${version.mysql-connector-j}
external-oracle	src/test/java-external-oracle	com.oracle.database.jdbc	ojdbc11	${version.com.oracle.ojdbc}
external-postgresql	src/test/java-external-postgresql	org.postgresql	postgresql	${version.postgresql}

The base external profile provides the shared abstract external test. Each database-specific profile provides a concrete ExternalIT class and JDBC driver dependency.

The driver coordinates are Maven properties and may be overridden when needed:

Property	Meaning
driver.groupId	JDBC driver dependency group id.
driver.artifactId	JDBC driver dependency artifact id.
driver.version	JDBC driver dependency version.

For example, run the MySQL profile with a different Connector/J version:

./mvnw \
  -Pfailsafe,external,external-mysql \
  -Ddriver.version='{driver-version}' \
  -Dit.test=ExternalIT \
  -Durl='jdbc:mysql://{address}:{port}/{database}?...' \
  -Duser='{user}' \
  -Dpassword='{password}' \
  test-compile failsafe:integration-test

For example, run the MySQL profile with the legacy Connector/J coordinates:

./mvnw \
  -Pfailsafe,external,external-mysql \
  -Ddriver.groupId='mysql' \
  -Ddriver.artifactId='mysql-connector-java' \
  -Ddriver.version='8.0.33' \
  -Dit.test=ExternalIT \
  -Durl='jdbc:mysql://{address}:{port}/{database}?...' \
  -Duser='{user}' \
  -Dpassword='{password}' \
  test-compile failsafe:integration-test

Oracle JDBC driver coordinates have varied by driver generation and Java baseline. Override driver.groupId, driver.artifactId, or driver.version when testing a different Oracle driver line.

Required System Properties

ExternalIT is enabled only when these properties are non-blank:

Property	Meaning
url	JDBC URL.
user	JDBC user.
password	JDBC password.

Running Against A MariaDB Server

Use the external-mariadb profile and pass JDBC connection properties.

./mvnw \
  -Pfailsafe,external,external-mariadb \
  -Dit.test=ExternalIT \
  -Durl='jdbc:mariadb://{address}:{port}/{database}' \
  -Duser='{user}' \
  -Dpassword='{password}' \
  test-compile failsafe:integration-test

Running Against A MySQL Server

Use the external-mysql profile and pass JDBC connection properties.

./mvnw \
  -Pfailsafe,external,external-mysql \
  -Dit.test=ExternalIT \
  -Durl='jdbc:mysql://{address}:{port}/{database}?...' \
  -Duser='{user}' \
  -Dpassword='{password}' \
  test-compile failsafe:integration-test

Running Against An Oracle Server

Use the external-oracle profile and pass JDBC connection properties.

./mvnw \
  -Pfailsafe,external,external-oracle \
  -Dit.test=ExternalIT \
  -Durl='jdbc:oracle:thin:@//{address}:{port}/{service}' \
  -Duser='{user}' \
  -Dpassword='{password}' \
  test-compile failsafe:integration-test

For example, run the Oracle profile with another OJDBC artifact/version:

./mvnw \
  -Pfailsafe,external,external-oracle \
  -Ddriver.artifactId='{ojdbc-artifact}' \
  -Ddriver.version='{driver-version}' \
  -Dit.test=ExternalIT \
  -Durl='jdbc:oracle:thin:@//{address}:{port}/{service}' \
  -Duser='{user}' \
  -Dpassword='{password}' \
  test-compile failsafe:integration-test

Running Against A PostgreSQL Server

Use the external-postgresql profile and pass JDBC connection properties.

./mvnw \
  -Pfailsafe,external,external-postgresql \
  -Dit.test=ExternalIT \
  -Durl='jdbc:postgresql://{address}:{port}/{database}' \
  -Duser='{user}' \
  -Dpassword='{password}' \
  test-compile failsafe:integration-test