Repository files navigation

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.

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

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

• You have installed the latest version ofElixir
• You have a Docker runtime installed
• You are familiar with Elixir and Docker basics

To add Testcontainers to your project, follow these steps:

1. Addtestcontainers to your list of dependencies inmix.exs:

defdepsdo[{:testcontainers,"~> 1.13",only:[:test,:dev]}]end

2. Run mix deps.get

3. Add the following to test/test_helper.exs

Testcontainers.start_link()

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

You can use generic container api, where you have to define everything yourself:

{:ok,_}=Testcontainers.start_link()config=%Testcontainers.Container{image:"redis:5.0.3-alpine"}{:ok,container}=Testcontainers.start_container(config)

Or you can use one of many predefined containers likeRedisContainer, that has waiting strategies among other things defined up front with good defaults:

{:ok,_}=Testcontainers.start_link()config=Testcontainers.RedisContainer.new(){:ok,container}=Testcontainers.start_container(config)

If you want to use a predefined container, such asRedisContainer, with an alternative image, for example,valkey/valkey, it's possible:

{:ok,_}=Testcontainers.start_link()config=Testcontainers.RedisContainer.new()|>Testcontainers.RedisContainer.with_image("valkey/valkey:latest")|>Testcontainers.RedisContainer.with_check_image("valkey/valkey"){:ok,container}=Testcontainers.start_container(config)

Given you have added Testcontainers.start_link() to test_helper.exs:

setupconfig=Testcontainers.RedisContainer.new(){:ok,container}=Testcontainers.start_container(config)ExUnit.Callbacks.on_exit(fn->Testcontainers.stop_container(container.container_id)end){:ok,%{redis:container}}end

there is a macro that can simplify this down to a oneliner:

importTestcontainers.ExUnitcontainer(:redis,Testcontainers.RedisContainer.new())

To run/wrap testcontainers around a project use the testcontainers.run task.

mix testcontainers.run [sub_task] [--database postgres|mysql] [--db-volume VOLUME]

to use postgres you can just run

mix testcontainers.run test since postgres is default and test is the default sub-task.

# Run tests with PostgreSQL (default)MIX_ENV=test mix testcontainers.runtest# Run tests with MySQLMIX_ENV=test mix testcontainers.runtest --database mysql# Run Phoenix server with PostgreSQL and persistent volumemix testcontainers.run phx.server --database postgres --db-volume my_postgres_data# Run tests with MySQL and persistent volumeMIX_ENV=test mix testcontainers.runtest --database mysql --db-volume my_mysql_data# Start Phoenix server with containerized DB (will keep running until stopped)mix testcontainers.run phx.server --database postgres --db-volume my_dev_data

The--db-volume parameter allows you to specify a persistent volume for database data. This ensures that your database data persists between container restarts. The volume name you provide will be used to create a Docker volume that gets mounted to the appropriate database data directory:

• PostgreSQL: Volume is mounted to/var/lib/postgresql/data
• MySQL: Volume is mounted to/var/lib/mysql

This is particularly useful when you want to maintain database state across test runs or development sessions.

Instead of editing dev.exs or test.exs, you can let testcontainers setDATABASE_URL and use it fromconfig/runtime.exs for dev and test:

# config/runtime.exsifconfig_env()in[:dev,:test]doifurl=System.get_env("DATABASE_URL")doconfig:my_app,MyApp.Repo,url:url,pool:Ecto.Adapters.SQL.Sandbox,show_sensitive_data_on_connection_error:true,pool_size:10endend

This allows you to run your Phoenix server or tests with a containerized database without changing dev.exs or test.exs (remember to set MIX_ENV when running tests):

# Start Phoenix server with PostgreSQL containermix testcontainers.run phx.server --database postgres# Start Phoenix server with MySQL containermix testcontainers.run phx.server --database mysql# Start with persistent datamix testcontainers.run phx.server --database postgres --db-volume my_dev_data

Activate reuse of database containers started by mix task with addingtestcontainers.reuse.enable=true in~/.testcontainers.properties. This is experimental.

You can pass arguments to the sub-task by appending them after--. For example, to pass arguments to mix test:

MIX_ENV=test mix testcontainers.run test -- --exclude flaky --stale

In the example above we are running tests while excluding flaky tests and using the --stale option.

Note: MIX_ENV is not overridden by the run task. For tests, set it explicitly in the shell:

MIX_ENV=test mix testcontainers.run test

For backward compatibility, the oldmix testcontainers.test task is still available and works exactly as before. It automatically delegates tomix testcontainers.run test, so existing scripts and workflows will continue to work without modification:

# These commands are equivalent:mix testcontainers.test --database mysqlmix testcontainers.runtest --database mysql# Both support all the same options:mix testcontainers.test --database postgres --db-volume my_datamix testcontainers.runtest --database postgres --db-volume my_data

While the old task will continue to work, we recommend updating tomix testcontainers.run for new projects as it provides more flexibility by allowing you to run any Mix task, not just tests.

Testcontainers use the standard Logger, seehttps://hexdocs.pm/logger/Logger.html.

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

This is the supported way to use Testcontainers Elixir on Windows. Download Testcontainers Desktop, install it and everything just works.

You can run on windows natively with elixir and erlang. But its not really supported, but I have investigated and tried it out. These are my findings:

First install Visual Studio 2022 with Desktop development with C++.

Open visual studio dev shell. I do it by just opening an empty c++ project, then View -> Terminal.

Enable "Expose daemon on tcp://localhost:2375 without TLS" in Docker settings.

for powershell:

$Env:DOCKER_HOST = "tcp://localhost:2375"

for cmd:

set DOCKER_HOST=tcp://localhost:2375

Compile and run tests:

mix deps.get

mix deps.compile

mix test

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

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

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!