# `Testcontainers.ExUnit`
[🔗](https://github.com/testcontainers/testcontainers-elixir/blob/main/lib/exunit.ex#L4)

Convenient macros to run containers within ExUnit tests.

# `compose`
*macro* 

Creates and manages the lifecycle of a Docker Compose environment within ExUnit tests.

When the `:shared` option is set to `true`, the compose environment is created once for all
tests in the module. When omitted or set to `false`, a new compose environment is created
for each individual test.

## Parameters

  * `name`: The key that should be used to reference the compose environment in test cases.
  * `config`: A `%Testcontainers.DockerCompose{}` struct with the compose configuration.
  * `options`: Optional keyword list. Supports the following options:
    * `:shared` - If set to `true`, the compose environment is shared across all tests.

## Examples

    defmodule MyComposeTest do
      use ExUnit.Case

      alias Testcontainers.DockerCompose

      compose :my_env, DockerCompose.new("test/fixtures")
      # ...
    end

# `container`
*macro* 

Creates and manages the lifecycle of a container within ExUnit tests.

When the `:shared` option is set to `true`, the container is created once for all tests in the module. It initializes the container before any test is run and keeps it running across multiple tests. This is useful for scenarios where the cost of setting up and tearing down the container is high, or the tests are read-only and won't change the container's state.

When the `:shared` option is omitted or set to `false`, a new container is created for each individual test, ensuring a clean state for each test case. The container is removed after each test finishes.

## Parameters

  * `name`: The key that should be used to reference the container in test cases.
  * `config`: Configuration necessary for initializing the container.
  * `options`: Optional keyword list. Supports the following options:
    * `:shared` - If set to `true`, the container is shared across all tests in the module. If `false` or omitted, a new container is used for each test.

## Examples

To create a new container for each test:

    defmodule MyTest do
      use ExUnit.Case

      alias Testcontainers.Container

      container :my_container, %Container{image: "my_image"}
      # ...
    end

To share a container across all tests in the module:

    defmodule MySharedTest do
      use ExUnit.Case

      alias Testcontainers.Container

      container :my_shared_container, %Container{image: "my_shared_image"}, shared: true
      # ...
    end

## Notes

  * The macro sets up the necessary ExUnit callbacks to manage the container's lifecycle.
  * It ensures the `Connection` and `Reaper` are started before initializing a container.
  * In the case of shared containers, be mindful that tests can affect the container's state, potentially leading to interdependencies between tests.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
