What's Changed

Notable changes from previous release candidates (1.15.0-rc1, 1.15.0-rc2) are called out in these release notes. If migrating from 1.14.3, please see the RC release notes for other changes.

🚀 Features & Enhancements

• 🎉 Image substitution (#3102) @rnorth

  This change introduces a mechanism for programmatic image name substitution, as one of a number of mitigations for Docker Hub image pull rate limiting. For more information, please see the documentation.

• 🥳 Add GCloud module for Google Cloud Datastore, Firestore, PubSub, and Spanner emulators (#2690) @eddumelendez

  For more information, please check out the documentation for this module!

Included in 1.15.0-rc2

• Add image compatibility checks (#3021) @rnorth
  The majority of modules make assumptions about the container image being used - for example, port numbers, expected log lines, etc. When asking users to provide their own images with modules, it is potentially confusing if the provided image diverges from the original 'vendor-provided' image that the module was built to support.

  This change is intended to ensure that, if the user provides their own image that is not the same as the vendor-provided one, they are given adequate warning and forced to signal that this is intentional.

  For example:

  • new KafkaContainer(DockerImageName.parse("confluentinc/cp-kafka:any")) will just work, because confluentinc/cp-kafka matches the image name that KafkaContainer was designed to work with
  • but new KafkaContainer(DockerImageName.parse("some-other-kafka")) will not work immediately, because some-other-kafka may be an entirely divergent image from confluentinc/cp-kafka. In this case, the user would be prompted to add .asCompatibleSubstituteFor("confluentinc/cp-kafka") which tells Testcontainers that this is a conscious decision

  This PR adds to DockerImageName:

  • asCompatibleSubstituteFor(DockerImageName) and asCompatibleSubstituteFor(String) methods which may be used to claim compatibility with a vendor-provided image
  • isCompatibleWith(DockerImageName) and assertCompatibleWith(DockerImageName) methods which can be used by Testcontainers to check that the provided image is compatible with the expected vendor-provided image

Included in 1.15.0-rc1

• Add a rootless Docker strategy (#2985) @bsideup. This allows Testcontainers to be used with Docker's rootless mode. All Testcontainers' features and modules are compatible with Docker rootless mode, but we would appreciate feedback on unidentified edge cases.

• Deprecate ambiguous constructors (#2839) @rnorth. This change affects the majority of constructors for container classes. This is intended to encourage users to specify an exact docker image and tag for dependencies, rather than relying on a (potentially outdated) default image chosen by Testcontainers.

  • new XyzContainer()-style and new XyzContainer(String)-style constructors are deprecated throughout, in favour of a strongly typed new XyzContainer(DockerImageName)-style constructor.
  • Users should identify an appropriate Docker image for their test dependencies, and use as follows: new XyzContainer( DockerImageName.parse( "the/image:tag" ) ).
  • We expect to make some further improvements in this area before the final 1.15.0 release.

• Un-shade docker-java-api (#2882) @bsideup. This change follows some significant refactoring of the docker-java library, and should resolve various issues associated with shading of dependencies.

• New optional transport based on Apache HttpClient5. This is a very promising transport that most probably will become the default in future versions of Testcontainers. You can give it a try by putting transport.type = httpclient5 to $HOME/.testcontainers.properties.

⚠️ Breaking API changes

Included in 1.15.0-rc1

While we expect that the vast majority of users will notice no difference, these changes can be considered breaking, so warrant special mention:

• Un-shade docker-java-api (#2882) @bsideup
• Remove deprecated implicit network in KafkaContainer (#2932) @bsideup
• Clean up deprecated methods (#2835) @bsideup
• Migrate postgis image to the postgis/postgis docker hub repo. (#2797) @Sanych

Other improvements

• Refactor TestcontainersConfiguration to allow config by env var (#3411) @rnorth
• Elasticsearch: Add withPassword(String) method for secure access (#2321) @dadoonet
• Vault: add a fluent API for configuring Vault's logging level (#2231) @fullkomnun
• Add gcloud endpoint accessors (#3344) @rnorth
• docker-machine: get full remote daemon URL, to allow for use of custom daemon port (#2769) (#3237) @vcvitaly
• Allow users to specify a MongoDB database name (#2980) @silaev
• Presto: Bump default Presto version (used in deprecated constructor and unversioned JDBC URL) from 329 to 344 (#3312) @findepi
• Reduce severity of warning for failed auth config lookups (fixes #1399) (#3353) @DevilzOwn
• When an image version is not specified, use latest as the default tag (#3313) @rnorth
• Don't display a stack trace in the logs when .testcontainers.properties is not found (#2293) @rishumehrotra

🐛 Bug Fixes

• Fix use of HostPortWaitStrategy with Postgres container (fixes #3382) (#3403) @pawellozinski
• Support Confluent Platform 6 in Kafka (#3293) @bsideup
• Add support for MongoDB 4.4 (#3083) @kiview
• Remove potential NullPointerException when trying to log an error in VNC recorder (#3408) @codefiddler

📖 Documentation

• Correct documentation for ryuk image (#3383) @ae-govau
• Latest kafka container 5.4.3 (#3402) @artamonovkirill
• Fix a small typo in documentation (#3349) @dadoonet
• Update image references in Localstack module docs (#3076) @artamonovkirill
• Elasticsearch: Add test and documentation for secured cluster, bump default Elasticsearch version (deprecated constructor) from 6.4.1 to 7.9.2 (#2320) @dadoonet
• Increase memory limits used in example (#3340) @rnorth

🧹 Housekeeping

• Bump Python mkdocs tool dependency to address CVE-2019-10906 (#3379) @artamonovkirill
• Update sponsors (#3410) @rnorth
• Latest kafka container 5.4.3 (#3402) @artamonovkirill
• Update tests to use emulators image (#3406) @eddumelendez
• Change image used for test to avoid image name cache preventing proper pull (#3378) @rnorth
• Fix remote gradle cache 400 InvalidArgument error (#3346) @rnorth
• Use a lighter weight image for MultiplePortsExposedTest (#3343) @rnorth
• Remove GitHub Actions cache restore keys (#3342) @rnorth
• Increase memory limits used in example (#3340) @rnorth
• Upgrade mkdocs-codeinclude-plugin (#3354) @rnorth
• Always continue on error for examples CI (#3339) @rnorth
• Add workflow for Update Gradle Wrapper Action. (#3297) @cristiangreco

📦 Dependency updates