Elixir "mix test" considers @doc examples as tests

Question

Recently I wrote a the following function:

  @doc """
  Creates a new deck, shuffles its cards and retrieves a hand of
  cards from it.
  The `hand_size` argument indicates the size of the hand.

  ## Examples
      iex> {hand, _deck_remainder} = Cards.create_hand 2
      iex> hand
      ["Ace of Clubs", "Four of Hearts"]
  """
  def create_hand(hand_size) do
    create_deck
    |> shuffle
    |> deal(hand_size)
  end

Points to consider:

• create_deck/0 returns a list of strings like ["Two of Clubs", "Four of Hearts"]
• shuffle/1 takes a list of strings and shuffles them using Enum.shuffle/1
• deal/2 returns a tuple like {["Ace of Spades"], ["Five of Clubs"]}

Then I ran the mix test task and the following error appeared:

ERROR

It looks like mix test is considering the examples in @doc annotations as unit tests.

Due to shuffle/1 randomly arranges the strings in the list, the example (as unit test) crashes.

I'd like to exclude those examples from mix test... Is it a good idea to do it? If so, how can I exclude them?

Answer 1

You probably have copied some boilerplate test code that enables doctests by default. Like:

defmodule MyModule.Test do
  use ExUnit.Case, async: true
  doctest MyModule
end

Remove the doctest bit and you should be fine. You can of course also format the comment to not look like a doctest :-)