Testcontainers

Testcontainers is an Elixir library that supports ExUnit tests, providing lightweight, throwaway instances of common databases, Selenium web browsers, or anything else that can run in a Docker container.

Table of Contents

• Prerequisites
• Installation
• Usage
• API Documentation
• Contributing
• License
• Contact

Prerequisites

Before you begin, ensure you have met the following requirements:

• You have installed the latest version of Elixir
• You have a Docker installed and running
• You are familiar with Elixir and Docker basics

Installation

To add Testcontainers to your project, follow these steps:

1. Add testcontainers to your list of dependencies in mix.exs:

def deps do
  [
    {:testcontainers, "~> x.x.x"}
  ]
end

1. Run mix deps.get

Usage

This section explains how to use the Testcontainers library in your own project.

In a Phoenix project:

In simple terms you can add this in application.ex:

  # In your application.ex file in your Phoenix project:

  import Testcontainers.Ecto

  @impl true
  def start(_type, _args) do
    postgres_container(
      app: :my_app,
      user: "postgres",
      password: "postgres"
    )

    # .. other setup code
  end

see documentation on Testcontainers.Ecto for more information about the options it can take.

There is an example repo here with a bare bones phoenix application, where the only changes are the inclusion of the ecto macro and removing the test alias that interferes with the macro:

https://github.com/jarlah/hello_testcontainers

Simple example

Here's a simple example of how to use a MySQL container in your tests:

# test/a_simple_mysql_container_test.exs

defmodule ASimpleMySqlContainerTest do
  use ExUnit.Case, async: true

  import Testcontainers.ExUnit

  alias Testcontainers.Container.MySqlContainer

  describe "with default configuration" do
    container(:mysql, MySqlContainer.new())

    test "provides a ready-to-use mysql container", %{mysql: mysql} do
      assert mysql.environment[:MYSQL_MAJOR] == "8.0"
    end
  end
end

Global Setup

If you prefer to set up a globally shared database for all tests in the project, you can configure and run a container inside the test/test_helper.exs file:

# test/test_helper.exs

import Testcontainers.ExUnit
alias Testcontainers.Container
alias Container.PostgresContainer

postgres =
  PostgresContainer.new("postgres:latest")
  |> Container.with_fixed_port(5432)
  # or |> Container.with_fixed_port(5432, <OTHER_HOST_PORT>) 

{:ok, _} = run_container(postgres, on_exit: nil)

ExUnit.start()

The container will be deleted by Ryuk after the test session ends.

NOTE: This will cause the test process to exit prematurely if the port is already used. Use with care!

Logging

By default, Testcontainers doesn't log anything. If you want Testcontainers to log, set the desired log level in config/test.exs:

# config/test.exs

import Config 

config :testcontainers,
  log_level: :warning

API Documentation

For more detailed information about the API, different container configurations, and advanced usage scenarios, please refer to the API documentation.

Contributing

We welcome your contributions! Please see our contributing guidelines (TBD) for more details on how to submit patches and the contribution workflow.

License

Testcontainers is available under the MIT license. See the LICENSE file for more info.

Contact

If you have any questions, issues, or want to contribute, feel free to contact us.

Thank you for using Testcontainers to test your Elixir applications!