Skip to content

Home > @opengovsg/testcontainers

testcontainers package ​

A declarative wrapper over testcontainers for integration and e2e test setups: a zod-validated container config schema, setup/teardown over GenericContainer, Vitest context handoff, and Postgres/Redis presets.

Functions ​

FunctionDescription
getMappedPort(container, containerPort)Return the mapped host port for a container port. Throws if unmapped.
getPostgresConnectionString(container, options)

Build a Postgres connection string from container info. Credentials are read back from configuration.environment; database overrides the DB name (the confetti per-run randomUUID() pattern).

By default the URL targets the mapped **host** port, for connecting from the test process. Pass internal: true for the container-internal address (localhost:5432) needed by commands run *inside* the container, e.g. pg_dump/pg_restore via StartedTestContainer.exec.

getRedisUrl(container, options)Build a redis://host:port URL from container info. Defaults to the mapped host port; pass internal: true for the container-internal address (localhost:6379) used by commands run inside the container.
postgres(overrides)Postgres preset: postgres:latest on port 5432 with POSTGRES_DB=test/POSTGRES_USER=root/POSTGRES_PASSWORD=root, waiting on the port. Overrides shallow-merge; environment merges per-key.
redis(overrides)Redis preset: redis on port 6379, waiting on the port. databases starts the server with --databases n for per-worker logical-DB isolation (confetti uses 256).
setup(configurations, options)Start the given containers concurrently and return their connection info. Faithful port of confetti's common.ts setup, with the optional network moved into an options object.
teardown(containers)Stop and remove the given containers concurrently.

Interfaces ​

InterfaceDescription
ContainerConfigurationDeclarative description of a single container. Ported from confetti's zod schema minus buildArgs (it was declared but never applied).
ContainerInformationThe serializable slice of a started container. ports maps each exposed container port to its mapped host port.
StartedContainerInformationA ContainerInformation plus the live, non-serializable handle.

Variables ​

VariableDescription
containerConfigurationSchemaZod schema validating a ContainerConfiguration. Unknown keys (such as the removed buildArgs) are stripped.

Type Aliases ​

Type AliasDescription
WaitStrategyWait strategy applied before a container is considered ready. Mirrors the three testcontainers strategies confetti relied on; timeout is the startup timeout in milliseconds (default 60000).