Describing testing with the phrase âRed, Green, Refactorâ makes it seem fairly straightforward. Most people interpret this as the process of writing some failing tests, getting those tests to pass, and then cleaning up the code without causing the tests to fail again. This general assumption is exactly correct, but a common misconception is how much work needs to be done between each phase of this cycle.
For example, if we try to solve our whole problem all in one big chunk, add tests to verify that it works, then clean up our code, we end up with implementations that are very difficult to test, and even more challenging to refactor. The following example illustrates just how bad this problem can get if youâre not careful. Itâs from some payroll management code I wrote in a hurry a couple of years ago:
def time_data_for_week(week_data,start,employee_id)
data = Hash.new { |h,k| h[k] = Hash.new }
%w[M T W TH F S].zip((0..6).to_a).each do |day,offset|
date = (start + offset.days).beginning_of_day
data[day][:lunch_hours] = LunchTime.find(:all, conditions:
["employee_id = ? and day between ? and ?",
employee_id, date, date + 1.day - 1.second] ).inject(0) { |s,r|
s + r.duration
}
times = [[:sick_hours , "Sick" ],
[:personal_hours, "Personal"],
[:vacation_hours, "Vacation"],
[:other_hours, "Other" ]]
times.each do |a,b|
data[day][a] = OtherTime.find(:all, conditions:
["employee_id = ? and category = '#{b}' and date between ? and ?",
employee_id, date, date + 1.day - 1.second] ).inject(0) { |s,r|
s + r.hours
}
end
d = week_data.find { |d,_| d == date }
next unless d
d = d[-1]
data[day].merge!(
regular_hours: d.inject(0) { |s,e|
s + (e.end_time ? (e.end_time - e.start_time) / 3600 : 0)
} - data[day][:lunch_hours],
start_time: d.map { |e| e.start_time }.sort[0],
end_time: d.map { |e| e.end_time }.compact.sort[-1]
)
end
sums = Hash.new(0)
data.each do |k,v|
[:regular_hours, :lunch_hours, :sick_hours,
:personal_hours, :vacation_hours, :other_hours].each { |h|
sums[h] += v[h].to_f }
end
Table(:day,:start_time,:end_time,:regular_hours,:lunch_hours,
:sick_hours,:personal_hours,:vacation_hours, :other_hours) do |t|
%w[M T W TH F S].each { |d| t << {day: d}.merge(data[d]) }
t << []
t << { day: "<b>Totals</b>" }.merge(sums)
end
endWhen you looked at the preceding example, did you have an easy time understanding it? If you didnât, you donât need to worry, because I can hardly remember what this code does, and Iâm the one who wrote it. Though it is certainly possible to produce better code than this without employing TDD, itâs actually quite difficult to produce something this ugly if you are writing your tests first. This is especially true if you manage to keep your iterations nice and tight. The very nature of test-driven development lends itself to breaking your code up into smaller, simpler chunks that are easy to work with. Itâs safe to say that we donât see any of those attributes here.
Now that weâve seen an example of what not to do, we can investigate the true benefits of TDD in the setting of a real project. What follows is the process that I went through while developing a simple feature for the Prawn PDF generation library. But first, a small diversion is necessary.
The code weâre about to look at was originally part of Prawnâs early support for inline styling, which allows users to make use of bold and italic typefaces within a single string of text. In practice, these strings look very similar to the most basic HTML markup:
"This is a string with <b>bold, <i>bold italic</i></b> and <i>italic</i> text"
Although the details of how Prawn actually converts these strings into stylized text that can be properly rendered within a PDF document are somewhat gory, the process of breaking up the string and parsing out the style tags is quite straightforward. Weâll focus on this aspect of things, stepping through the design and development process until we end up with a simple function that behaves as follows:
>> StyleParser.process("Some <b>bold</b> and <i>italic</i> text")
=> ["Some ", "<b>", "bold", "</b>", " and ", "<i>", "italic", "</i>", " text"]This example demonstrates the final product, but the initial pass at things wasnât so polished. I started by considering the possibility of passing all the strings rendered in Prawn through style processing, so the initial case I thought of was actually to allow the method to return the string itself when it did not detect any style data. My early example looked something like this:
class TestInlineStyleParsing < Test::Unit::TestCase
must "simply return the string if styles are not found" do
@pdf = Prawn::Document.new
assert_equal "Hello World", @pdf.parse_inline_styles("Hello World")
end
endMy initial functionality looked something like this:
class Prawn::Document
def parse_inline_styles(text)
text
end
endThis caused my example to run without failure, and is quite possibly the most boring code imaginable. However, working in small steps like this helps keep things simple and also allows you to sanity-check that things are working as expected. Seeing that this was the case, I was able to move forward with another set of examples. The modified test case ended up looking like this:
class TestInlineStyleParsing < Test::Unit::TestCase
must "simply return the string if styles are not found" do
@pdf = Prawn::Document.new
assert_equal "Hello World", @pdf.parse_inline_styles("Hello World")
end
must "parse italic tags" do
@pdf = Prawn::Document.new
assert_equal ["Hello ", "<i>", "Fine", "</i>", " World"],
@pdf.parse_inline_styles("Hello <i>Fine</i> World")
end
must "parse bold tags" do
@pdf = Prawn::Document.new
assert_equal ["Some very ", "<b>", "bold text", "</b>"],
@pdf.parse_inline_styles("Some very <b>bold text</b>")
end
endDespite the fact that Iâm writing a book titled Ruby Best Practices, I freely admit that I write some dumb code sometimes. For evidence, we can look at the first bit of code that made this example work:
def parse_inline_styles(text)
require "strscan"
sc = StringScanner.new(text)
output = []
last_pos = 0
loop do
if sc.scan_until(/<\/?[ib]>/)
pre = sc.pre_match[last_pos..-1]
output << pre unless pre.empty?
output << sc.matched
last_pos = sc.pos
else
output << sc.rest if sc.rest?
break output
end
end
output.length == 1 ? output.first : output
endThatâs way longer than it needs to be. Luckily, a useful aspect of using automated behavior verification is that it is helpful during refactoring. I had planned to send this code out to the ruby-talk mailing list so that I could learn the elegant solution that I knew must exist but couldnât quite muster in my first pass. Before I could do that though, I needed to add another example to clarify the intended behavior:
must "parse mixed italic and bold tags" do
@pdf = Prawn::Document.new
assert_equal ["Hello ", "<i>", "Fine ", "<b>", "World", "</b>", "</i>"],
@pdf.parse_inline_styles("Hello <i>Fine <b>World</b></i>")
endSome folks might make the claim that a good test suite makes it easier to communicate with customers, but Iâve never been too sure about that. What I do know is that tests are downright awesome for describing a problem to your fellow developers. Within minutes of posting my examples to ruby-talk, I had a much better implementation in hand:[1]
def parse_inline_styles(text)
segments = text.split( %r{(</?.*?>)} ).reject {|x| x.empty? }
segments.size == 1 ? segments.first : segments
endRunning the examples showed that this code accomplished what my earlier code did, as there were no failures. However, your code is only as correct as the examples you choose, and as it turns out, this code gave me more than I bargained for. It parsed out anything within angle braces, meaning itâd pull out the tags in the following string:
"Hello <indigo>Charlie</indigo>"
Though this might be useful in some situations, I really wanted to parse out only the two specific tags I planned to handle, so I added an example to cover this:
must "not split out other tags than <i>, <b>, </i>, </b>" do
@pdf = Prawn::Document.new
assert_equal ["Hello <indigo>Ch", "</b>", "arl", "</b>", "ie</indigo>"],
@pdf.parse_inline_styles("Hello <indigo>Ch</b>arl</b>ie</indigo>")
endThis new example resulted in a failure, as expected. The required change was simple, and caused everything to pass again:
def parse_inline_styles(text)
segments = text.split( %r{(</?[ib]>)} ).delete_if{|x| x.empty? }
segments.size == 1 ? segments.first : segments
endI originally planned to pass through this function every string that Prawn attempted to render, and this influenced the way the initial interface was specified. However, later I realized that it would be better to check to see whether a string had any style tags in it before attempting to parse it. Because the process of rendering the text is handled in two very different ways depending on whether there are inline styles present, I needed to handle only the case when there were tags to be extracted in my parser:
def parse_inline_styles(text)
text.split( %r{(</?[ib]>)} ).delete_if{|x| x.empty? }
endThis cleanup caused one of my examples to fail, because it broke the old default behavior:
1) Failure: test_simply_return_the_string_if_styles_are_not_found(TestInlineStyleParsing) [...]: <"Hello World"> expected but was <["Hello World"]>.
As this example was no longer relevant, I simply removed it and was
back under the green light. But I still needed a related feature, which
was the ability to test whether a string
needed to be parsed. I considered making this a private method on
Prawn::Document,
but it led to some ugly code:
must "be able to check whether a string needs to be parsed" do @pdf = Prawn::Document.new assert ! @pdf.send(:style_tag?, "Hello World") assert @pdf.send(:style_tag?, "Hello <i>Fine</i> World") end
Most of the time when I need to use send() to call a private method in one of my
tests, I try to rethink my interface. Sometimes itâs a necessary evil, but
most of the time it just means that things
are looking to be refactored. When I first added Document#parse_inline_styles, it didnât
concern me much to add a single utility method for this purpose. However,
once I found out that I needed an additional helper method, I began to
rethink the problem. I realized things would look better if I wrapped the
code up in a module.
I updated my examples to reflect this change, and cleaned them up a
bit by adding a setup method, which
gets run before each individual test:
class TestInlineStyleParsing < Test::Unit::TestCase
def setup
@parser = Prawn::Document::Text::StyleParser
end
must "parse italic tags" do
assert_equal ["Hello ", "<i>", "Fine", "</i>", " World"],
@parser.process("Hello <i>Fine</i> World")
end
must "parse bold tags" do
assert_equal ["Some very ", "<b>", "bold text", "</b>"],
@parser.process("Some very <b>bold text</b>")
end
must "parse mixed italic and bold tags" do
assert_equal ["Hello ", "<i>", "Fine ", "<b>", "World", "</b>", "</i>"],
@parser.process("Hello <i>Fine <b>World</b></i>")
end
must "not split out other tags than <i>, <b>, </i>, </b>" do
assert_equal ["Hello <indigo>Ch", "</b>", "arl", "</b>", "ie</indigo>"],
@parser.process("Hello <indigo>Ch</b>arl</b>ie</indigo>")
end
must "be able to check whether a string needs to be parsed" do
assert @parser.style_tag?("Hello <i>Fine</i> World")
assert !@parser.style_tag?("Hello World")
end
endBecause these features didnât really rely on anything within
Prawn::Document, it made me happy to
give them a home of their own, ready to be expanded later as needed. I
created the module and dropped in the trivial check that made up the
style_tag? feature:
module StyleParser
extend self
def process(text)
text.split( %r{(</?[ib]>)} ).delete_if{|x| x.empty? }
end
def style_tag?(text)
!!(text =~ %r{(</?[ib]>)})
end
endWith the tests passing, I snuck in one more bit of cleanup under the green light, just to make things a little more DRY:[2]
module StyleParser
extend self
TAG_PATTERN = %r{(</?[ib]>)}
def process(text)
text.split(TAG_PATTERN).delete_if{|x| x.empty? }
end
def style_tag?(text)
!!(text =~ TAG_PATTERN)
end
endWith these two simple features in hand, I was then ready to work on implementing the inline styling support in Prawn, which I can assure you was far less pleasant to hack together.[3] Even though this example was quite simple, it captures the entire process of evolving a feature by using progressively tweaked examples from start to finish. Although the end result is an automated safety net that verifies that my methods behave as Iâve specified them, you can see that the process of problem discovery, refactoring, and iterative design are the true fruits of test-driven development. This is what justifies spending time writing tests that are often longer than your implementation. The resulting examples are mostly a helpful side effect; the power of this technique is in what insight you gain through writing them in the first place.
Now that weâve seen the process in action, weâll take a step back and go over some testing fundamentals. Although this stuff may be familiar to folks who are already accustomed to TDD, it doesnât hurt to brush up on the essentials, as they form a foundation for the more advanced stuff that weâll tackle a little later.
Get Ruby Best Practices now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.
