Test assertion failure with explicit reason message

What this failure means

A test case assertion failed with an explicit reason message. The test ran but the expected condition did not hold, producing a deterministic failure reason that names the broken expectation.

Symptoms

Faultline looks for one or more of these log fragments:

SUITE:.*failed
SUITE_.*failed
failed.*Reason:
Reason: expecting
Reason: expected_
init_per_group failed Reason
assertion failed: expected
AssertionError: expected

Diagnosis

Test assertion failures provide explicit reason messages that name what was expected versus what occurred. Common patterns:

• Erlang EUnit/Common Test: SUITE_NAME:test_function failed ... Reason: expected_value_got_other
• Queue/messaging tests: expecting_nack_got_ack, expected_empty_got_n_messages
• State machine tests: expected_state_X_got_state_Y

The Reason: message tells you exactly what the test was checking.

Common causes:

• Logic error — the implementation changed and now produces different output than the test expects.
• Test data setup — the test fixture or seed data does not match the test assumption.
• Timing or ordering — concurrent code or queue processing order changed.
• API change — a dependency changed its behavior and the code did not adapt.

Fix steps

1. Read the Reason: message carefully — it names both the expected and actual state.
2. Locate the failing test in the source:

   grep -r "expected_.*_got_" src/test/ eunit_SUITE.erl
   

3. Run the test in isolation to reproduce:

   erl -name test@localhost -s mymodule test_function
   rebar3 eunit -m mymodule
   

4. Add debug output or inspect the intermediate state:
   • Print the actual state before the assertion
   • Check if external dependencies behave as expected
5. Fix either the implementation to match the test, or update the test if the new behavior is correct and documented.

Validation

• Run the failing test again — it should pass.
• Run the full test suite to ensure no regressions.

Why it matters

Test assertions with explicit reasons are deterministic and reproducible. They stop the pipeline but pinpoint exactly what broke, making fixes straightforward.

Prevention

• Write tests with descriptive assertion messages that name both the expected and actual values.
• Run tests locally before pushing:

  rebar3 eunit
  rebar3 ct  # for Common Test
  

• Use parameterized tests to cover multiple scenarios but keep each test focused on a single behavior.

Try it locally

rebar3 eunit
rebar3 ct
rebar3 eunit

How Faultline detects it

Use faultline explain test-assertion-with-reason to see the full playbook.

faultline analyze build.log
faultline explain test-assertion-with-reason

Generated from playbooks/bundled/log/test/test-assertion-with-reason.yaml. Do not edit directly.