andersswanson.dev

Polyglot, automated ORDS tests with Testcontainers

Polyglot ORDS testcontainers

Did you know you can locally test Oracle REST Data Services (ORDS) with free Oracle AI Database resources?

If you rely on mock servers (or don’t run automated tests at all!), you’re dealing with a thin layer of comfort. Using container-driven ORDS tests can prove your app starts, connects to ORDS, and uses database APIs like the MongoDB wire-compatibility API. All with a local stack your test created.

Jump to the language-specific resources if you’d like to skip the article:

I talked about this from a Java perspective in Test ORDS locally with Testcontainers and Oracle AI Database Free – Now, we’re expanding that coverage to Python, JavaScript/TypeScript, and Go.

It’s the same idea, but implemented in 4 different languages. You can adapt this idea to any automated ORDS testing for your applications.

How it works : local ORDS tests

Each version does the same work in the style of its test ecosystem:

  1. Start an Oracle AI Database Free container on a Docker network.
  2. Create two test users in freepdb1: one for the ORDS database API and one for the MongoDB API path.
  3. Start the ORDS container on the same network.
  4. Give ORDS the database connection string and admin password through CONN_STRING and ORACLE_PWD.
  5. Enable each schema with ORDS.ENABLE_SCHEMA.
  6. Run real assertions against ORDS over HTTP and the MongoDB-compatible API -> in your app, do any ORDS-specific testing here.
  7. Tear everything down.
Diagram explaining the functions of ORDS tests, showing connections to HTTP readiness, MongoDB CRUD operations, DB API versioning, and cleanup processes.

The the test owns the whole lifecycle, including schema setup and ORDS readiness.

Java

Code:

Prerequisites:

  • Java 21+
  • Maven
  • Docker-compatible container runtime
  • Access to container-registry.oracle.com/database/ords:latest

Run it from the repo root:

mvn -pl ords-testcontainers test

The test uses JUnit 5 with Testcontainers. It starts Oracle AI Database Free, runs ords_init.sql, starts ORDS, then checks three real paths: the ORDS home endpoint, the ORDS database API database/version endpoint, and MongoDB-compatible CRUD.

To use it in your own Java tests, add the same Testcontainers, JUnit 5, Oracle AI Database Free, and MongoDB driver dependencies from the sample pom.xml, then reuse the OrdsContainer helper:

private static final OrdsContainer ordsContainer = new OrdsContainer()
        .withNetwork(NETWORK)
        .withDatabaseConnectionString(DATABASE_CONNECTION)
        .withOraclePassword(ADMIN_PASSWORD)
        .withSchema(DB_API_ADMIN_USERNAME, DB_API_ADMIN_PASSWORD, SCHEMA_CONNECTION)
        .withSchema(MONGO_USERNAME, MONGO_PASSWORD, SCHEMA_CONNECTION);

The schema enablement belongs in the helper,:

String command = String.format(
        "printf 'WHENEVER SQLERROR EXIT SQL.SQLCODE\nEXECUTE ORDS.ENABLE_SCHEMA;\nEXIT;\n' | sql -s %s",
        shellQuote(schema.username() + "/" + schema.password() + "@" + schema.connectDescriptor())
);

Python

Code:

Prerequisites:

  • Python 3.13+
  • Poetry
  • Docker-compatible container runtime
  • Access to container-registry.oracle.com/database/ords:latest

Run it from the Python module:

cd python-oracle
poetry install
poetry run python -m unittest tests.test_ords_container -v

The test uses setUpClass to create the network, start Oracle AI Database Free, initialize users, start ORDS, and then run the HTTP and MongoDB assertions.

To use it in your own Python tests, bring over OrdsContainer, install testcontainers and pymongo, and start it beside your database container:

cls.ords_container = OrdsContainer(network=cls.network) \
    .with_database_connection_string(DATABASE_CONNECTION) \
    .with_oracle_password(ADMIN_PASSWORD) \
    .with_schema(DB_API_ADMIN_USERNAME, DB_API_ADMIN_PASSWORD, SCHEMA_CONNECTION) \
    .with_schema(MONGO_USERNAME, MONGO_PASSWORD, SCHEMA_CONNECTION)
cls.ords_container.start()

The important Python-specific detail is cleanup. ORDS startup can fail before tearDownClass runs, so the sample cleans up in the setUpClass failure path:

try:
    cls.oracle_container.start()
    cls._initialize_database()
    cls.ords_container.start()
except Exception:
    cls._cleanup_containers()
    raise

TypeScript

Code:

Prerequisites:

  • Current Node.js runtime
  • npm
  • Docker-compatible container runtime
  • Access to container-registry.oracle.com/database/ords:latest

Run it from the TypeScript module:

cd typescript
npm install
npm run testcontainers-ords-example

To use it in your own JavaScript/TypeScript tests, import OrdsContainer, put it on the same Network as Oracle AI Database Free, and configure the database connection and schemas before start():

ordsContainer = await new OrdsContainer()
    .withNetwork(network)
    .withDatabaseConnectionString(DATABASE_CONNECTION)
    .withOraclePassword(ADMIN_PASSWORD)
    .withSchema(DB_API_ADMIN_USERNAME, DB_API_ADMIN_PASSWORD, SCHEMA_CONNECTION)
    .withSchema(MONGO_USERNAME, MONGO_PASSWORD, SCHEMA_CONNECTION)
    .start();

Go

Code:

Prerequisites:

  • Go 1.26.3+
  • Docker-compatible container runtime
  • Access to container-registry.oracle.com/database/ords:latest

Run it from the Go module:

cd golang
go test ./testcontainers -run TestOrdsContainerIntegration

To use it in your own Go tests, call RunOrdsContainer with the functional options your test needs:

ordsContainer, err := RunOrdsContainer(
    ctx,
    WithOrdsDatabaseConnectionString(ordsDatabaseConnection),
    WithOrdsOraclePassword(ordsAdminPassword),
    WithOrdsSchema(dbAPIAdminUsername, dbAPIAdminPassword, ordsSchemaConnection),
    WithOrdsSchema(mongoUsername, mongoPassword, ordsSchemaConnection),
    WithOrdsContainerCustomizers(tcnetwork.WithNetwork(nil, nw)),
)
require.NoError(t, err)

The Go helper carries the same reusable pieces as the TypeScript helper: exposed ORDS ports, HTTP readiness, required CONN_STRING and ORACLE_PWD settings, schema enablement, and _JAVA_OPTIONS=-Xms128m -Xmx768m for predictable local startup.

Why this is awesome

This pattern is great for:

  • Building code that calls ORDS database APIs.
  • Testing MongoDB-compatible access through ORDS.
  • Replacing shared local setup instructions with repeatable test setup.
  • Debugging ORDS startup or schema enablement as code instead of as a manual checklist.

It’s sufficient to make ORDS part of a normal development loop. A Java service can use JUnit. A Python tool can use unittest. A Node service can use Vitest. A Go service can use go test.

You get faster, automated feedback on your ORDS implementations, with minimal local overhead.

FAQ

  • You need a Docker-compatible runtime and access to the ORDS image at container-registry.oracle.com/database/ords:latest.
  • The MongoDB API tests use TLS settings appropriate for local containers with self-signed certificates. The Java test calls this out directly: trusting all certificates is test-only behavior, not production guidance.
  • The Go sample directory also documents Oracle client library requirements for its broader database container tests. If you run the whole package instead of the focused ORDS test, account for that local dependency.
  • Finally, keep an eye on container memory. The TypeScript and Go helpers set _JAVA_OPTIONS=-Xms128m -Xmx768m because local ORDS startup can fail under memory pressure. If you’re running a system with memory constraints, keep an eye on how much memory your container runtime is using.

References

Leave a Reply

Discover more from andersswanson.dev

Subscribe now to keep reading and get access to the full archive.

Continue reading