Testcontainers for Crystal

A lightweight Crystal library for writing tests with throwaway Docker containers, inspired by testcontainers-ruby. Uses docr for Docker Engine API communication.

Requirements

Crystal >= 1.10.0
Docker or Docker Desktop running

Installation

Add to your shard.yml:

dependencies:
  testcontainers:
    github: dragosv/testcontainers-crystal
    version: "~> 0.1.0"

Then run:

shards install

Quick Start

See QUICKSTART.md for a step-by-step guide.

require "testcontainers"

container = Testcontainers::DockerContainer.new("nginx:latest")
  .with_exposed_port(80)
  .with_wait_for(:http, port: 80)
  .start

port = container.mapped_port(80)
puts "Nginx running at http://localhost:#{port}"

container.stop
container.remove

Modules

Pre-configured containers for common services — each exposes a connection_url convenience method:

Module	Image	Default Port
`PostgresContainer`	`postgres`	5432
`MySQLContainer`	`mysql`	3306
`MariaDBContainer`	`mariadb`	3306
`RedisContainer`	`redis`	6379
`MongoContainer`	`mongo`	27017
`NginxContainer`	`nginx`	80
`RabbitMQContainer`	`rabbitmq`	5672 / 15672
`ElasticsearchContainer`	`elasticsearch`	9200

pg = Testcontainers::PostgresContainer.new
  .with_database("testdb")
  .start

url = pg.connection_url

Wait Strategies

# Wait for log message matching a regex
.with_wait_for(:logs, message: /ready to accept connections/)

# Wait for a TCP port to be reachable
.with_wait_for(:tcp, port: 5432)

# Wait for an HTTP endpoint to return 200
.with_wait_for(:http, port: 8080, path: "/health")

# Wait for Docker HEALTHCHECK to report healthy
.with_wait_for(:healthcheck)

Crystal Spec Integration

require "spec"
require "testcontainers"

describe "Database" do
  it "connects to PostgreSQL" do
    pg = Testcontainers::PostgresContainer.new
      .with_database("testdb")
      .start

    begin
      url = pg.connection_url
      url.should contain("postgres://")
    ensure
      pg.stop
      pg.remove
    end
  end
end

Networking

Testcontainers::Network.create("app-net") do |network|
  db = Testcontainers::PostgresContainer.new
    .with_network(network)
    .with_network_alias("database")
    .start

  app = Testcontainers::DockerContainer.new("myapp:latest")
    .with_network(network)
    .with_env("DB_HOST", "database")
    .start

  # app can reach db at hostname "database"

  app.stop; app.remove
  db.stop; db.remove
end

Documentation

Document	Description
QUICKSTART.md	5-minute getting-started guide
ARCHITECTURE.md	Design decisions and component overview
IMPLEMENTATION_GUIDE.md	Detailed implementation guide
PROJECT_SUMMARY.md	Full feature inventory and stats
CONTRIBUTING.md	How to contribute