liveBook · Manning

Descriptive assertion

As explained in Effective Behavior-Driven Development

A pattern that includes diagnostic context in assertion failure messages.

A failed automated scenario should tell the team what went wrong, not merely report two unequal values. A descriptive assertion puts the context needed for diagnosis directly in its failure message. This matters when a failing regression test interrupts a CI pipeline and the team needs to investigate quickly. section 19.1 section 19.7

Which order was taken?

A kitchen should take the earliest order first. “Expected 1000, actual 1001” identifies a mismatch but leaves the investigator to find what those numbers mean. A more useful failure says that order #1000 was placed at 13:33:47, while the order taken, #1001, was placed at 13:45:30. The message connects the failure to the business rule. section 19.1

Listing 19.2 Improved error message
*** StepDefinitions/OrderProcessingStepDefinitions.cs ***
[Then("the earliest order received should be taken")]
public void ThenTheEarliestOrderReceivedShouldBeTaken()
{
  Assert.IsNotNull(takenOrder, "Order was not taken");
  var earliestOrder = placedOrders.OrderBy(o => o.PlacingTime)
    .First();

  Assert.AreEqual(earliestOrder.OrderNo, takenOrder.OrderNo, 
      $"Expected the earliest order #{earliestOrder.OrderNo} (placed at 
    ➥ {earliestOrder.PlacingTime}) but got order #{takenOrder.OrderNo} 
    ➥ (placed at {takenOrder.PlacingTime})");    #A
}

*** Test execution result ***
Message:
Assert.AreEqual failed. Expected:<1000>. Actual:<1001>.    #B
  'expected' expression: 'earliestOrder.OrderNo', 
  'actual' expression: 'takenOrder.OrderNo'. 
  Expected the earliest order #1000 (placed at 13:33:47) but got 
➥ order #1001 (placed at 13:45:30)

Stack Trace:
OrderProcessingStepDefinitions.ThenTheEarliestOrderReceivedSho...() line 62

The improved assertion reports both order numbers and placing times alongside the failed comparison. section 19.1

Design the message by asking what someone would need to diagnose this particular failure. Check that information when a step first fails in the Red-Green-Refactor loop. A fluent assertion library can help produce readable errors, but the team should use a consistent assertion style. If essential context is too large or is not text, a supplementary attachment can carry it instead. section 19.1 section 19.7

How Effective Behavior-Driven Development covers it

How deep it goes
Works through a default failure, a contextual message, and a fluent-library alternative; leaves oversized or nontextual evidence to attachments.
Examples
Compares order-number-only failures with messages naming the expected and taken orders and their placing times.
What it assumes
Uses a BDD Then-step assertion to demonstrate the pattern without requiring a particular assertion library.
What you can do after
Diagnose/debug with it by designing assertion messages that expose the values and business context needed to investigate failures.
How it connects
Connects assertion messages with BDD automation, continuous integration, Red-Green-Refactor, and supplementary attachments.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Effective Behavior-Driven Development. The section links point to the parts of the book it draws on.