Testcontainers for Ruby

To allow multiple containers to communicate with each other, attach them to a shared network using Testcontainers::Network::SHARED (or Testcontainers::Network.shared). This singleton network persists for the lifetime of your test suite and is cleaned up automatically when the process exits.

network = Testcontainers::Network::SHARED

redis = Testcontainers::DockerContainer.new("redis:6.2-alpine").with_network(network)
nginx = Testcontainers::DockerContainer.new("nginx:alpine").with_network(network)

Instead of using the generic DockerContainer, Testcontainers provides specialized modules for common databases and services. These modules offer pre-configured setups and reduce boilerplate code.

Available modules include:

• ComposeContainer
• ElasticsearchContainer
• MariadbContainer
• MongoContainer
• MysqlContainer
• NginxContainer
• PostgresContainer
• RabbitmqContainer
• RedisContainer
• RedpandaContainer
• SeleniumContainer

To avoid the overhead of starting/stopping containers for every single test, manage the Redpanda container lifecycle within RSpec's before(:suite) and after(:suite) blocks. This allows you to attach the container instance to the RSpec configuration for easy access in your specs.

RSpec.configure do |config|
  # Register a setting to hold the container instance
  config.add_setting :redpanda_container, default: nil

  config.before(:suite) do
    # Start the container once before the entire test suite runs
    config.redpanda_container = Testcontainers::RedpandaContainer.new.start
  end

  config.after(:suite) do
    # Clean up the container after the suite finishes
    config.redpanda_container&.stop
    config.redpanda_container&.remove
  end
end

To connect your application code to a container, use @container.host to get the host address and @container.mapped_port(original_port) to get the dynamically assigned port on the host. It is recommended to use @container.wait_for_tcp_port(port) to ensure the service is ready before attempting a connection.

@redis_container = Testcontainers::DockerContainer.new("redis:6.2-alpine").with_exposed_ports(6379)
@redis_container.start
@redis_container.wait_for_tcp_port(6379)

host = @redis_container.host
port = @redis_container.mapped_port(6379)

# Use host and port to initialize your application component
@under_test = RedisBackedCache.new(host, port)

To set up a local development environment for this repository:

1. Run bin/setup to install dependencies.
2. Run rake test to execute the test suite.
3. Use bin/console for an interactive prompt to experiment with the API.
4. To install the gem locally from the source, run bundle exec rake install.

To avoid using global variables, you can attach the container to the RSpec configuration. Use before(:suite) to start the container and after(:suite) to stop and remove it. You can also inject the database_url into the ENV for your application to consume.

RSpec.configure do |config|
  # Add a setting to access the container via RSpec configuration
  config.add_setting :mariadb_container, default: nil

  config.before(:suite) do
    # Start the container and assign it to the config setting
    config.mariadb_container = Testcontainers::MariadbContainer.new.start
    
    # Expose the connection via DATABASE_URL
    ENV["DATABASE_URL"] = config.mariadb_container.database_url(protocol: "mysql2")
  end

  config.after(:suite) do
    # Clean up the container
    config.mariadb_container&.stop
    config.mariadb_container&.remove
  end
end

You can manage container lifecycles using Testcontainers::DockerContainer. Use .new(image_name) to specify the image and .with_exposed_ports(port) to expose specific ports. Call .start to launch the container and .stop to shut it down.

require "testcontainers"

# Create and start a container
@redis_container = Testcontainers::DockerContainer.new("redis:6.2-alpine").with_exposed_ports(6379)
@redis_container.start

# Stop the container
@redis_container.stop if @redis_container

You can install the testcontainers gem using Bundler or by using the gem command directly.

If you are using Bundler, add it to your Gemfile by running:

$ bundle add testcontainers

If you are not using Bundler, install it via:

$ gem install testcontainers

To use the MySQL module, add testcontainers-mysql to your application's Gemfile within the :test group, then run bundle install.

group :test do
  gem 'testcontainers-mysql'
end

$ bundle install

To use Testcontainers in your Ruby project, add the testcontainers gem to your Gemfile and run bundle install.

gem "testcontainers"

To use the Postgres module, add testcontainers-postgres to your application's Gemfile within the :test group and run bundle install.

Alternatively, you can install the gem directly using gem install.

group :test do
  gem "testcontainers-postgres"
end

$ bundle install
# or
$ gem install testcontainers-postgres