Testcontainers for Java: Add showcase examples for different scenarios

.github/dependabot.yml

@@ -35,3 +35,8 @@ updates:
     package-ecosystem: "bundler"
     schedule:
       interval: "monthly"
+
+  - directory: "/testing/testcontainers/java"
+    package-ecosystem: "gradle"
+    schedule:
+      interval: "monthly"

.github/workflows/testcontainers-java.yml

@@ -0,0 +1,47 @@
+name: Testcontainers for Java
+on:
+
+  pull_request:
+    branches: [ main ]
+    paths:
+    - '.github/workflows/testcontainers-java.yml'
+    - 'testing/testcontainers/java/**'
+  push:
+    branches: [ main ]
+    paths:
+    - '.github/workflows/testcontainers-java.yml'
+    - 'testing/testcontainers/java/**'
+
+  # Allow job to be triggered manually.
+  workflow_dispatch:
+
+# Cancel in-progress jobs when pushing to the same branch.
+concurrency:
+  cancel-in-progress: true
+  group: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  test:
+    name: "CrateDB: ${{ matrix.cratedb-version }}
+     on ${{ matrix.os }}"
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ "ubuntu-latest" ]
+
+    steps:
+
+      - name: Acquire sources
+        uses: actions/checkout@v3
+
+      - name: Setup Java
+        uses: actions/setup-java@v3
+        with:
+          distribution: "temurin"
+          java-version: "17"
+          cache: "gradle"
+
+      - name: Run software tests
+        run: |
+          cd testing/testcontainers/java
+          ./gradlew check

README.rst

@@ -26,5 +26,8 @@ Layout
   CrateDB is part of a larger software stack. Those resources may also be used
   within "reference architecture" types of documentation.
 
+- The ``testing`` folder contains reference implementations about how to use
+  different kinds of test layers for testing your applications with CrateDB.
+
 
 .. _CrateDB: https://github.com/crate/crate

testing/testcontainers/java/.gitignore

@@ -0,0 +1,8 @@
+.gradle/
+.idea
+*.iws
+*.iml
+*.ipr
+build/
+out/
+target/

testing/testcontainers/java/.java-version

@@ -0,0 +1 @@
+17

testing/testcontainers/java/README.rst

@@ -0,0 +1,89 @@
+#######################
+Testcontainers for Java
+#######################
+
+*How to run integration tests of Java applications with CrateDB.*
+
+
+*****
+About
+*****
+
+Introduction
+============
+
+`Testcontainers for Java`_ is a Java library that supports JUnit tests,
+providing lightweight, throwaway instances of common databases suitable
+for integration testing scenarios.
+
+The `Testcontainers CrateDB Module`_ will provide your application test
+framework with a single-node `CrateDB`_ instance. You will be able to choose
+the `CrateDB OCI image`_ variant by version, or by selecting the ``nightly``
+release.
+
+What's inside
+=============
+
+This directory includes different canonical examples how to use those
+components within test harnesses of custom applications using `CrateDB`_.
+Currently, all test cases are based on JUnit 4. This is an enumeration
+of examples you can explore here:
+
+- ``TestClassScope``: Class-scoped testcontainer instance with JUnit 4 @Rule/@ClassRule integration.
+- ``TestFunctionScope``: Function-scoped testcontainer instance with JUnit 4 @Rule/@ClassRule integration.
+- ``TestJdbcUrlScheme``: Database containers launched via Testcontainers "TC" JDBC URL scheme.
+- ``TestManual``: Function-scoped testcontainer instance with manual setup/teardown.
+- ``TestManualWithLegacyCrateJdbcDriver``:
+  Function-scoped testcontainer instance with manual setup/teardown, using a custom
+  ``CrateDBContainer``, which uses the `legacy CrateDB JDBC driver`_.
+- ``TestSharedSingleton`` [1]:
+  Testcontainer instance shared across multiple test classes, implemented using the Singleton pattern.
+- ``TestSharedSingletonEnvironmentVersion``:
+  Testcontainer instance honoring the ``CRATEDB_VERSION`` environment variable, suitable
+  for running a test matrix on different versions of CrateDB, shared across multiple test
+  classes.
+
+[1]: Sometimes, it might be useful to define a container that is only started once for
+several test classes. There is no special support for this use case provided by
+the Testcontainers extension. Instead, this can be implemented using the Singleton
+pattern. See also `Testcontainers » Manual container lifecycle control » Singleton
+containers`_.
+
+
+*****
+Usage
+*****
+
+1. Make sure Java 17 is installed.
+2. Invoke software tests, using `Testcontainers for Java`_. It should work out
+   of the box::
+
+    # Run all tests.
+    ./gradlew test
+
+    # Run individual tests.
+    ./gradlew test --tests TestFunctionScope
+
+    # Run test case showing how to select CrateDB version per environment variable.
+    export CRATEDB_VERSION=5.2.3
+    export CRATEDB_VERSION=nightly
+    ./gradlew test --tests TestSharedSingletonMatrix
+
+3. Invoke example application::
+
+    # Start CrateDB.
+    docker run -it --rm --publish=4200:4200 --publish=5432:5432 \
+      crate:latest -Cdiscovery.type=single-node
+
+    # Run example program, using both the CrateDB legacy
+    # JDBC driver, and the vanilla PostgreSQL JDBC driver.
+    ./gradlew run --args="jdbc:crate://localhost:5432/"
+    ./gradlew run --args="jdbc:postgresql://localhost:5432/"
+
+
+.. _CrateDB: https://github.com/crate/crate
+.. _CrateDB OCI image: https://hub.docker.com/_/crate
+.. _legacy CrateDB JDBC driver: https://crate.io/docs/jdbc/
+.. _Testcontainers for Java: https://github.com/testcontainers/testcontainers-java
+.. _Testcontainers CrateDB Module: https://www.testcontainers.org/modules/databases/cratedb/
+.. _Testcontainers » Manual container lifecycle control » Singleton containers: https://www.testcontainers.org/test_framework_integration/manual_lifecycle_control/#singleton-containers

testing/testcontainers/java/build.gradle

@@ -0,0 +1,67 @@
+/**
+ * An example application for demonstrating "Testcontainers for Java" with CrateDB and the PostgreSQL JDBC driver.
+ */
+
+buildscript {
+    repositories {
+        mavenCentral()
+    }
+}
+
+plugins {
+    id 'application'
+    id 'idea'
+    id 'java'
+}
+
+repositories {
+    mavenCentral()
+    mavenLocal()
+}
+
+dependencies {
+    implementation 'org.postgresql:postgresql:42.6.0'
+    implementation 'io.crate:crate-jdbc:2.6.0'
+    implementation 'org.slf4j:slf4j-api:2.0.7'
+    implementation 'org.slf4j:slf4j-simple:2.0.7'
+    testImplementation 'junit:junit:4.13.2'
+    testImplementation "org.assertj:assertj-core:3.23.1"
+    testImplementation 'org.testcontainers:testcontainers:1.18.0'
+    testImplementation 'org.testcontainers:cratedb:1.18.0'
+    testImplementation 'org.testcontainers:postgresql:1.18.0'
+}
+
+java {
+    toolchain {
+        languageVersion = JavaLanguageVersion.of(17)
+    }
+}
+
+jar {
+    archiveBaseName = 'cratedb-example-testcontainers-java'
+    archiveVersion = '0.0.1-SNAPSHOT'
+}
+
+sourceSets {
+    main {
+        java.srcDirs += [
+            "src/generated/java",
+            "src/main/java",
+        ]
+    }
+}
+
+test {
+    dependsOn 'cleanTest'
+}
+
+application {
+    mainClass = 'io.crate.example.testing.Application'
+}
+
+ext.javaMainClass = "io.crate.example.testing.Application"
+
+
+idea.module.inheritOutputDirs = true
+processResources.destinationDir = compileJava.destinationDir
+compileJava.dependsOn processResources

testing/testcontainers/java/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,5 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-7.6-bin.zip
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists