{"id":17477450,"url":"https://github.com/testcontainers/testcontainers-elixir","last_synced_at":"2026-03-17T08:08:04.314Z","repository":{"id":199533581,"uuid":"703103806","full_name":"testcontainers/testcontainers-elixir","owner":"testcontainers","description":"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.","archived":false,"fork":false,"pushed_at":"2024-05-15T18:26:00.000Z","size":662,"stargazers_count":82,"open_issues_count":11,"forks_count":8,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-05-22T18:21:08.440Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/testcontainers.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-10-10T15:46:18.000Z","updated_at":"2024-05-28T17:17:42.196Z","dependencies_parsed_at":"2023-10-16T04:14:30.003Z","dependency_job_id":"23f02f60-c35c-4d60-a358-60c3487419ea","html_url":"https://github.com/testcontainers/testcontainers-elixir","commit_stats":{"total_commits":333,"total_committers":8,"mean_commits":41.625,"dds":0.0570570570570571,"last_synced_commit":"a4e48a56ecefde84eaf433ac4cab2c7da4eed626"},"previous_names":["jarlah/testcontainers-elixir","testcontainers/testcontainers-elixir"],"tags_count":49,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testcontainers%2Ftestcontainers-elixir","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testcontainers%2Ftestcontainers-elixir/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testcontainers%2Ftestcontainers-elixir/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/testcontainers%2Ftestcontainers-elixir/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/testcontainers","download_url":"https://codeload.github.com/testcontainers/testcontainers-elixir/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247493734,"owners_count":20947758,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-18T20:08:08.061Z","updated_at":"2026-03-17T08:08:04.309Z","avatar_url":"https://github.com/testcontainers.png","language":"Elixir","funding_links":[],"categories":["Languages"],"sub_categories":[],"readme":"# Testcontainers\n\n[![Hex.pm](https://img.shields.io/hexpm/v/testcontainers.svg)](https://hex.pm/packages/testcontainers)\n\n\u003e 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.\n\n## Table of Contents\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n- [Usage](#usage)\n- [API Documentation](#api-documentation)\n- [Contributing](#contributing)\n- [License](#license)\n- [Contact](#contact)\n\n## Prerequisites\n\nBefore you begin, ensure you have met the following requirements:\n- You have installed the latest version of [Elixir](https://elixir-lang.org/install.html)\n- You have a Docker runtime installed\n- You are familiar with Elixir and Docker basics\n\n## Installation\n\nTo add Testcontainers to your project, follow these steps:\n\n1. Add `testcontainers` to your list of dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:testcontainers, \"~\u003e X.XX\", only: [:test, :dev]}\n  ]\nend\n```\n\nReplace X.XX with the current major and minor version.\n\n2. Run mix deps.get\n\n3. Add the following to test/test_helper.exs\n\n```elixir\nTestcontainers.start_link()\n```\n\n## Usage\n\nThis section explains how to use the Testcontainers library in your own project.\n\n### Basic usage\n\nYou can use generic container api, where you have to define everything yourself:\n\n```elixir\n{:ok, _} = Testcontainers.start_link()\nconfig = %Testcontainers.Container{image: \"redis:5.0.3-alpine\"}\n{:ok, container} = Testcontainers.start_container(config)\n```\n\nOr you can use one of many predefined containers like `RedisContainer`, that has waiting strategies among other things defined up front with good defaults:\n\n```elixir\n{:ok, _} = Testcontainers.start_link()\nconfig = Testcontainers.RedisContainer.new()\n{:ok, container} = Testcontainers.start_container(config)\n```\n\nIf you want to use a predefined container, such as `RedisContainer`, with an alternative image, for example, `valkey/valkey`, it's possible:\n\n```elixir\n{:ok, _} = Testcontainers.start_link()\nconfig =\n  Testcontainers.RedisContainer.new()\n  |\u003e Testcontainers.RedisContainer.with_image(\"valkey/valkey:latest\")\n  |\u003e Testcontainers.RedisContainer.with_check_image(\"valkey/valkey\")\n{:ok, container} = Testcontainers.start_container(config)\n```\n\n### ExUnit tests\n\nGiven you have added Testcontainers.start_link() to test_helper.exs:\n\n```elixir\nsetup \n  config = Testcontainers.RedisContainer.new()\n  {:ok, container} = Testcontainers.start_container(config)\n  ExUnit.Callbacks.on_exit(fn -\u003e Testcontainers.stop_container(container.container_id) end)\n  {:ok, %{redis: container}}\nend\n```\n\nthere is a macro that can simplify this down to a oneliner:\n\n```elixir\nimport Testcontainers.ExUnit\n\ncontainer(:redis, Testcontainers.RedisContainer.new())\n```\n\n### Run tests in a Phoenix project (or any project for that matter)\n\nTo run/wrap testcontainers around a project use the testcontainers.run task.\n\n`mix testcontainers.run [sub_task] [--database postgres|mysql] [--db-volume VOLUME]`\n\nto use postgres you can just run\n\n`mix testcontainers.run test` since postgres is default and test is the default sub-task.\n\n#### Examples:\n\n```bash\n# Run tests with PostgreSQL (default)\nMIX_ENV=test mix testcontainers.run test\n\n# Run tests with MySQL\nMIX_ENV=test mix testcontainers.run test --database mysql\n\n# Run Phoenix server with PostgreSQL and persistent volume\nmix testcontainers.run phx.server --database postgres --db-volume my_postgres_data\n\n# Run tests with MySQL and persistent volume\nMIX_ENV=test mix testcontainers.run test --database mysql --db-volume my_mysql_data\n\n# Start Phoenix server with containerized DB (will keep running until stopped)\nmix testcontainers.run phx.server --database postgres --db-volume my_dev_data\n```\n\n#### Persistent Volumes\n\nThe `--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:\n\n- **PostgreSQL**: Volume is mounted to `/var/lib/postgresql/data`\n- **MySQL**: Volume is mounted to `/var/lib/mysql`\n\nThis is particularly useful when you want to maintain database state across test runs or development sessions.\n\n#### Configuration (runtime.exs)\n\nInstead of editing dev.exs or test.exs, you can let testcontainers set `DATABASE_URL` and use it from `config/runtime.exs` for dev and test:\n\n```elixir\n# config/runtime.exs\n\nif config_env() in [:dev, :test] do\n  if url = System.get_env(\"DATABASE_URL\") do\n    config :my_app, MyApp.Repo,\n      url: url,\n      pool: Ecto.Adapters.SQL.Sandbox,\n      show_sensitive_data_on_connection_error: true,\n      pool_size: 10\n  end\nend\n```\n\nThis 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):\n\n```bash\n# Start Phoenix server with PostgreSQL container\nmix testcontainers.run phx.server --database postgres\n\n# Start Phoenix server with MySQL container\nmix testcontainers.run phx.server --database mysql\n\n# Start with persistent data\nmix testcontainers.run phx.server --database postgres --db-volume my_dev_data\n```\n\nActivate reuse of database containers started by mix task with adding `testcontainers.reuse.enable=true` in `~/.testcontainers.properties`. This is experimental.\n\nYou can pass arguments to the sub-task by appending them after `--`. For example, to pass arguments to mix test:\n\n`MIX_ENV=test mix testcontainers.run test -- --exclude flaky --stale`\n\nIn the example above we are running tests while excluding flaky tests and using the --stale option.\n\nNote: MIX_ENV is not overridden by the run task. For tests, set it explicitly in the shell:\n\n`MIX_ENV=test mix testcontainers.run test`\n\n#### Backward Compatibility\n\nFor backward compatibility, the old `mix testcontainers.test` task is still available and works exactly as before. It automatically delegates to `mix testcontainers.run test`, so existing scripts and workflows will continue to work without modification:\n\n```bash\n# These commands are equivalent:\nmix testcontainers.test --database mysql\nmix testcontainers.run test --database mysql\n\n# Both support all the same options:\nmix testcontainers.test --database postgres --db-volume my_data\nmix testcontainers.run test --database postgres --db-volume my_data\n```\n\nWhile the old task will continue to work, we recommend updating to `mix testcontainers.run` for new projects as it provides more flexibility by allowing you to run any Mix task, not just tests.\n\n### Logging\n\nTestcontainers use the standard Logger, see https://hexdocs.pm/logger/Logger.html.\n\n## API Documentation\n\nFor more detailed information about the API, different container configurations, and advanced usage scenarios, please refer to the [API documentation](https://hexdocs.pm/testcontainers/api-reference.html).\n\n## Windows support\n\n### Testcontainers Desktop\n\nThis is the supported way to use Testcontainers Elixir on Windows. Download Testcontainers Desktop, install it and everything just works.\n\n### Native\nYou 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:\n\nFirst install Visual Studio 2022 with Desktop development with C++.\n\nOpen visual studio dev shell. I do it by just opening an empty c++ project, then View -\u003e Terminal.\n\nEnable \"Expose daemon on tcp://localhost:2375 without TLS\" in Docker settings.\n\nfor powershell:\n\n`$Env:DOCKER_HOST = \"tcp://localhost:2375\"`\n\nfor cmd:\n\n`set DOCKER_HOST=tcp://localhost:2375`\n\nCompile and run tests:\n\n`mix deps.get`\n\n`mix deps.compile`\n\n`mix test`\n\n## Contributing\n\nWe welcome your contributions! Please see our contributing guidelines (TBD) for more details on how to submit patches and the contribution workflow.\n\n## License\n\nTestcontainers is available under the MIT license. See the LICENSE file for more info.\n\n## Contact\n\nIf you have any questions, issues, or want to contribute, feel free to contact us.\n\n---\n\nThank you for using Testcontainers to test your Elixir applications!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftestcontainers%2Ftestcontainers-elixir","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftestcontainers%2Ftestcontainers-elixir","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftestcontainers%2Ftestcontainers-elixir/lists"}