jarlah

Testcontainers

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

It supports Testcontainers Desktop, but doesn’t need it to run. It will find and pick up a docker engine that works every time it runs.

Let me show you its features

In its basic form Testcontainers can used like this:

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

But the most interesting usage for Elixir is the Ecto module, which lets you run tests without having a postgres (or mysql) container running (see the README section for this advanced usage).

You can also spin up a throwaway container in a single ExUnit test:

container(:redis, Testcontainers.RedisContainer.new())

or shared container for multiple tests

container(:redis, Testcontainers.RedisContainer.new(), shared: true)

How it works

It has a dependency on an autogenerated elixir library for the docker engine api. The complex logic for calling out to docker is hidden inside that library.

41 comments

#ecto #library #docker #testing #exunit

20 3641 41

2026-03-16 17:06:42 UTC

Showing Posts 1 to 10

Show Best Posts
Show All (oldest first)
Show All (newest first)

thiagomajesk

That looks very very interesting, thanks for sharing!

Post #1

jarlah

new version v1.3.0 released which dynamically sets host port in repo config when using Testcontainers.Ecto No more duplication of database options see here for more info

Post #2

jarlah

Version 1.4.0 released

debug failed containers, containers are no longer autoremoved
added Minio and Cassandra container modules
experimental support for persistent containers with Testcontainers.Ecto

Post #3

hst337

This library looks awesome. I have some questions though:

Are database instances isolated from each other?
How much time does it take to spin up a single container? (I mean, less than a second, or several seconds, or even minutes)
Does database container run migrations every time it’s created? Or does it preserve the schema and seeds between runs?

Post #4

jarlah

Hi.

In its core it allows for spinning up containers in tests. I have additionally added support for running a database container in dev and test in Phoenix. I use this approach myself in all projects i work on lately. And it saves a lot of frustration not having to give the slightest thought about how the database is created. We use mix test.watch to automatically rerun test suites, and i cant say it takes that long to start the container. I think right now the bottleneck is the database startup, but we only have 170 simple tests which completes in sub second. For larger Phoenix projects and those with sync tests i would expect the tests being the bottle neck.

I am going to add some timing logs on container startup but i wouldnt use too much time on that. We use alpine version of postgres if remember correctly.

The readme has been improved a lot recently. So the example in the original post is outdated and just wrong. Not possible to compile for release when using Mix module in application.ex. So use the GitHub repo readme as example on how to do it properly.

The Ecto approach does run migrations each time tests are run or each time app is started. But it supports an option persistent_volume_name that makes it possible to run Phoenix in dev mode with persistent changes.

I dont understand the isolation question 100% but all containers use dynamic and random ports. And there is no reuse.

Post #5

jarlah

Oh btw yes seeds is not run automatically. I should propably fix that. PRs are welcomed.

Post #6

jarlah

however, there is an alternative way to solve this though. You can easily start the phoenix application in interactive elixir shell with iex -S mix phx.server and run Code.eval_file("priv/repo/seeds.exs") in the interactive terminal.

Post #7

sezaru

Any plans to support podman as an alternative to docker?

Post #8

dimitarvp

I might be missing something but podman can alias itself so the docker command actually calls podman.

Post #9

jarlah

This is supoorted by Testcontainers. There are docs on using podman on the Golang language docs on testcontainers.com. Testcontainers for elixir will work with any docker runtime given it can find a docker host. And it uses several strategies

Post #10

Load more posts (31 remaining)