Skip to content

Oracle integration testing

The domain mappings define the intended application schema. The legacy application was not bootstrapped by its feature migrations: V1 assumes tables such as MAN_DRAFT already exist. Integration tests therefore install a reviewed, structure-only legacy prerequisite fixture before executing the real API migrations. Hibernate does not create or update the database.

Database initialization

The API test harness starts disposable Oracle Free and Redis containers. It installs these resources in order:

  1. db/test-bootstrap: legacy sequences, tables, indexes, foreign keys, synthetic reference parents and valid application triggers. Its separate TEST_BOOTSTRAP_HISTORY never marks application migrations as applied.
  2. db/migration: the unchanged existing migrations plus V4 domain reconciliation, using the normal flyway_schema_history table. Prerequisite installation checks that feature-owned tables and representative columns are absent before this step.
  3. db/test-views: valid local legacy views, installed after the feature columns and tables they can reference.

The fixture was derived from read-only metadata in the host cis-oracle-db, PDB ORCLPDB1, schema SGUSER, on 4 November 2026. It contains 173 legacy tables, 56 local views and 13 application triggers. It contains no application rows, passwords, grants, database links or application Flyway history. Source sequence and identity high-water marks are replaced with deterministic test values. Invalid and remote dependencies are excluded. Synthetic parent rows exist only to satisfy the real migration seeds and foreign keys.

db/test-bootstrap/manifest.json records the object scope, exclusions, feature-owned objects and SHA256 hashes of normalized UTF-8 resources. Fixtures are not a production baseline or a replacement for application migrations. Their scripts may be revised together because every test JVM creates a disposable database.

The host database is not used by tests and was not migrated during fixture derivation. The domain reconciliation migration must be deployed through the normal application migration process for shared environments.

Domain reconciliation

V4__reconcile_domain_schema.sql adds four mapped tables, 42 missing columns and three sequences. It preserves existing columns and rows. The source inventory originally attributed a collection join column to ROLES; that column belongs to SITEMAP_ROLE, so no ROLE_ID column is added to ROLES.

The live archive identifier triggers also replaced IDs that Hibernate had already allocated. V4 preserves supplied IDs while retaining sequence defaults for native inserts that omit an ID. This aligns stored identity with the domain sequence mappings. The regression test exercises both paths with transaction rollback.

DomainSchemaIntegrationTest compares explicit scalar and singular association column mappings and sequence generators from the running JPA metamodel with the migrated schema, including embedded IDs. It checks presence, not comprehensive datatype, default or constraint equivalence. Collection join columns are not treated as columns of their owner table. OracleSchemaMigrationIntegrationTest checks feature objects, preservation of a legacy sentinel record, actual V4 re-execution with an independent test history, sequence preservation and a second no-op application migration run.

Test isolation and lifecycle

The integration profile disables scheduled business jobs and uses loopback addresses for external transports. Redis is real and disposable. Authentication helpers apply the real JWT-to-domain-principal converter; dedicated security tests remain responsible for cryptographic token validation. Resource integration tests must not send real email or SMS; mock the transport or application service when testing those endpoints.

Oracle and Redis are manually managed JVM singletons. They are not simultaneously managed by the JUnit Testcontainers extension. Shutdown hooks stop them even when Bitbucket disables Ryuk, preventing database containers from accumulating across modules. Docker-free local runs skip the Oracle suites; TESTCONTAINERS_REQUIRED=true turns missing Docker into a CI failure.

API integration tests have a bounded heap and a small Spring context cache. Database slice tests use transactions; individual service and controller tests must provide their own valid fixtures and clean up writes. Do not rely on host business rows or test execution order. A startup failure must not be hidden by ddl-auto: update, disabling the integration task or marking migration history successful.

Commands and pipeline

Run from the repository root in PowerShell:

./gradlew.bat :cis-api:test
./gradlew.bat :cis-api:integrationTest
./gradlew.bat :cis-api:integrationTest --tests '*OracleSchemaMigrationIntegrationTest' --tests '*DomainSchemaIntegrationTest'
./gradlew.bat check --no-daemon

The API separates integration-tagged tests from unit tests. Auth and workflow retain their existing test tasks and now use a consistent singleton lifecycle. The BFF's class-managed Redis tests retain their own lifecycle. Bitbucket runs check, requires Testcontainers, disables Ryuk for the runner and publishes detailed test XML and HTML artifacts. Full exception output exposes the original Oracle error instead of only Spring context wrappers.

Refreshing the fixture

Use scripts/schema-baseline/inspect_oracle.py --export-ddl to collect metadata and structure to a task-local review directory. It is read-only. Review the inventory and domain gaps before using scripts/schema-baseline/export_test_fixture.py --inspection <review-directory> to derive test resources. The exporter supports --view-ddl and --trigger-ddl for reviewed offline exports. The live container is not required by CI; the resulting resources are checked in.

Review regenerated SQL, excluded objects and the manifest. Run migration, schema contract and integration tests against a fresh container. Never copy production data, credentials or history tables into the fixture. Never modify an already applied production migration to accommodate test setup.

CIS API test suites and CI

Tests share the standard cis-api/src/test/java source set. Use one execution category per test. Prefer a class-level JUnit @Tag.

Tag Gradle task Scope
unit :cis-api:test Isolated logic. Untagged legacy unit tests are included during migration.
slice :cis-api:sliceTest Spring MVC or persistence slices that run without Docker.
integration :cis-api:integrationTest Oracle-backed JPA slices and application integration with Oracle, Redis and local adapters.
contract :cis-api:contractTest API/client contracts with local stubs.
e2e :cis-api:e2eTest Full multi-service scenarios when provisioned.

Run ./gradlew :cis-api:jacocoTestReport for fast-suite coverage and ./gradlew :cis-api:integrationTest for Oracle integration coverage. Both reports publish HTML and XML under cis-api/build/reports/jacoco. JaCoCo exposes line, branch, method and class counters with package drill-down, including web.rest, service, persistence.repository, security and configuration and their subpackages.

Bitbucket runs fast verification on ordinary commits, adds Oracle integration for pull requests, and runs all module checks before releases. Schedule the nightly-verification custom pipeline in Bitbucket for nightly runs.