elixir-testing

name	elixir-testing
description	ExUnit testing patterns for Elixir, including async strategy, Mox for behaviour mocking, test tags, database sandbox isolation, and performance benchmarking. Use when writing tests, setting up Mox mocks, choosing async: true or false, or structuring test modules.

Elixir Testing with ExUnit

async: true vs async: false

# async: true — test module runs concurrently with others
# Safe when: tests have no shared mutable state (no Registry, PubSub, ETS, DB)
defmodule MyApp.PureLogicTest do
  use ExUnit.Case, async: true

  test "calculates correctly" do
    assert MyApp.Calculator.add(1, 2) == 3
  end
end

# async: false — test module runs alone (serialized)
# Required when: tests use Registry, PubSub, global ETS, or named GenServers
defmodule MyApp.EventsTest do
  use ExUnit.Case, async: false

  test "broadcasts events" do
    Phoenix.PubSub.subscribe(MyApp.PubSub, "topic")
    MyApp.Events.broadcast(:something)
    assert_receive {:something}
  end
end

Running Tests

mix test                              # All tests
mix test test/my_module_test.exs      # Single file
mix test test/my_test.exs:42          # Single test by line number
mix test --trace                      # Verbose output
mix test --max-failures 3             # Stop after 3 failures
mix test --only performance           # Only @tag :performance tests
mix test --exclude performance        # Skip performance tests
mix test --include integration        # Include @tag :integration tests

Test Tags

defmodule MyApp.PerformanceTest do
  use ExUnit.Case, async: false

  @moduletag :performance       # Tag entire module

  @tag :slow
  test "processes 10k items" do
    # ...
  end
end

Mox — Behaviour Mocking

Mox enforces that mocks implement a behaviour contract.

Setup (test/support/mocks.ex):

Mox.defmock(MockQdrant, for: MyApp.QdrantBehaviour)
Mox.defmock(MockSearch, for: MyApp.SearchBehaviour)

In test:

defmodule MyApp.IndexerTest do
  use ExUnit.Case, async: true
  import Mox

  setup :verify_on_exit!   # Ensures all expected calls were made

  test "indexes a file" do
    MockQdrant
    |> expect(:upsert_points, fn points -> {:ok, length(points)} end)
    |> stub(:health_check, fn -> :ok end)

    assert {:ok, _} = MyApp.Indexer.index_file("lib/foo.ex")
  end
end

• expect/3 — must be called exactly N times (default 1)
• stub/3 — can be called any number of times
• allow/3 — share mock expectations across processes (needed for async)

Inject mock via application config (not module attribute):

# config/test.exs
config :my_app, qdrant_client: MockQdrant

# In code
qdrant = Application.get_env(:my_app, :qdrant_client, MyApp.QdrantClient)

Database Sandbox (Ecto)

# test_helper.exs
Ecto.Adapters.SQL.Sandbox.mode(MyApp.Repo, :manual)

# In test
defmodule MyApp.UserTest do
  use MyApp.DataCase    # sets up sandbox checkout

  test "creates user" do
    assert {:ok, user} = MyApp.Accounts.create_user(%{name: "Alice"})
    assert user.name == "Alice"
  end
end

Assertions

# Value assertions
assert result == {:ok, 42}
refute result == {:error, _}

# Pattern matching assertions
assert {:ok, %{name: "Alice"} = user} = MyApp.create_user(params)

# Process message assertions
assert_receive {:event, :done}, 1000   # wait up to 1000ms
refute_receive {:error, _}, 100        # ensure no error message in 100ms

# Exception assertions
assert_raise ArgumentError, fn -> MyApp.bad_call() end
assert_raise ArgumentError, ~r/invalid/, fn -> MyApp.bad_call() end

# Approximate equality
assert_in_delta result, 3.14, 0.01

Performance Testing Pattern (from ElixirNexus)

defmodule MyApp.PerformanceTest do
  use ExUnit.Case, async: false
  @moduletag :performance

  defp measure(fun) do
    {micros, result} = :timer.tc(fun)
    {result, micros / 1000}  # return ms
  end

  defp assert_under(actual_ms, max_ms) do
    assert actual_ms < max_ms,
      "Expected under #{max_ms}ms but took #{Float.round(actual_ms, 2)}ms"
  end

  test "search completes in under 50ms" do
    {_result, ms} = measure(fn -> MyApp.Search.search("query") end)
    assert_under(ms, 50)
  end

  test "statistical benchmark" do
    times = for _ <- 1..100, do: elem(measure(fn -> MyApp.fast_op() end), 1)
    p95 = Enum.sort(times) |> Enum.at(round(100 * 0.95) - 1)
    assert_under(p95, 10)
  end
end

Common Mistakes

• Using async: true with shared named processes or ETS causes flaky tests
• Forgetting verify_on_exit! with Mox — expected calls go unverified
• Using assert_receive without a timeout — default is 100ms which can be flaky in CI
• Not flushing mailbox between tests when using PubSub: add flush_mailbox() helper