Skip to content

PROJECT_SUMMARY.md

Latest commit

 

History

History
165 lines (141 loc) · 6.08 KB

PROJECT_SUMMARY.md

File metadata and controls

165 lines (141 loc) · 6.08 KB

PROJECT_SUMMARY.md

Testcontainers for Perl 5 — Implementation Summary

This document provides a comprehensive overview of the testcontainers-perl5 implementation.

Implementation Status

Core Library — Complete

Component Status Module
Main entry point Done Testcontainers
Container wrapper Done Testcontainers::Container
Request builder Done Testcontainers::ContainerRequest
Docker client Done Testcontainers::DockerClient
Labels specification Done Testcontainers::Labels

Wait Strategies — Complete

Strategy Status Module
TCP port listening Done Testcontainers::Wait::HostPort
HTTP endpoint Done Testcontainers::Wait::HTTP
Log message matching Done Testcontainers::Wait::Log
Docker health check Done Testcontainers::Wait::HealthCheck
Composite (all) Done Testcontainers::Wait::Multi
Base role (polling) Done Testcontainers::Wait::Base
Factory functions Done Testcontainers::Wait

Pre-Built Modules — Complete

Module Status Factory Features
PostgreSQL Done postgres_container() DSN, connection string
MySQL Done mysql_container() DSN, connection string
Redis Done redis_container() Connection string, optional password
Nginx Done nginx_container() Base URL

Container Features — Complete

Feature Status
Port mapping Done
Environment variables Done
Labels (with validation) Done
Command / Entrypoint Done
Tmpfs mounts Done
Privileged mode Done
Network mode Done
Named networks Done
Container exec Done
Container logs Done
Auto-cleanup (DEMOLISH) Done

Build & CI — Complete

Component Status
Module::Build Done
cpanfile Done
GitHub Actions CI Done
perlcritic linting Done

Vendored Dependencies

Dependency Source Reason
WWW::Docker Getty/p5-www-docker Unmaintained upstream

File Structure

lib/
├── Testcontainers.pm                 # run(), terminate_container()
├── Testcontainers/
│   ├── Container.pm                  # Running container wrapper
│   ├── ContainerRequest.pm           # Config → Docker API
│   ├── DockerClient.pm               # WWW::Docker wrapper
│   ├── Labels.pm                     # org.testcontainers.* labels
│   ├── Wait.pm                       # Strategy factory
│   ├── Wait/
│   │   ├── Base.pm                   # Moo::Role polling loop
│   │   ├── HostPort.pm               # TCP check
│   │   ├── HTTP.pm                   # HTTP check
│   │   ├── Log.pm                    # Log matching
│   │   ├── HealthCheck.pm            # Health check
│   │   └── Multi.pm                  # Composite
│   └── Module/
│       ├── PostgreSQL.pm             # postgres_container()
│       ├── MySQL.pm                  # mysql_container()
│       ├── Redis.pm                  # redis_container()
│       └── Nginx.pm                  # nginx_container()
└── WWW/
    ├── Docker.pm                     # Vendored Docker client
    └── Docker/
        ├── Container.pm
        ├── ContainerExec.pm
        ├── ContainerExecStart.pm
        ├── Image.pm
        ├── Network.pm
        ├── Request.pm
        ├── System.pm
        └── Volume.pm

t/
├── 01-load.t                         # Module loading
├── 02-container-request.t            # Unit tests
├── 03-wait-strategies.t              # Unit tests
├── 04-integration.t                  # Integration (Docker)
├── 05-modules.t                      # Integration (Docker)
├── 06-basic.t                        # WWW::Docker tests
├── 07-system.t
├── 08-version.t
├── 09-containers.t
├── 10-images.t
├── 11-networks.t
├── 12-volumes.t
├── fixtures/
└── lib/

Implementation Statistics

Metric Count
Testcontainers source files 16
Vendored WWW::Docker files 9
Test files 12
Total Testcontainers LOC ~2,500
Total vendored LOC ~1,500
Total test LOC ~1,300
Unit tests 85+
Wait strategies 5 (+1 composite)
Pre-built modules 4

API Comparison with Go

Go Testcontainers Perl Testcontainers
testcontainers.Run(ctx, req) Testcontainers::run($image, %opts)
container.Host(ctx) $container->host
container.MappedPort(ctx, "80/tcp") $container->mapped_port('80/tcp')
container.Endpoint(ctx, "") $container->endpoint('80/tcp')
container.Exec(ctx, cmd) $container->exec(\@cmd)
container.Logs(ctx) $container->logs
testcontainers.TerminateContainer(c) $container->terminate
wait.ForListeningPort("80/tcp") Testcontainers::Wait::for_listening_port('80/tcp')
wait.ForHTTP("/") Testcontainers::Wait::for_http('/')
wait.ForLog("ready") Testcontainers::Wait::for_log('ready')
wait.ForHealthCheck() Testcontainers::Wait::for_health_check()
wait.ForAll(...) Testcontainers::Wait::for_all(...)
testcontainers.WithEnv(map) env => { ... }
testcontainers.WithExposedPorts(...) exposed_ports => [...]
postgres.Run(ctx, ...) postgres_container(...)

Future Enhancements

  • Ryuk resource reaper — automatic cleanup of orphaned containers
  • Docker Compose — multi-container orchestration support
  • Volume mounts — bind mount and named volume helpers
  • File copy — copy files to/from containers
  • Additional modules — MongoDB, Kafka, Elasticsearch, RabbitMQ
  • CPAN distribution — package for CPAN release
  • Container reuse — persist containers across test runs for speed