SYNOPSIS

use Testcontainers qw( run terminate_container );
use Testcontainers::Wait;

# Simple usage - run a container
my $container = run('nginx:alpine',
    exposed_ports => ['80/tcp'],
    wait_for      => Testcontainers::Wait::for_listening_port('80/tcp'),
);

# Get connection details
my $host = $container->host;
my $port = $container->mapped_port('80/tcp');

# Use the container in tests...

# Clean up
$container->terminate;

# Or with environment variables and labels
my $container = run('postgres:16-alpine',
    exposed_ports => ['5432/tcp'],
    env           => { POSTGRES_PASSWORD => 'test', POSTGRES_DB => 'testdb' },
    labels        => { 'testcontainers' => 'true' },
    wait_for      => Testcontainers::Wait::for_log('database system is ready to accept connections'),
);

DESCRIPTION

Testcontainers for Perl is a Perl library that makes it simple to create and clean up container-based dependencies for automated integration/smoke tests. The clean, easy-to-use API enables developers to programmatically define containers that should be run as part of a test and clean up those resources when the test is done.

This library is inspired by the Testcontainers for Go project and uses WWW::Docker as its Docker client library.

FEATURES

• Simple API for creating and managing test containers

• Wait strategies: port listening, HTTP endpoints, log messages, health checks

• Pre-built modules for popular services (PostgreSQL, MySQL, Redis, Nginx)

• Automatic container cleanup

• Port mapping and host resolution

• Environment variable and label support

• Container lifecycle hooks

Create and start a new container. Returns a Testcontainers::Container object.

Arguments:

• $image - Docker image name (required)

• exposed_ports - ArrayRef of ports to expose (e.g., ['80/tcp', '443/tcp'])

• env - HashRef of environment variables

• labels - HashRef of container labels

• cmd - ArrayRef of command arguments

• entrypoint - ArrayRef for container entrypoint

• name - Container name (optional)

• wait_for - Wait strategy object (from Testcontainers::Wait)

• tmpfs - HashRef of tmpfs mounts (path => options)

• startup_timeout - Timeout in seconds for wait strategy (default: 60)

• privileged - Run in privileged mode (default: false)

• network_mode - Docker network mode

• networks - ArrayRef of network names

• docker_host - Docker daemon URL (overrides DOCKER_HOST)

• no_pull - Skip pulling the image (default: false)

Terminate and remove a container. Safe to call with undef.

ENVIRONMENT VARIABLES

DOCKER_HOST

Docker daemon connection URL. Default: unix:///var/run/docker.sock

TESTCONTAINERS_RYUK_DISABLED

Set to 1 to disable the Ryuk resource reaper (container cleanup).

SEE ALSO

• Testcontainers::Container - Container instance methods

• Testcontainers::Wait - Wait strategy factory

• Testcontainers::Module::PostgreSQL - PostgreSQL module

• Testcontainers::Module::MySQL - MySQL module

• Testcontainers::Module::Redis - Redis module

• WWW::Docker - Docker client library

• https://golang.testcontainers.org/ - Testcontainers for Go (reference)