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 with one external profile.

Profile	Test sources	driver.groupId default	driver.artifactId default	driver.version default
external-mariadb	src/test/java-external-mariadb	org.mariadb.jdbc	mariadb-java-client	${version.mariadb-java-client}
external-mysql5	src/test/java-external-mysql5	mysql	mysql-connector-java	8.0.33
external-mysql8	src/test/java-external-mysql8	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}

Each profile provides a concrete ExternalIT class extending the shared abstract external test.

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 8 profile with a different Connector/J version:

./mvnw \
  -Pfailsafe,external-mysql8 \
  -Ddriver.version='{driver-version}' \
  -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 An Oracle Server

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

./mvnw \
  -Pfailsafe,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-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 MariaDB Server

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

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

Running Against A MySQL 8 Server

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

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

Running Against A MySQL 5 Server

Use the external-mysql5 profile for the legacy MySQL profile.

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