# `ExUnit.CaseTemplate`
[🔗](https://github.com/elixir-lang/elixir/blob/v1.20.0-rc.4/lib/ex_unit/lib/ex_unit/case_template.ex#L5)

Defines a module template to be used throughout your test suite.

This is useful when there are a set of setup callbacks or a set
of functions that should be shared between test modules.

Let's imagine that you create a `MyCase` module that calls `use
ExUnit.CaseTemplate`. When a test case module calls `use MyCase`, the
following things hold true:

  * All the functionality that `MyCase` would have had available from
    `use ExUnit.Case` is available (same as if `MyCase` called `use
    ExUnit.Case` directly)

  * The `setup` and `setup_all` callbacks that you define in `MyCase`
    get used in the test case module

The options that you pass to `use MyCase` get also passed to `use
ExUnit.Case` under the hood. This means you can do things like `use
MyCase, async: true`. You can also access this options in `using/2`.

> #### `use ExUnit.CaseTemplate` {: .info}
>
> When you `use ExUnit.CaseTemplate`, it will import the functionality
> from `ExUnit.Assertions`, `ExUnit.Callbacks`, and this module itself.
> It will also define a `__using__` callback, so the module itself can
> be used as a template instead of `ExUnit.Case`.

## Example

    defmodule MyCase do
      use ExUnit.CaseTemplate

      setup do
        IO.puts("This will run before each test that uses this case")
      end
    end

    defmodule MyTest do
      use MyCase, async: true

      test "truth" do
        assert true
      end
    end

If you need to "hook" into `use MyCase` and do other things as well,
you can use the `using/2` macro. See its documentation for more
information and examples.

    defmodule MyCase do
      use ExUnit.CaseTemplate

      using do
        quote do
          import MyApp.TestHelpers
        end
      end
    end

# `using`
*macro* 

Allows a developer to customize the using block
when the case template is used.

You can use an optional `var` argument when calling `using/2`. ExUnit
will pass whatever argument you pass to `use MyCase` as this `var` argument. See the examples below for clarification.

## Example

    defmodule MyCase do
      use ExUnit.CaseTemplate

      using do
        quote do
          # This code is injected into every case that calls "use MyCase"
          alias MyApp.FunModule
        end
      end
    end

You can specify an argument to `using/2`:

    defmodule MyCase do
      use ExUnit.CaseTemplate

      using options do
        quote do
          if unquote(options)[:import_helpers] do
            import MyApp.TestHelpers
          end
        end
      end
    end

The second argument passed to `use MyCase` gets forwarded to `using/2` too:

    defmodule SomeTestCase do
      use MyCase, async: true, import_helpers: true

      test "the truth" do
        # truth/0 comes from MyApp.TestHelpers:
        assert truth()
      end
    end

> #### Sharing options with `use ExUnit.Case` {: .warning}
>
> The second argument that you pass to `use MyCase` is *also* passed
> as the second argument to `use ExUnit.Case`.

---

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