NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
npm · #4531 most downloaded on npm
Testcontainers is a NodeJS library that supports tests, providing lightweight, throwaway instances of common databases, Selenium web browsers, or anything else that can run in a Docker container
Last release 6 days ago
28 Sep 2026
Ships fairly regularly
a new release about every 3 weeks
Nearly every release is documented
notes for 60 of the last 60 stable releases
1 version withdrawn
withdrawn after publishing
9 years old
299 releases · first in 2018
Add InfluxDB module @JonnasFigueiredo
One column per quarter.
Add MongoDB Atlas Local support @jbl428
Fix container exec output truncation @cristianrgreco
Downgrade archiver to restore Jest CJS compatibility @cristianrgreco
Reset stateful regex log waits between matches @cristianrgreco
Fix Podman image healthcheck detection @cristianrgreco
Node 20 is EOL. Minimum engine requirement is now >= 22.22 , matching the constraints from our dependencies.
Node 20 is EOL. Minimum engine requirement is now >= 22.22, matching the constraints from our dependencies.
Previously, when no wait strategy was configured, Testcontainers defaulted to Wait.forListeningPorts().
The new default wait strategy uses a Docker healthcheck when one is configured on the container image or service, falling back to Wait.forListeningPorts() when no healthcheck is available.
To keep the previous behaviour, configure Wait.forListeningPorts() explicitly:
import { DockerComposeEnvironment, GenericContainer, Wait } from "testcontainers";
// Container: opt back into the previous default of waiting for listening ports
const container = await new GenericContainer("my-image:latest")
.withExposedPorts(8080)
.withWaitStrategy(Wait.forListeningPorts())
.start();
// Compose: apply the previous default to all services
const environment = await new DockerComposeEnvironment(composeFilePath, "docker-compose.yml")
.withDefaultWaitStrategy(Wait.forListeningPorts())
.up();
// Compose: or apply it to a specific compose container
const environment = await new DockerComposeEnvironment(composeFilePath, "docker-compose.yml")
.withWaitStrategy("api-1", Wait.forListeningPorts())
.up();RYUK_CONTAINER_IMAGE lazily so dotenv / other runtime overrides work @dvirarad (#1323)/tmp for Kafka startup script @cristianrgreco (#1302)Add auto cleanup control for containers and compose environments @cristianrgreco
repository.url in package.json @cristianrgreco (#1273)Add Oracle Free module @collinmurd
Add SSL support for postgres containers @cristianrgreco
status and Action fields @cristianrgreco (#1230)Add Azure Service Bus module @UnstoppableMango
identityToken when present in auths @jwhite-sds (#1197)Add support for disabling TLS in OpenSearch module @rafaeltab
Add support for identity token authentication @cristianrgreco
Fix Redis container to accept command override @ziggornif
Add configuration for TESTCONTAINERS_RYUK_RECONNECTION_TIMEOUT @abendi
TESTCONTAINERS_RYUK_RECONNECTION_TIMEOUT @abendi (#1168)Add missing await to cassandra test @cristianrgreco
await to cassandra test @cristianrgreco (#1154)Return empty registry credentials when none found @cristianrgreco
Bump ryuk image version to 0.14 @digital88
Skip checking registry on credential helper list @karol-bochenski
Fix redpanda missing redpanda.yaml.hbs @cristianrgreco
redpanda.yaml.hbs @cristianrgreco (#1105)Implement support for specifying the protocol when exposing ports @technocidal
Add support for MongoDBContainer credentials @digital88
Bump the dependencies group across 5 directories with 5 updates @[dependabot[bot]]
Fix for Gcloud module eagerly importing @google-cloud/spanner @cristianrgreco
Implement AsyncDisposable to support TS 5.2's using @cristianrgreco
AsyncDisposable to support TS 5.2's using @cristianrgreco (#1080)Fix undici response parsing when status code says no content but there is content @cristianrgreco
Add getSecureUrl in mockserver's module @botflux
getSecureUrl in mockserver's module @botflux (#1059)Add support for custom client options in DockerComposeEnvironment @Dyskal
esdb to kurrentdb @botflux (#1051)Increase timeout for waiting for host port bindings @cristianrgreco
Handle case where container port does not exist in inspect result @cristianrgreco
Retry inspecting container until exposed ports are mapped @cristianrgreco
1. Minimum Node engine requirement set to 20.
1. Minimum Node engine requirement set to 20.
2. Default module images have been removed.
Previously:
await new PostgreSqlContainer().start();
Now:
await new PostgreSqlContainer("postgres:13.3-alpine").start();
For convenience, here is a table of all the previous default values, which you could just copy/paste to get back working again, but have a think about which version you actually need. Some of these are quite old and need to be updated.
<details> <summary>Default module images</summary>
| Module | Image |
|---|---|
| arangodb | arangodb:3.10.0 |
| azurecosmosdb | mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-EN20250228 |
| azurite | mcr.microsoft.com/azure-storage/azurite:3.33.0 |
| cassandra | cassandra:5.0.2 |
| chromadb | chromadb/chroma:0.6.3 |
| clickhouse | clickhouse/clickhouse-server:25.3-alpine |
| cockroachdb | cockroachdb/cockroach:v24.3.5 |
| couchbase | couchbase/server:6.5.1 |
| elasticsearch | elasticsearch:7.17.7 |
| etcd | quay.io/coreos/etcd:v3.6.0 |
| eventstoredb | eventstore/eventstore:24.10 |
| gcloud | gcr.io/google.com/cloudsdktool/cloud-sdk:517.0.0-emulators |
| hivemq | hivemq/hivemq-ce:2023.5 |
| k3s | rancher/k3s:v1.31.2-k3s1 |
| kafka | confluentinc/cp-kafka:7.2.2 |
| localstack | localstack/localstack:2.2.0 |
| mariadb | mariadb:11.5.2 |
| minio | minio/minio:RELEASE.2024-12-13T22-19-12Z |
| mockserver | mockserver/mockserver:5.15.0 |
| mongodb | mongo:4.0.1 |
| mssqlserver | mcr.microsoft.com/mssql/server:2022-CU13-ubuntu-22.04 |
| mysql | mysql:8.0.31 |
| nats | nats:2.8.4-alpine |
| neo4j | neo4j:4.4.12 |
| ollama | ollama/ollama:0.1.44 |
| postgresql | postgres:13.3-alpine |
| qdrant | qdrant/qdrant:v1.13.4 |
| rabbitmq | rabbitmq:3.12.11-management-alpine |
| redis | redis:7.2 |
| redpanda | docker.redpanda.com/redpandadata/redpanda:v23.3.10 |
| scylladb | scylladb/scylla:6.2.0 |
| selenium | selenium/standalone-chrome:112.0 |
| toxiproxy | ghcr.io/shopify/toxiproxy:2.11.0 |
| valkey | valkey/valkey:8.0 |
| weaviate | semitechnologies/weaviate:1.24.5 |
</details>
3. Dropped support for Docker Compose v1 (EOL July 2023).
4. Docker compose version no longer available via ComposeClient
const { compose } = await getContainerRuntimeClient();
compose.version; // no longer available
5. Container stop timeouts have changed from seconds to milliseconds
Previously:
await container.stop({ timeout: 10 }); // 10 seconds
Now:
await container.stop({ timeout: 10_000 }); // 10 seconds
6. EventStoreDB has been renamed to KurrentDB
Previously:
import { EventStoreDBContainer } from "@testcontainers/eventstoredb";
new EventStoreDBContainer("eventstore/eventstore:24.10").start();
Now:
import { KurrentDbContainer } from "@testcontainers/kurrentdb";
new KurrentDbContainer("kurrentplatform/kurrentdb:25.0").start();
RandomUniquePortGenerator replaced by RandomPortGeneratorNATS: Add codec, scratch compatibility @joebowbeer
Bump undici from 5.28.5 to 5.29.0 @dependabot
Support Neo4j plugins other than Apoc @stscoundrel
Wait.forListeningPorts to Cassandra/Cockroach/Postgres modules @nidomiro (#998)Allow overriding default compose wait strategy @jalaziz
Revert "Simplify log-wait-strategy (#977)" @cristianrgreco
Update wait-strategies.md @jonathanagustin
dockerode dependency to 4.0.5 @estiller (#980)Add SocatContainer @eddumelendez
Add snapshot support to postgres module @Nikola-Milovic
Improve PortCheck logging for distroless images @digital88
TESTCONTAINERS_RYUK_VERBOSE setting @digital88 (#941)withAutoRemove #905 @digital88 (#939)Add ability to set command flags to Gcloud emulators @digital88
LAMBDA_DOCKER_FLAGS @florian-nguyen (#935)Add support for container commit @smcroskey
Add CockroachDB module @leourbina
Enable/disable container reuse with an environment variable @juliette-derancourt
Add support for Docker credential providers which do not implement list command @glebbash
Fix EventstoreDB publish config
Add EventStoreDB module @botflux
isRoot parameter to executeQuery @jeengbe (#882)Remove explicit port binding in Azurite container @ChlorUpload
stdout and stderr fields to container exec result @chungjung-d (#874)Add BigQueryEmulatorContainer to gcloud module @oskarwidmark
Add support for reusing stopped containers @cbrevik
Fix for Docker registry passwords that contain a colon @joshystuart
Fix LocalStack container hostname resolution @joebowbeer
Add autoUpdateExternalUrl to CloudStorageEmulatorContainer @alecmev
autoUpdateExternalUrl to CloudStorageEmulatorContainer @alecmev (#825)Log docker daemon labels @eddumelendez
CloudStorageEmulatorContainer and PubSubEmulatorContainer to gcloud module @weyert (#805)directConnection @BradLewis (#821)withFiles/directories/content @danmondra (#809)Make HealthCheckWaitStrategy event based @cristianrgreco
HealthCheckWaitStrategy event based @cristianrgreco (#789)DatastoreEmulatorContainer to gcloud module @oskarwidmark (#782)node-fetch with Node.js' native fetch @Kurre (#777)Fix fetching registry credentials when using Gcloud cred helper @HiranmayaGundu
Docker runtimes may be undefined @cristianrgreco
Log stacktrace when container runtime strategy throws @cristianrgreco
Add logs around resolving a container runtime @cristianrgreco
Your coding agent can read these notes before it upgrades. Set up the MCP server →