Cultivate Explicit Diagnostic Tools to Debug Test Failures

A big part of the carrying cost of system tests is the time it takes to diagnose why they are failing when we don’t believe the feature being tested is actually broken. The assertions available to Rails provide only rudimentary assistance. The team will eventually learn to use puts page.html as a diagnostic tool, but let’s take time now to make one that works a bit better.

Let’s wrap puts page.html in a method called with_clues. The with_clues method will take a block of code and, if there is any exception, produce some diagnostic information (currently the page’s HTML) and re-raise the exception. This will be a foothold for adding more useful diagnostic information later. We’ll add this in test/application_system_test_case.rb so that all tests now and in the future can access it.

Let’s put this in a separate file and module and include that into ApplicationSystemTestCase. As we build up a library of useful diagnostic tools, we don’t want our test/application_system_test_case.rb file to get out of control. We’ll put this in test/support/with_clues.rb file: