Behavior of setup_all in ExUnit

It is documented here ExUnit.Callbacks — ExUnit v1.20.2

But more examples wouldn‘t hurt I guess. Maybe ask first in Elixir repo.

Yeah, I read that but I didn’t understand much of it from the examples given. “Your documentation has too many examples” said no developer ever. I’ll put together a PR and see what comes of it. Thanks!

defmodule EdnoTest do
  use ExUnit.Case

  setup_all do
    {:ok, setup_all: :rand.uniform(100)}
  end

  setup do
    {:ok, setup: :rand.uniform(100)}
  end

  test "1", context do
    IO.inspect Map.take(context, [:setup_all, :setup])
  end

  test "2", context do
    IO.inspect Map.take(context, [:setup_all, :setup])
  end
end

Running this test suite yields this:

%{setup: 85, setup_all: 6}
.%{setup: 44, setup_all: 6}
.

setup_all has the same value for all tests in the suite – namely it’s called once for the test file (the suite) – while setup is called on each test.

Not trying to be demeaning, just legitimately curious what is tripping you.

That’s a great example! Worthy of being included in the docs.

What’s tripping me is that the docs do not have examples as clear as that. I know I am an educator, so my standards for documentation may be high, but I feel the current docs could help reduce mental friction and clarify this feature more quickly by including more examples. Explanations are a nice-to-have; examples are paramount.

Specifically:

• The docs nowhere mention the notion of a Test Fixture, and that’s really what these functions are relevant to. Other languages/frameworks refer to such functions as fixtures, so the mere act of name-dropping that term will help the light-bulb go off for some people.
• The examples of the context variable could be more clear (e.g. like yours).
• I haven’t seen a clear example of how/why you can return a tuple OR a map and the context comes through the same. That’s kind of a weird bit of unseen macro “magic” that is rare in the functional world.

I’m working on the PR to include some clarifications to the existing docs.

I did make the mind-mapping from the previous TDD terminology I was familiar with, and connected it to ExUnit myself. But I agree that it should be explicit in the docs.

Sounds like you can use your educator / copywriter skills to help improve the docs then.

I’d guess that it’s just for ease of use and sometimes to make use of functions that return ok/error tuples in other parts of the code.