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 62The 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
