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:

Test method	Metadata call	Artifacts
catalogs()	Context.getCatalogs()	target/{prefix}-catalogs.xml, target/{prefix}-catalogs.json
schemas()	Context.getSchemas() or Context.getSchemas(catalog, null)	target/{prefix}-schemas.xml, target/{prefix}-schemas.json
tables()	Context.getTables(catalog, null, "%", null)	target/{prefix}-tables.xml, target/{prefix}-tables.json

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}

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

Required System Properties

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

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

Optional:

Property	Meaning
catalog	Catalog/database name used by catalog-scoped metadata calls where supported.

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