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

Contributing

Contributions are welcome — please read CONTRIBUTING.md first.

Acknowledgments

• testcontainers-ruby — Reference implementation
• docr — Crystal Docker client

License

MIT — see LICENSE.

Support

GitHub Issues · Testcontainers Slack