When mocking and dynamic typing travel in the same cart, the riders believe nothing can stand in their way. Their movements become headlong - faster and faster and faster. They put aside all thoughts of obstacles and forget the precipice does not show itself to the man in a blind rush until it’s to late.

With the release of the Mac App Store, it was clear that Apple wanted users managing third-party software much as they do on iOS devices: blessed apps vetted by Apple. Marco Arment has written in detail about how this approval process isn’t that bad and that it’s a net gain for users:

First and foremost, the review process has created a level of consumer confidence and risk-taking that has enabled the entire iOS app market to be far bigger and healthier than anyone expected. Average people — the same people who have been yelled at for decades for clicking on the wrong button on the wrong incomprehensible dialog box and messing up their computers — can (and do) confidently buy large quantities of inexpensive apps impulsively, without having to worry that any of them will “break” their iPhones or iPads, rip them off, destroy their data, or require them to embarrassingly visit the corporate IT department, the Geek Squad, or their computer-savvy relatives (us) for help. Part of this is due to the highly sandboxed architecture enforced by the OS, but a big part is the app review process.

When Lion was released, there was a general feeling of fear amongst developers that, someday soon, the App Store would be the only way to get apps onto your Mac. This would, in turn, destroy many useful apps that would just never make it through the review process (and, presumably, make development on a Mac much more difficult or impossible). With what we know about Mountain Lion, it’s clear that this dystopian future is not what Apple has in mind. Gatekeeper is the proof.

John Gruber sums Gatekeeper up nicely in his piece on Mountain Lion (emphasis mine):

It’s a system whereby developers can sign up for free-of-charge Apple developer IDs which they can then use to cryptographically sign their applications. If an app is found to be malware, Apple can revoke that developer’s certificate, rendering the app (along with any others from the same developer) inert on any Mac where it’s been installed. In effect, it offers all the security benefits of the App Store, except for the process of approving apps by Apple.

Finally, the feature can be entirely disabled:

I think Apple would prefer “Mac App Store only” as the default. Honestly, so would I. I’d love to send my parents or sister a Mac that they simply can’t fuck up. Many grey hairs on my head are attributable to the trouble my family has gotten into with their PCs. Granted, it’s harder to get into this trouble with a Mac, but it’s still possible. And, as the Mac starts to take over more and more of the PC market, it will increasingly become a target for malware.

I think it’s hard to argue that for “regular” users (and those of us doomed to support them), Gatekeeper is a net positive.

What about us developers? Is this a win for us? There’s certainly a few unknowns:

• How does software installed via “traditional” means interact with this system? If I download and compile the latest version of Ruby, but have Gatekeeper on, will it work?
• What about software written in a scripting language? What if I gem install a Ruby command-line application (something I have a vested interest in being able to do), will it work?
• Will the option to “allow applications downloaded from…anywhere” go away in a future version of OS X?

It’s hard to predict the answers to these questions without knowing more about how Gatekeeper works. I do think that the mere existence of Gatekeeper’s allowance of signed-but-not-from-the-App-Store-apps demonstrates Apple’s understanding that developers and “power users” are important to the platform. Think about it: what’s in it for Apple to disallow unsigned applications completely? What would Apple have to gain by making it difficult (or impossible) to write non-Mac software on a Mac?

Don’t forget, many iOS and Mac apps are backed by web services written using tools like Ruby on Rails, PHP, or Java. If Apple were to make it difficult (or impossible) to write, say, a Rails app on a Mac, it would be much more difficult to write an iOS app; the developer would need a second machine to write the web service. It just doesn’t make sense.

So, I think Gatekeeper is a win for average users, a win for geeks, and not a concern for developers. As such, I’m in favor of it.

In non-test code, pretty much any literal that isn’t 0, 1, -1, the empty string, nil/null, or some universal constant like 60 (number of seconds in a minute), is a magic value. A naked literal just sitting out there with no context makes code hard to understand, and we usually whisk them away inside a constant or injected value. Suppose we come across this code:

1
2
3
4
5

if percentage < 0.75
  show_graph
else
  show_no_data
end

We want to know what 0.75 actually means. If we’d used a constant, it would be clearer, like so:

1
2
3
4
5

if percentage > THRESHOLD_FOR_DATA_DISPLAY
  show_graph
else
  show_no_data
end

Now we know that we’re comparing our percentage against a threshold and not some arbitrary value.

Tests, on the other hand, require a lot of literals, because we tend to be setting up very specific conditions, and that’s much easier with an example of some input. Here’s a test for our Saluation class that we’ve seen before:

1
2
3
4
5
6
7
8
9

def test_full_name
  # Given
  person = Person.new("David","Copeland",:male)
  salutation = Salutation.new(person)
  # When
  greeting = salutation.greeting
  # Then
  assert_equal "Hello, David!",greeting
end

We have four magic values:

• "David"
• "Copeland"
• :male
• "Hello, David!"

Do these all need to be in there? Which ones are actually relevant, and which are true magic values that we should eliminate?

You’ll recall that in the first post on clean tests, we made this test clearer via method extraction, like so:

1
2
3
4
5
6
7
8
9
10
11

def test_full_name
  # Given
  person = person_with_full_name("David")
  salutation = Salutation.new(person)

  # When
  greeting = salutation.greeting

  # Then
  assert_equal "Hello, David!",greeting
end

Essentially, we’ve hidden the fact that the last name and gender don’t matter inside the person_with_full_name method. Some developers would object to this, preferring to have each test method stand on its own, without chasing down lots of helpers. This is a fair point, so let’s get rid of some irrelevant magic strings another way:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

def test_full_name
  # Given
  person = Person.new("David",any_string,any_gender)
  salutation = Salutation.new(person)

  # When
  greeting = salutation.greeting

  # Then
  assert_equal "Hello, David!",greeting
end

private

def any_string
  Faker::Lorum.words(5).join('')
end

def any_gender
  rand(2) == 1 ? :female : :male
end

We’ve still got helper methods (any_string and any_gender), but they’re tiny and they convey some information: the last name and the gender can be anything; they don’t matter. If you aren’t familiar with faker, it’s a handy gem for generating nonsense within certain parameters. This is perfect for creating values that don’t matter.

Does “David” matter? It matters more than the last name and gender, since it will show up in our greeting, but the first name could just as easily be “Mark” or “Mary”. So, let’s eliminate this magic value as well:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

def test_full_name
  # Given
  first_name = any_string
  person = Person.new(first_name,any_string,any_gender)
  salutation = Salutation.new(person)

  # When
  greeting = salutation.greeting

  # Then
  assert_equal "Hello, #{first_name}!",greeting
end

private

def any_string
  Faker::Lorum.words(5).join('')
end

def any_gender
  rand(2) == 1 ? :female : :male
end

Now, we’re talking! Read the test, in English: “first name is any string, a person has that as their first name, with any string as their last and any gender as their gender. Make a salutation for that person, and get the greetting. The greeting should equal ‘Hello’ plus the first name”. We’ve come very close to encoding a specification of our Salutation class without using a special test framework or magic values, and the entire test is in the test method.

Just to hammer this home, lets port over the test that handles the case when you have no first name:

1
2
3
4
5
6
7
8
9

def test_last_name_only_male
  # Given
  person = Person.new(nil,"Copeland",:male)
  salutation = Salutation.new(person)
  # When
  greeting = salutation.greeting
  # Then
  assert_equal "Hello, Mr. Copeland!",greeting
end

Here, :male is very relevant, but "Copeland" doesn’t particularly matter:

1
2
3
4
5
6
7
8
9
10

def test_last_name_only_male
  # Given
  last_name = any_string
  person = Person.new(nil,last_name,:male)
  salutation = Salutation.new(person)
  # When
  greeting = salutation.greeting
  # Then
  assert_equal "Hello, Mr. #{last_name}!",greeting
end

With syntax highlighing, the relevant parts of the test literally jump out at you. :male and nil are the only literals in this test, and they are therefore important.

By removing as many magic values as possible, and replacing them with the most general possible value to satisfy the test, we can make it crystal clear what’s going on in each test.

Can we carry this concept further? Consider the variable person in the last test. Is this variable relevant? Somewhat. It is as relevant as salutation or greeting? No. salutation is the object under test, and greeting is the value we’re testing. Further, last_name is a value that’s part of the expected result. To make this distinction clear, we can take advantage of Ruby’s ability to define fields on the fly:

1
2
3
4
5
6
7
8
9
10

def test_last_name_only_male
  # Given
  @last_name = any_string
  person = Person.new(nil,last_name,:male)
  @salutation = Salutation.new(person)
  # When
  @greeting = @salutation.greeting
  # Then
  assert_equal "Hello, Mr. #{@last_name}!",@greeting
end

This might seem superfluous in such a small test, but in a larger, more complex test (especially one dealing with a lot of mocks), this can be really helpful. You know that so-called “at” variables are important, and their values are meaningful across the “Given/When/Then” of the test, however local variables or short-lived and can be skimmed over when first understanding the test.

Setup/Teardown

Let’s have a brief word on setup and teardown methods. I’ve seen a lot of tests use the setup method to set up various mock expectations, or do other test-specific setup. A problem arises when you need to add a test that doesn’t require that setup, or perhaps requires some additional setup. This causes two problems:

• You must now piece together what the “Givens” of a particular test are
• You are setting up conditions that aren’t relevant to all tests

Using nested contexts in tools like RSpec exacerbates this greatly, and it’s not uncommon to have setup code littered throughout the file.

I would suggest you keep all test-specific setup out of the setup method entirely. Ideally, you won’t even have one. Occasionally, you’ll need to set up something around global variables that can’t be easily injected into your code. More commonly, you’ll have a teardown method to make sure the next test has a clean slate (e.g. clean up temp files, restore configuration to default, etc.). These are OK. What you want to avoid is having any “Givens” or “Thens” inside these methods.

Conclusion

This brings us to the end of my whirlwind tour of clean tests. The overall goal is to prioritize comprehensibility of tests without sacrificing too much ease of creation. Your tests are going to be read and modified a lot more than written. In summary:

• Structure your tests in three parts: Given (setup), When (action), Then (assertions).
• Mock expectations are assertions, so put them in the “Then” block, and repeat the Given/When/Then if you need to due to your mocking framework.
• Don’t duplicate test code that’s the same by design, but do duplicate it if it’s the same by happenstance.
• Values important to a test should be variables.
• Values irrelevant to a test should be hidden in “any” style methods.
• If these rules muddy your tests, break them.

Afterword

I’ve been working this way for several months, and developed the clean_test gem to help. I’ll introduce that in a future blog post, but look at some of the tests written using these techniques. I tend to prefer knowledge be stored digitally, and not in my brain, so these techniques really help. Try writing your next set of tests like this and see what you think!

In Java, you are basically stuck with this, but in Ruby (or any OO language that supports closures/blocks/functions), we can fight this by using Procs instead of classes.

SOLIDifying some code

First, let’s take some code that needs refactoring and see what it looks like with classes. We’ll look at a very simple base class for handling events in a system based on Resque. Our base class allows us to do two things that a generic Resque event can’t: retry events later, and queue arbitrary events. Let’s have a look at the code¹:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

class Event::Base

  def self.perform(params)
    self.new.perform(params)
  end

  def perform(params)
    raise "subclass must implement"
  end

protected

  def self.queue_event(klass,options)
    Resque.enque(klass,options.merge({ :queued_at => Time.now }))
  end

  def self.requeue_later(params)
    new_params = { :attempt_number => 0 }.merge(params)
    new_params[:attempt_number] += 1

    raise "Requeued too many times" if new_params[:attempt_number] > 5

    sleep(new_params[:attempt_number])
    queue_event(class,new_params)
  end
end

We might use this like so:

1
2
3
4
5
6
7
8
9
10

class RenameEvent < Event::base
  def perform(params)
    if person = Person.find_by_id(params[:person_id]).nil?
      requeue_later(params)
    else
      person.name = params[:name]
      person.save!
    end
  end
end

Our base class is doing too much. It’s OK for it to provide the queuing and re-queuing functionality, but it shouldn’t be implemented there. Further, there’s aspects of how the functionality is implemented that we might want to be able to change in our subclasses. This is the perfect application for dependency inversion.

In our naive approach, we’ll make one class for each function we have, namely:

• A class to queue events onto Resque, adding in the queued_at timestamp
• A class to orchestrate requeuing events, failing after a certain number of attempts
• A class to sleep and perform the actual requeuing
• Our base class to provide access to these features

Let’s have a look:

1
2
3
4
5

class Queuer
  def queue(klass,options)
    Resque.enque(klass,options.merge({ :queued_at => Time.now }))
  end
end

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

class Requeuer
  def initialize(requeue_strategy,max_attempts=5)
    @requeue_strategy = requeue_strategy
    @max_attempts = max_attempts
  end

  def requeue(klass,options)
    new_params = { :attempt_number => 0 }.merge(params)
    new_params[:attempt_number] += 1

    raise "Requeued too many times" if new_params[:attempt_number] > @max_attempts

    @requeue_strategy.requeue(klass,new_params[:attempt_number],options)
  end
end

1
2
3
4
5
6
7
8
9
10

class RequeueStrategy
  def initialize(queuer)
    @queuer = queuer
  end

  def requeue(klass,attempt_number,options)
    sleep(attempt_number)
    @queuer.queue(klass,options)
  end
end

Whew! Now, to use all this, our base class becomes:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

class Event::Base

  def initialize(requeuer=nil)
    @requeuer = requeuer || Requeuer.new(RequeueStrategy.new(Queuer.new))
  end

  def self.perform(params)
    self.new.perform(params)
  end

  def perform(params)
    raise "subclass must implement"
  end

protected

  def requeue_later(params)
    @requeuer.requeue(self.class,params)
  end
end

Our base class is a lot cleaner, and we can now test it more easily without mocks making things difficult.

But, we’re firmly in the Kingdom of Nouns, e.g. queuer.queue(). We’d like to keep our code nicely designed, but get rid of the superfluous naming and structure around the tiny bits of code we have. Let’s use Procs.

Procs instead of classes

The easiest class to convert to a Proc is going to be Queuer, since it has no real dependencies and is just a wrapper around a very simple line of code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

class Event::Base

  QueueEvent = lambda { |klass,params|
    Resque.enque(klass,options.merge({ :queued_at => Time.now }))
  }

  def initialize(requeuer=nil)
    @requeuer = requeuer || Requeuer.new(RequeueStrategy.new(QueueEvent))
  end

  def self.perform(params)
    self.new.perform(params)
  end

  def perform(params)
    raise "subclass must implement"
  end

protected

  def requeue_later(params)
    @requeuer.requeue(self.class,params)
  end
end

RequeueStrategy now becomes:

1
2
3
4
5
6
7
8
9
10

class RequeueStrategy
  def initialize(queue_event)
    @queue_event = queue_event
  end

  def requeue(klass,attempt_number,options)
    sleep(attempt_number)
    @queue_event.call(klass,options)
  end
end

Notice that we’re using the name queue_event instead of queuer. A Proc isn’t, conceptually, a thing, but an action that we’re passing around, so we name it as such.

Of course, RequeueStrategy itself isn’t much code; can we convert that? The tricky part is that RequeueStrategy requires the ability to queue events and thus needs a Queuer. We pass this in the constructor, which a Proc doesn’t really have (at least conceptually). Instead, we’ll pass the queueing code in as a parameter to our newly re-made SleepThenRequeue Proc, which is now part of our base class.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

class Event::Base

  SleepThenRequeue = lambda { |queue_event,klass,attempt_num,options|
    sleep(attempt_number)
    queue_event.call(klass,options)
  }

  QueueEvent = lambda { |klass,params|
    Resque.enque(klass,options.merge({ :queued_at => Time.now }))
  }

  def initialize(requeuer=nil)
    @requeuer = requeuer || Requeuer.new(QueueEvent,SleepThenRequeue)
  end

  def self.perform(params)
    self.new.perform(params)
  end

  def perform(params)
    raise "subclass must implement"
  end

protected

  def requeue_later(params)
    @requeuer.requeue(self.class,params)
  end
end

We now need to update Requeuer to hold onto the QueueEvent Proc so that it can pass it to the SleepThenRequeue Proc:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

class Requeuer
  def initialize(queue_event,requeue_event,max_attempts=5)
    @queue_event = queue_event
    @requeue_event = requeue_event
    @max_attempts = max_attempts
  end

  def requeue(klass,options)
    new_params = { :attempt_number => 0 }.merge(params)
    new_params[:attempt_number] += 1

    raise "Requeued too many times" if new_params[:attempt_number] > @max_attempts

    @requeue_event.call(@queue_event,klass,new_params[:attempt_number],options)
  end
end

Now, our system has all the flexbility, testability, and comprehensibility that we get from applying SOLID principles, but we don’t have any of the baggage and boilerplate of making actual classes that are mere wrappers for simple functionality.

Taking Advantage

Let’s see how this works be implementing a second requeuing strategy. Suppose a subclass wants to have retried events go onto a different queue, instead of sleeping and re-queuing. To enable this, we first make our base class a bit more configurable by introducing the method self.requeue_strategy, which returns a Proc. The base class’ implementation will simply return SleepThenRequeue.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

class Event::Base

  QueueEvent = lambda { |klass,params|
    Resque.enque(klass,options.merge({ :queued_at => Time.now }))
  }

  SleepThenRequeue = lambda { |queue_event,klass,attempt_num,options|
    sleep(attempt_number)
    queue_event.call(klass,options)
  }

  def initialize(requeuer=nil)
    @requeuer = requeuer || Requeuer.new(QueueEvent,self.class.requeue_strategy)
  end

  def self.perform(params)
    self.new.perform(params)
  end

  def perform(params)
    raise "subclass must implement"
  end

protected

  def self.requeue_strategy
    SleepThenRequeue
  end

  def requeue_later(params)
    @requeuer.requeue(self.class,params)
  end
end

Now, our subclass can return something else, but it won’t have to make an entire class to do so:

1
2
3
4
5
6
7
8
9
10

class SomeEvent < Event::Base

protected

  def self.requeue_strategy
    lambda { |queue_event,klass,attempt_num,options|
      queue_event.call(klass,options.merge(:queue => 'scheduled',
                                           :for => Time.now + attempt_num.minutes)
    }
  end

Of course, we’re not constrained by Procs; after all a Proc is just a structural type for an object that reponds to call. If we needed some really complex requeuing, we could make a class:

1
2
3
4
5

class ComplexRequeueingStrategy
  def call(queue_event,klass,attempt_num,options)
    # Do whatever
  end
end

This results in a much more flexible system that keeps ceremony, boilerplate, and noise to a minimum; the majority of our code is the “business logic” or “necessary complexity”.

Conclusions

Of course, we can take this too far. Suppose we made Requeuer into a Proc. It would start getting cumbersome, since it has so many dependent objects to manage; a class is actually helpful here².

Just because Ruby is object-oriented doesn’t mean that every bit of functionality has to live inside a method of a class. A Proc is tailor-made to hold functionality and pass it around, so don’t be afraid to use it if the situation warrants.

• Given - Establish the conditions under which the test will run
• When - Run the code under test
• Then - assert that the code did what you expect

This structure becomes problematic when using either mock objects or block-based asserts.

The Trouble with Mocks

When using mock objects in a test, you typically use a mocking framework (like mocha) to modify the behavior of objects the class-under-test collaborates with. You often test that the class-under-test made certain calls to its collaborators. Let’s look at an example.

Suppose we have an existing system and we wish to start recording some statistics, such as the number of times a method is called or how long a method takes to run. We’ve created a class, Statistics, that has some class methods on it to do the recording:

1
2
3
4
5
6

class Statistics
  # Add one to stat_name
  def self.count(stat_name)
    # ...
  end
end

We want to start using this class in our Salutation class to keep track of the number of times we’re calling #greeting. In order to add this in, we need to test that Salutation#greeting is calling Statistics.count. While we could set up a fake statistics server and examine it during our test, it’s more straightforward to use mocks.

1
2
3
4
5
6
7

class SalutationTest << TestCase
  def test_that_we_log_statistics
    saluation = Salutation.new(Person.new('David','Copeland',:male))
    Statistics.expects(:count).with('saluation.greeting.count')
    saluation.greeting
  end
end

What will happen is, if we don’t call Statistics.count("saluation.greeting.count") in the Salutation class, this test will fail. That’s what a mocking framework like mocha does for us.

Of course, there’s something odd about our test. There’s no call to any sort of assert method. The Given/When/Then is very unclear. For a real-world test that requires a lot more setup, it can be even more difficult to see what’s actually being tested. Essentially, the “Given/When/Then” is “out of order”:

1
2
3
4
5
6
7
8
9
10

class SalutationTest << TestCase
  def test_that_we_log_statistics
    # Given
    saluation = Salutation.new(Person.new('David','Copeland',:male))
    # Then
    Statistics.expects(:count).with('saluation.greeting.count')
    # When
    saluation.greeting
  end
end

Making our Intent Clear

We’d like to keep our test method in a canonical structure, or at least have some part of it follow the Given/When/Then structure. Unfortunately, our “Then”, the mock expectations, simply have to occur before the “When”. I think we can make it clearer, so let’s add a bit of code to help.

First, we’ll create a method named when_the_test_runs_then to clearly indicate that our expectations are part of our “Then”, and that they are going to be checked when the test runs, which happens later. We’ll also add a no-op method, assert_mocks_were_called that will allow our test to always have an assert and provide us with a way to be explicit about what’s being asserted. Although this “assert” method doesn’t do anything, it allows use to distinguish between “this test passes when the mocks are called as expected” from “I forgot to actually test for something”.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

class SalutationTest << TestCase
  def test_that_we_log_statistics
    when_the_test_runs_then {
      Statistics.expects(:count).with('saluation.greeting.count')
    }

    # Given
    saluation = Salutation.new(Person.new('David','Copeland',:male))
    # When
    saluation.greeting
    # Then
    assert_mocks_were_called
  end

  def when_the_test_runs_then; yield; end
  def assert_mocks_were_called; end
end

We’ve still deviated from our canonical structure, but the test reads better: “When the test runs then expect this method to be called; now let’s run the test”

Of course, we’ve just taken our first step out of “plain old Ruby” and created framework code. This is the price you pay for using mocks; testing with mocks complicate our tests. By using some lightweight “control structure” helper methods, we can at least make the intent clear.

Block-Based Asserts Disrupt, too

There’s another pattern we see in tests that disrupts the structure in much the same way that the use of mocks does. That disruption is block-based asserts, the most common of which is assert_raises. For example, suppose we’re testing that our Saluation class requires a non-nil Person in its constructor. We could test that like so:

1
2
3
4
5

def test_that_constructor_requires_a_person
  assert_raises ArgumentError do
    Salutation.new(nil)
  end
end

This test is weird for two reasons: the first is that the “Given” is implicit. The second is that the “Then” comes before the “When”:

1
2
3
4
5
6
7
8

def test_that_constructor_requires_a_person
  # Given - we are going to use a nil Person
  # Then
  assert_raises ArgumentError do
    # When
    Salutation.new(nil)
  end
end

We can clean this up by creating a variable for our nil Person and putting our “Then” code inside a block, which we then pass to assert_raises:

1
2
3
4
5
6
7
8

def test_that_constructor_requires_a_person
  # Given
  nil_person = nil
  # When
  code = lambda { Salutation.new(nil_person) }
  # Then
  assert_raises(ArgumentError,&code)
end

We’ve had to jump through a slightly awkward hoop of putting the code-under-test in a lambda, but now things are in a consistent structure. This example might seem a bit too simplisitc. What about another popular block-based assertion, assert_difference? It’s commonly used in Rails apps to check that a certain number of records were written to the database. While I think that this assertion is generally not needed, it is commonly used.
Here’s an example where we suppose that an after_save hook is memoizing a derived field for us.

1
2
3
4
5
6
7
8
9
10
11
12
13

test "we can save and our after-save hook runs, generating the full_name attribute" do
  # Given
  first_name = 'David'
  last_name = 'Copeland'

  # Then
  assert_difference('Person.count') do
    # When
    person = Person.create(:first_name => first_name, last_name => last_name)
    # Then
    assert 'David Copeland',person.full_name
  end
end

Now the structure is very strange. If we try to apply our lambda solution above, it’s still a bit odd:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

test "we can save and our after-save hook runs, generating the full_name attribute" do
  # Given
  first_name = 'David'
  last_name = 'Copeland'

  # When
  code = lambda {
    person = Person.create(:first_name => first_name, last_name => last_name)
    # Then
    assert 'David Copeland',person.full_name
  }

  # Then
  assert_difference('Person.count',&code)
end

Yikes. This is arguably worse. Since only one line of code inside our “When” block is really affecting the condition that assert_difference tests for, we can take advantage of Ruby’s ability to create instance variables on-demand and pass the person outside of the assert_difference block:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

test "we can save and our after-save hook runs, generating the full_name attribute" do
  # Given
  first_name = 'David'
  last_name = 'Copeland'

  # When
  create_person = lambda {
    @person = Person.create(:first_name => first_name, last_name => last_name)
  }

  # Then
  assert_difference('Person.count',&create_person)
  assert 'David Copeland',@person.full_name
end

That’s much better; we can now clearly see the setup, the code being tested, and all the assertions together.

It may seem slightly unusual, but by working to keep all your tests structured around Given/When/Then, you will find them readable weeks and months later, and others will be clearly able to see their intent.

Next

We still have a fair way to go to get our tests really clean and clear. For example, do we need to have those #Given, #When, and #Then comments everywhere? I think comments are powerful, but having the same group of comments everywhere feels like repetition we can eliminate. Another issue is the use of “magic values”, or literals, in our test code. In the test above, we create a male person with the name “David Copeland”. Is any of this relevant to the test? If not, why is it there?

We’ll deal with these issues in the next post.

The Two Types of Comments

Before we dig in, it’s important to understand that there are two types of comments. There are comments that serve as API Documentation and comments that are, for lack of a better term, explanatory.

I’m not going to argue that you should write API documentation for your public APIs. You should, and anyone insisting that you shouldn’t is just being lazy. It’s worth pointing out that API documentation comments are there to help you write code, primarily. They help answer the question “what code do I need to accomplish this task?”.

The other type of comment, explanatory comments, are there to help you read code, and this is why they are so important to use and to get right. Code is read many more times than written, and I doubt you’ll find a professional developer who would argue against writing code for readability.

Explanatory Comments

Explanatory comments are those that seek to explain something about the code that the author (or maintiner) didn’t feel was obvious from the code itself. It’s at this point that many will say that the mere existence of such comments is a code smell, or indicator that the code should be rewritten in a more clear way.

This rule of thumb makes a lot of assumptions about what sort of comments one might write as well as the expressiveness of source code. Comments that merely explain what the code does are, in fact, a code smell. Comments that explain why the code was written a certain way, or even why it exists at all, are not. Understanding why code is the way it can be is incredibly hard to encode in a programming language. I still think “what” comments have their place, but let’s tackle “why” comments, as these are a powerful tool for code authors and maintainers.

“Why” Comments

Let’s take the example from my last blog entry: a salutation class. Suppose our system has the following implementation:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

class Salutation
  def initialize(person)
    @person = person
  end

  def greeting
    if @person.honorific == :doctor
      "Hello, Dr. #{person.last_name}!"
    elsif @person.first_name.present?
      "Hello, #{person.first_name}!"
    elsif @person.male?
      "Hello, Mr. #{person.last_name}!"
    else
      "Hello, Ms. #{person.last_name}!"
    end
  end
end

This code is pretty clear, and it’s easy to understand what it does. A novice programmer might comment it like so:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

class Salutation
  def initialize(person)
    @person = person
  end

  def greeting
    # Check if they are a doctor, otherwise
    # use their first name, falling back
    # to their gender
    if @person.honorific == :doctor
      "Hello, Dr. #{person.last_name}!"
    elsif @person.first_name.present?
      "Hello, #{person.first_name}!"
    elsif @person.male?
      "Hello, Mr. #{person.last_name}!"
    else
      "Hello, Ms. #{person.last_name}!"
    end
  end
end

We can all agree these comments add noise. So what’s missing from this picture that the code can’t express? Something that seems odd is the explicit check for the honorific of :doctor. Why do we only check that one? Clearly there can be other values for honorific; why don’t we check those?

Code like this is all over the place in a real production application. This is part of what makes the job of a programmer challenging. We get requirements that are sometimes odd and result in akward code that isn’t as clean as the idealized code you’d see in a book. And so we have the dreaded special case, which results in code that sticks out like a sore thumb.

Code like this, at first, looks like a bug: “Oh no! What if someone registers with the honorific of ‘Sir’? We’re going to call them by their first name?”. Suppose in this case, it’s not a bug. Suppose in this case that this is intentional. How would someone know that?

Explanatory Comments.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

class Salutation
  def initialize(person)
    @person = person
  end

  def greeting
    # We special case :doctor because the Initech
    # style guide for messaging requires it, and we need
    # to be compliant with it.  Since we have very few users with
    # honorifics other than doctor, we don't want to get into a 
    # complex honorific mapping mapping situation right now, so
    # we just handle this one explcitly.
    if @person.honorific == :doctor
      "Hello, Dr. #{person.last_name}!"
    elsif @person.first_name.present?
      "Hello, #{person.first_name}!"
    elsif @person.male?
      "Hello, Mr. #{person.last_name}!"
    else
      "Hello, Ms. #{person.last_name}!"
    end
  end
end

Now it makes sense. We got some annoying requirement and had to meet it. The reality of the data in our system made the cost of a more generalized soluation have little benefit, so we did the simplest thing that could possibly work and were nice enough to explain ourselves.

This is the sort of comment that is incredibly useful for understanding code. I would argue that any time you do something weird or akward in your code, you should explain why you did it that way. Future you will thank you in the following ways:

• You’ll understand, six months from now, why you wrote what appears to be awkward code.
• The maintainer of this code won’t ask you about it.

Maintaining Comments

The second criticism typically leveled against comments is that they become out of sync with the code. Continuing our Salutation example, suppose we later get a requirement to special-case college professors. The quick and dirty solution would be:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

class Salutation
  def initialize(person)
    @person = person
  end

  def greeting
    # We special case :doctor because the Initech
    # style guide for messaging requires it, and we need
    # to be compliant with it, and have very few users with
    # other honorifics, so we don't want to get into a 
    # complex honorific mapping mapping situation right now
    if @person.honorific == :doctor
      "Hello, Dr. #{person.last_name}!"
    elsif @person.honorific == :professor
      "Hello, Prof. #{person.last_name}!"
    elsif @person.first_name.present?
      "Hello, #{person.first_name}!"
    elsif @person.male?
      "Hello, Mr. #{person.last_name}!"
    else
      "Hello, Ms. #{person.last_name}!"
    end
  end
end

Now the comment is out of sync with reality. We have a nice explanation of special-casing :doctor, but not a word about :professor. I would argue that the developer that wrote this code and called it “done” has been negligent. He’s not done his job and there’s no excuse for this. At the very least, he should replace the phrase “We special case :doctor” in the comment with “We special case :doctor and :professor”. There’s many better ways to meet the new requirement, but for the purpose of keeping our focus on comments, you must keep the comments and the code in sync. That’s the job.

Hopefully, you can see that comments that explain why code is the way it is are important. These sorts of comments are a powerful tool for expressing intent and making code readable, understandable, and clear, beause the reality is, not every problem that we have to solve can be done so in perfect-looking “clean” code.

So what about those “what” comments? What about comments that explain how code works and what it’s doing? Those are certainly wrong in every case, right? Not so. Here’s a (qualified) defense of those sorts of comments.

Sometimes you need to explain what the code does

I don’t write perfect code. My code isn’t always written in the most elegant, understandable way. Yours isn’t either. The reasons for this are many: we didn’t have time to make it as clear as possible, we couldn’t think of the right name for something at the time we write it, we didn’t really undertand the problem as much as we thought we did, etc.

And, just because you omitted all comments doesn’t make your code magically comprehensible. You might feel that code should be self-documenting, but leaving out comments doesn’t make it so.

If you spent any time in real production code, you know that the most brilliant developers can write some real stinkers, creating convoluted code that can be really hard to unravel. I’ve done it many times, and I’m certain my ex-co-workers at Opower and Gliffy curse my name from time-to-time. It’s code like this that can benefit from some judiciously-placed “what” comments.

Suppose we come across this code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

def isqrt(square)
  square = square.to_i
  return 0 if square == 0
  raise RangeError if square < 0

  n = iter(1, square)
  n1 = iter(n, square)
  n1, n = iter(n1, square), n1 until n1 >= n - 1
  n1 = n1 - 1 until n1*n1 <= square
  return n1
end
def iter(n, square)
  (n + (square / n)) / 2
end

You might guess that this takes the square root, but boy is it impenetrable. Some things are just complex and either can’t be made more clear or external constraints exist (like time) that we just can’t do so. What we probably could do is add a few comments to help the poor sap that must fix a bug in this code later:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

def isqrt(square)
  # just in case we don't get an int
  square = square.to_i
  return 0 if square == 0
  raise RangeError if square < 0

  # make our initial guesses, which are initially 
  # too high (intentionally; see next)
  n = iter(1, square)
  n1 = iter(n, square)

  # Refine our guesses until we get close enough
  n1, n = iter(n1, square), n1 until n1 >= n - 1
  # We're close enough when we're JUST under square
  n1 = n1 - 1 until n1*n1 <= square
  return n1
end
def iter(n, square)
  (n + (square / n)) / 2
end

The code is more noisy, yes, but now the reader has some clue as to what’s going on. It might even given him the confidence to refactor this in a way that no longer requires comments.

What about tests?

Tests can give insight into how code is supposed to work. Tests can rarely make clear the why of code, and almost never explain the complex guts of a routine. And, let’s be honest, even well-tested applications have horribly unreadable tests, rife with duplication, magic numbers, questionable coding practices and other horrors we’d never include in our production code. We’ll get to that.

The point is, comments are a way to include information that can’t be (or wasn’t) expressed in code right next to the relevant code. There’s power in that, and a develper that completely writes this power off is being foolish.

Bottom Line

• Document your public API
• Use comments to explain why odd or surprising code was written
• Use comments to explain what impenetrable code is doing if you just can’t make it any more clear

Future you will thank you.

How much duplication is too much or, what does duplication in tests mean, and how does it affect the understandability and maintainability of our tests?

What is a test?

To know how our test code should be structured, we must understand what the purpose of a test is. At its base, a test is some code that, when executed, checks that some other code behaves in a certain way. This is a bare minimum, we also wnat our tests to describe the behavior of a piece of code. We should be able to understand, from looking at a bunch of tests, what the code is supposed to do and what the intent of the developer who created it was.

Let’s start with the basic structure of one test

Structure of a single test

A test is made of up three parts:

1. Setup or Given - This part establishes the conditions under which the test will be performed. This is crucial, and what makes programming hard - can we know every condition under which our code will run? We call this “Given” because we simply “give” conditions to the code under test.
2. Execute or When - Here, we run the code we’re testing, usually by calling a public method from the class under test. It’s called “When” because of phrases like “When I calculcate the sales tax”.
3. Assert or Then - The final part involves checking that what we executed in step 2 did what we thought it should do. It’s called “Then” because of the way we might state assertions in English - “Then the total should be $56.12”.

A very simple test might look like this:

1
2
3
4
5
6
7
8

def test_area
  # Given (setup)
  circle = Circle.new(10)
  # When (execute)
  area = circle.area
  # Then (assert)
  assert_equal 314,area
end

Tests in real apps are rarely this simple and straightforward. Often, complex setup is required to establish all the “givens”. Further, the setup for several tests might be very similar, containing identical code with very small differences. It’s these differences that form the true picture of the behavior of code under test.

Structure of a set of tests

Let’s take a simple domain that it’s a bit more complex than our Circle class to see how tests interact. Let’s test a class that, given a Person, returns a “salutation”. What makes this tricky is that people in our system don’t always have a first name or last name. We want our Salutation class to handle this.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

class SalutationTest << Test
  def test_full_name
    # Given
    person = Person.new("David","Copeland",:male)
    salutation = Salutation.new(person)
    # When
    greeting = salutation.greeting
    # Then
    assert_equal "Hello, David!",greeting
  end

  def test_first_name_only
    # Given
    person = Person.new("David",nil,:male)
    salutation = Salutation.new(person)
    # When
    greeting = salutation.greeting
    # Then
    assert_equal "Hello, David!",greeting
  end

  def test_last_name_only_male
    # Given
    person = Person.new(nil,"Copeland",:male)
    salutation = Salutation.new(person)
    # When
    greeting = salutation.greeting
    # Then
    assert_equal "Hello, Mr. Copeland!",greeting
  end

  def test_last_name_only_female
    # Given
    person = Person.new(nil,"Copeland",:female)
    salutation = Salutation.new(person)
    # When
    greeting = salutation.greeting
    # Then
    assert_equal "Hello, Ms. Copeland!",greeting
  end
end

Read these tests over. They should, hopefully, give you a picture of what the Salutation class is supposed to do, even though we aren’t seeing the actual implementation¹. Of course, this isn’t perfect. If you look over the test class quickly, all the tests look similar, and it’s hard to tell what the differences are. Specifically:

• The assertions in the first two tests are identical. Is this by coincidence, or by design?
• This test is tightly coupled to the construction of a Person, even though this class doesn’t test that construction; we simply want Person instances of a certain nature.

All of these issues make it unclear what’s really being tested. What part of each of these tests is different from the others in a significant way?

Making intent more clear

Our first issue is that the first two tests’ assertions are identical. This is, in fact, by design of the Salutation class - if the person has a first name, we don’t care if they have a last name. Let’s make that design decision clear:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

class SalutationTest << Test
  def test_salutation_uses_first_name
    [ Person.new("David","Copeland",:male),
      Person.new("David",nil       ,:male),
    ].each do |person|
      # Given
      salutation = Salutation.new(person)
      # When
      greeting = salutation.greeting
      # Then
      assert_equal "Hello, David!",greeting,"For person #{person}"
    end
  end
end

Now, it’s very clear that the last name doesn’t matter. Note that since we’re now executing our given/when/then in a loop, we need to include the person used in the salutation in our assertion message so if it ever fails, we know which last_name caused it.

This clears up our biggest issue, but what about the duplication of creating Person instances? Outside of the fact that any change in the constructor Person will break this test, it’s also not clear what’s different about all of these Person instances. Even if we’re familiar with the constructor, it’s still not 100% clear what kind of person we’re setting up as a “Given”.

We could certainly drop a few comments in, but we have a more powerful tool: method extraction.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

class SalutationTest << Test

  def test_salutation_uses_first_name
    # Given
    first_name = "David"

    [ person_with_first_name_only(first_name),
      person_with_full_name(first_name) ].each do |person|
      # Given
      salutation = Salutation.new(person)
      # When
      greeting = salutation.greeting
      # Then
      assert_equal "Hello, #{first_name}!",greeting,"For person #{person}"
    end
  end

  def test_last_name_only_male
    # Given
    salutation = Salutation.new(male_with_only_last_name("Copeland"))
    # When
    greeting = salutation.greeting
    # Then
    assert_equal "Hello, Mr. Copeland!",greeting
  end

  def test_last_name_only_female
    # Given
    salutation = Salutation.new(female_with_only_last_name("Copeland"))
    # When
    greeting = salutation.greeting
    # Then
    assert_equal "Hello, Ms. Copeland!",greeting
  end
end

Now, it’s painfully clear which type of person we’re setting up. We’ve also been able to eliminate the person variable, which was only really needed to construct the Saluation instance. It’s existence muddied the test code, so the elimination of that makes the tests more clear. The extracted methods are trivial:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

def person_with_first_name_only(first_name)
  Person.new(first_name,nil,:male)
end

def person_with_full_name(first_name)
  Person.new(first_name,'Smith',:male)
end

def male_with_only_last_name(last_name)
  Person.new(nil,last_name,:male)
end

def female_with_only_last_name(last_name)
  Person.new(nil,last_name,:female)
end

Granted, our test is a lot more lines of code than it was, but it’s also a lot more clear. Since code is read much more often than written, good, clean code should favor readability. Our test code now does, clearly communicating, for each test, what the conditions are under which we’re going to test, what code we’re testing and what behavior we expect our code to exhibit, all with a minium of comments – the code speaks for itself.

Of course, we can still introduce further confusing duplication. As our codebase grows, we’ll see that duplication will also grow.

Behavior in the face of change

Let’s consider a new subclass of Salutation called FormalSalutation. This new subclass will implement the somewhat old-fashioned notion of referring to married women as “Mrs.” and unmarried women as “Miss”. It will also spell our “Mister”. We’ll copy the tests for Salutation and enhance them as a naive first step.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

class FormalSalutationTest << Test

  def test_salutation_uses_first_name
    # Given
    first_name = "David"

    [ person_with_first_name_only(first_name),
      person_with_full_name(first_name) ].each do |person|

      # Given
      salutation = FormalSalutation.new(person)
      # When
      greeting = salutation.greeting
      # Then
      assert_equal "Hello, #{first_name}!",greeting,"For person #{person}"
    end
  end

  def test_last_name_only_male
    # Given
    salutation = FormalSalutation.new(male_with_only_last_name("Copeland"))
    # When
    greeting = salutation.greeting
    # Then
    assert_equal "Hello, Mister Copeland!",greeting
  end

  def test_last_name_only_married_female
    # Given
    person = female_with_only_last_name("Copeland")
    person.marry!
    salutation = FormalSalutation.new(person)
    # When
    greeting = salutation.greeting
    # Then
    assert_equal "Hello, Mrs. Copeland!",greeting
  end

  def test_last_name_only_unmarried_female
    # Given
    salutation = FormalSalutation.new(female_with_only_last_name("Copeland"))
    # When
    greeting = salutation.greeting
    # Then
    assert_equal "Hello, Miss Copeland!",greeting
  end

private
  def person_with_first_name_only(first_name)
    Person.new(first_name,nil,:male)
  end

  def person_with_full_name(first_name)
    Person.new(first_name,'Smith',:male)
  end

  def male_with_only_last_name(last_name)
    Person.new(nil,last_name,:male)
  end

  def female_with_only_last_name(last_name)
    Person.new(nil,last_name,:female)
  end
end

The tests are pretty clear as to what they are doing, but now we have two types of nasty duplication going on:

• Some of these tests are identical to those in SalutationTest
• Some of our private person_* methods are identical to those in SalutationTest

Duplicated Tests

What do our duplicated tests tell us? They tell us that, for a person with a first name, irrespective of the existence of a last name, Salutation and FormalSalutation behave the same only by happenstance. In other words, it is OK for the behavior of these classes to differ in this situation, but, currently, they happen to behave the same. Meaning that if we later change how Salutation behaves, we don’t need to also change how FormalSalutation behaves.

The quesiton is: is this interpretation correct? Let’s suppose that it isn’t. Let’s suppose that, anywhere in our system, anyone that uses a Salutation or Salutation-like class should expect that the behavior regarding a Person with a first name should be the same. Can we communicate that design decision in our tests?

We could do this by creating a module to hold our specific asserts, called SalutationTests::Asserts, like so:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

module SalutationTests
  module Asserts
    def assert_greeting_for_person_with_first_name(greeting,first_name,msg=nil)
      assert_equal "Hello, #{first_name}!",greeting,msg
    end
  end
end

class SalutationTest
  include SalutationTests::Asserts
  def test_salutation_uses_first_name
    # Given
    first_name = "David"

    [ person_with_first_name_only(first_name),
      person_with_full_name(first_name) ].each do |person|

      # Given
      salutation = Salutation.new(person)
      # When
      greeting = salutation.greeting
      # Then
      assert_greeting_for_person_with_first_name(greeting,first_name,"For person #{person}")
    end
  end
end

class FormalSalutationTest
  include SalutationTests::Asserts

  def test_salutation_uses_first_name
    # Given
    first_name = "David"

    [ person_with_first_name_only(first_name),
      person_with_full_name(first_name) ].each do |person|

      # Given
      salutation = FormalSalutation.new(person)
      # When
      greeting = salutation.greeting
      # Then
      assert_greeting_for_person_with_first_name(greeting,first_name,"For person #{person}")
    end
  end
end

We’ve added lines of code, but now it’s clear that the behavior of both Salutation and FormalSalutation are supposed to be the same for a Person with a first name. Meaning, if the behavior of one changes, than the behavior of the other must change, and we can make that change, in our tests, in one place. It also means that future Salutation-like classes can re-use this logic. This is basic structured programming.

Onto our second form of cross-test duplication, the duplication in the setup of Person instances.

Duplication in setup

In both SalutationTest and FormalSalutationTest, we create a person with a full name, a person with no last name, and a male person without a first name. It’s done the same way in both test classes. The code, as it stands now, is telling us that this duplication is merely happenstance. This is not correct. We intended to create the same set of circumnstances in both tests. In one, the behavior is the same (by design, as indicated by the sharing of the assert method). In the other the classes, under the same conditions should behavior differently.

So, we’d like to communicatet this sameness that in our implementation. We could use a tool like FactoryGirl, but this puts all of our test data into global scope. We only want our test data scoped to the tests in question. This is so that data can change as those sets of classes change, and we can be sure we aren’t breaking other classes.

We can do this without any special tools by using a module with a well-chosen name. We’ll use our SalutationTests namespace and create a new module inside called People that will contain our extracted methods.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

module SalutationTests
  module People
    def person_with_first_name_only(first_name)
      Person.new(first_name,nil,:male)
    end

    def person_with_full_name(first_name)
      Person.new(first_name,'Smith',:male)
    end

    def male_with_only_last_name(last_name)
      Person.new(nil,last_name,:male)
    end

    def female_with_only_last_name(last_name)
      Person.new(nil,last_name,:female)
    end
  end
end

class SalutationTest << Test
  include SalutationTests::People
end

class FormalSalutationTest << Test
  include SalutationTests::People
end

It’s now clear that the setup for the first two tests of both SalutationTest and FormalSalutationTest are the same by design. Note that if we did choose to move to FactoryGirl later on, we only need to update this module to use our factories, instead of having to go into each test method and do it. This is, yet again, basic structured programming.

What about the case when we want to re-use this setup, but change it slightly? Should we re-use it, or duplicate it?

When we need a slight tweak to our setup

Suppose we want to make a third class, called HonorificSalutation. Here, our setup is very similar, but not exactly the same, as our common Person setup in SalutationTests::People. Since we don’t have to use this module, we could create Person instances exactly how we’d like, and make it clear that the tests in HonorificSalutationTest aren’t the same as those in the other two.

However, this isn’t exactly true. The setup is almost the same and, since these three classes are all related, it makes sense to share the similarities. We want someone to look at HonorificSalutation and know what’s different about this class from Salutation or FormalSalutation. So, we re-use the methods from SalutationTests::People and modify the results during the setup:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

class HonorificSalutationTest << Test
  include SalutationTests::People

  def test_doctor_with_no_first_name
    [ male_with_only_last_name('Copeland'),
      female_with_only_last_name('Copeland')].each do |person|
      # Given
      person.honorific = :doctor
      salutation = HonorificSalutation.new(person)
      # When
      greeting = salutation.greeting
      # Then
      assert_equal "Hello, Dr. Copeland!",greeting
    end
  end
end

What this code is saying is that when we test a person who’s a doctor and has no first name, we want both a male and female exactly like we had in our other tests, but the one difference between those tests and this is that honorific is being set to :doctor. This makes it very clear what’s truly different.

Conclusions

There’s a lot more to this subject, but essentially what we’re getting at is the meaning behind duplication. Essentially, things that are the same by desgin should be shared. Everything else is only the same by happenstance. By coding your tests in this way, you make the intent and design very clear. And you don’t need any special tools to do it.

2011

Here’s what was on my list of goals for 2011:

Deploy my iPhone app to App Store

Sadly, my app is still floundering. With the release of iOS5, it’s even got some bugs. I would like to either re-implement or at least beef it up and get it into the store. With the book done (see below), this might happen.

Speak at at least 2 conferences

Done and done. I was lucky enough to speak at more than two conferences this year, including RubyNation, RubyConf, GoGaRuCo, OSCON and Ruby Midwest. It was a ton of fun, but exhausting. Probably going to dial that back this year.

Publish my command-line application book

My book on command-line applications in Ruby is done. It took most of my free time this year to get it to completion, but it’s done and should be out of beta real soon. I love writing and so I’m inclined to count this against myi “blog twice a month” thing, but it took a lot more time than I thought it would.

Develop and deploy an iPad app

Not even close :(

Blog twice a month

I barely managed an average of one post/month. This year will hopefully be better. My main problem is that it’s hard to find interesting things to blog about. I would much rather my blog be like Marco Arment’s than a grab bag of technical junk, but I also don’t want to have a blog like Daring Fireball that is just opinions and reactions (not that I don’t think that’s a great blog or a great way to write, but it’s just not what I want to blog about).

Learn JavaScript more betterer

I spent almost no time improving my JavaScript skills. I’m not particularly sad about it, but I would still like to be better at it.

Get my rudimentary scaladoc doclet accepted.

I think that my patch inspired a change in the scaladoc tool that gives it doclet-like abilities, but I couldn’t find the time to do anything with it. The Scala documentation is much improved over the initial version of Scaladoc2, but it’s still pretty bad. Sadly, I’m not writing a lot of Scala at work, so I don’t have the time or motivation to do much about it.

2012

All in all, I didn’t hit everything I’d hoped, but I’m still happy with how things panned out. I think the theme of 2011 for me was “Don’t Get Pigeon-holed”.

While my job at Opower was great, I was doing a lot of Java and ready to move on, both technically and product-wise. Instead of spending my free-time refining my Ruby skills, I now apply them daily (along with a great team), freeing up my after-work time to other pursuits.

So, what are those pursuits? I’m not looking to dive into some esoteric new bleeding-edge language at the moment. I’d still like to get better at JavaScript and Objective-C, and that might be enough “new stuff” for me for this year. Additionally, I’d like to:

• Keep writing, either the blog or a short self-published thing
• Complete methadone and release GLI2, so both of those projects can be in maintenance-mode for a while
• Find a way to keep up with my Scala.

Beyond that, hopefully I can spend more time on music and cooking this year. Amy and I had a blast in Culebra just making up dishes using the limited ingredients available on the island and I’m just tired of eating sandwiches.

In short, I’d recommend this book to someone interested in command-line Ruby (and who might have my book), but who has very little UNIX programming experience. This book is a crash-course in the basics of UNIX Process management.

That being said, if you are (or have been) familiar with things like fork and exec, you’ll find this book a bit too light, especially given the price (update 1/2/2012 see inside).

The Good

The information in the book is accurate and presented at excellent pace; the reader isn’t expected to ingest too much knowledge at once, and the author brings the reader one step-at-a-time through understanding UNIX process management. In a nice touch, the author pauses on occasion to connect the information presented to “real world” scenarios.

The book also delves slightly into the realities of using these tools in the context of particualr Ruby implementations.

The appendeces of the book are a walkthrough of certain parts of Resque and unicorn’s source code, relating back to the concepts learned in the book. This is something few books do, but that I find very illuminating. Here, it demonstrates real-world use of the concepts outlined in the book.

The Bad

At $27 ($7 more than my book, and $22 more that Avid Grimm’s so-far-wonderful Objects on Rails), I was hoping for a little more depth. The book clocks in at 90 pages in PDF (77 pages in iBooks) and feels more like an introduction. For the price, I was hoping for a lot more depth.

As an example, the section “Daemon Processes” shows the use of the setsid system call. Although the purpose of using the call is explained, that explanation makes no sense. I have no idea what a “session leader” or “process group” are, and these terms are never touched on in the book, nor is there a link to find out more. A cursory search of the internet turned up only the information presented here. Piecing this together is the insight a book like this should provide; it’s what makes the information worth paying for.

Update 1/2/2012: The author has recently updated the book to include a much more detailed explanation of setsid and all of the process stuff around it. The update makes it very clear how the quoted rack daemon process code works and was very illuminating. This demonstrates one of the cool things about ebooks - easy updates.

I also feel like some discussion of named pipes would be warranted, as well as things like select and poll, which are at the heart of the current fad in evented programming.

The book could also benefit from some editing, as there were just enough grammar and spelling mistakes to distract me, as well as numerous formatting bugs with source code in the ePub version. I also think that using running, real-world examples would make the points more clear; the examples aren’t particularly compelling (although the appendeces make up for this significantly, since they do relate the concepts to real code).

The book also includes some source code that is never really discussed and, honestly, I’m not sure what I’m supposed to do with it.

Conclusions

Don’t let these criticisms spoil you, though. If you have no clue what a process is, or what exec is for, this book will teach that to you, simply and quickly. This book fills a gap that a lot of developers have these days; it shouldn’t require writing C code to learn the UNIX fundamentals. This book proves that to be true.

I just finished up an appendix where I showed alternate implementations of the running examples using main, thor, and trollop. I did this for a few reasons:

• These tools are popular, and people have asked if they’d be included
• They are, by and large, very different from how OptionParser and GLI work
• I wanted to give them a real shakedown

I also surveyed many other tools, but, alas, I couldn’t include everything. Each of these tools have a common theme, which is to avoid the boilerplate of OptionParser, and make it really easy to parse command-line arguments. They all have done this, but at a cost. All of them are less powerful and extensible than OptionParser, and only slightly more compact (or, in the case of main, more verbose).

Enter methadone, which has all of OptionParser’s power, but the compactness of these other frameworks.

Another command-line option parser?

Yes and no. Methadone isn’t a re-implementation of command-line option parsing. It’s barely a DSL, making use of almost no meta-programming, class_eval, or other craziness. It’s a plain Ruby proxy to OptionParser, with some helper methods. It makes idiomatic option parsing and command-line app design as seemless as possible, but doesn’t force any of itself on you. In this post, I’ll derive its syntax while showing you the basics of how to structure a simple command-line app.
You’ll have to buy the book to dig deeper¹.

Basic Command-line App Structure

Most command-line apps start off with parsing the command-line with OptionParser (which typically consists of setting values into some Hash), defining a few helper methods, and then, at the end, implementing the main logic of the program:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

#!/usr/bin/env ruby

require 'optparse'

options = {}

parser = OptionParser.new do |opts|
  opts.banner 'My awesome app'

  opts.on("-u USERNAME","--username","The username") do |user|
    options[:username] = user
  end

  opts.on("-v","--verbose","Be verbose") do
    options[:verbose] = true
  end

  # etc.

end

parser.parse!

def some_helper_method
end

def some_other_helper_method

puts "Starting program" if options[:verbose]

# etc, the main logic of your program

Yuck. The boilerplate option parsing is bad enough, but the structure is all wrong. The interesting stuff is all the way at the bottom; you have to read the thing in the wrong order. At the very least, you should extract the core logic into a main method, put that at the top, and call it at the end.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

#!/usr/bin/env ruby

require 'optparse'

def main(args)
  # main logic of your app
  0 # or return nonzero if something went wrong
end

def some_helper_method
end

def some_other_helper_method

puts "Starting program" if options[:verbose]

options = {}

parser = OptionParser.new do |opts|
  opts.banner 'My awesome app'

  opts.on("-u USERNAME","--username","The username") do |user|
    options[:username] = user
  end

  opts.on("-v","--verbose","Be verbose") do
    options[:verbose] = true
  end

  # etc.

end

parser.parse!

exit main(ARGV)

Now, we can see, immediately upon opening the file, the main thing this app is doing. Of course, an exception might be raised. We may even do it on purpose, but we can’t have the app vomiting a stack trace to the user, so we wrap our call to main in a begin..rescue block:

1
2
3
4
5
6

begin
  exit main(ARGV)
rescue => ex
  STDERR.puts ex.message
  exit 1
end

Methadone’s Main Method

The structure we just saw is pretty decent, and gives us, and future contributors, an easy way to follow the code. Users also get a pretty decent experience and never have to see a backtrace.

This brings us to the first feature of methadone. Instead of including this boilerplate every time, we extract it into a module, Methadone::Main, which gives us two methods: main and go!.

main takes a block that represents our main method from before. go! calls that block, handling the exceptions for us. Our app now looks like so:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

#!/usr/bin/env ruby

require 'methadone'

include Methadone::Main

main do |args,go,here|
  # main logic
  # raise exceptions at will
end

# declare options and helper methods as before

go!

go! will extract the contents of ARGV leftover after parsing and pass them to the block. Since they’re passed as individual arguments, you don’t have to call shift a bunch of times on some array. Just name your parameters whatever, and Metahdone takes care of it. If your main block raises an exception, go! will handle catching it, messaging the user without a backtrace, and exiting nonzero².

Parse Options with no Loss of Power

Notice how we can still safely use OptionParser. Methadone doesn’t hide that. As we’ll see, it provides some more features to make option parsing even easier. First, we can get rid of the options Hash as well as the actual creation of the OptionParser instance.

Methadone provides two methods: options and opts. options provides access to a Hash that we can use inside our main block. opts provides access to the underlying OptionParser instance that is automatically created. We can now remove a few lines of code, losing no functionality:

1
2
3
4
5
6
7
8
9

opts.banner 'My awesome app'

opts.on("-u USERNAME","--username","The username") do |user|
  options[:username] = user
end

opts.on("-v","--verbose","Be verbose") do
  options[:verbose] = true
end

Given that opts is baked in, there’s no need to even use that for our cases, because Methadone provides a method on that proxies to the underlying OptionParser. You can still use opts to access anything else, but for declaring command-line options, just call on directly:

1
2
3
4
5
6
7
8
9

opts.banner 'My awesome app'

on("-u USERNAME","--username","The username") do |user|
  options[:username] = user
end

on("-v","--verbose","Be verbose") do
  options[:verbose] = true
end

You can see, as we peel off layers of boilerplate, Methadone hides nothing; it’s just making commonly-written code easier to write. At any time, you can abandon it and go back to the old way.

So far, we’ve only saved a few lines of code and a couple of characters. That’s because we haven’t seen the true power of the on method. on is more than just a proxy to OptionParser. It does one additional thing for us: it we omit the block, Methadone will provide one for us. That Methadone-provided block simply sets the value from the command-line in the options Hash automatically. Meaning that the above code is equivalent to this:

1
2
3
4

opts.banner 'My awesome app'

on("-u USERNAME","--username","The username")
on("-v","--verbose","Be verbose")

Not bad! This means that all we need to do, assuming we’re doing things idiomatically, is to give on the names of our options and their descriptions. Note, however, this still proxies to OptionParser’s on method. Suppose we only allowed usernames with all lower-case characters? In Methadone, as in OptionParser, you pass in a Regexp:

1
2

on("-u USERNAME","--username","The username",/^[a-z]+$/)
on("-v","--verbose","Be verbose")

Suppose you want the value type-converted for you? We have access to the underlying OptinParser, so we can set that up easily:

1
2
3
4
5
6

opts.accept(User) do |username|
  User.find_by_name(username)
end

on("-u USERNAME","--username","The username",User)
on("-v","--verbose","Be verbose")

Do the Right Thing

You’ve noticed that we are still setting our banner manually. You’ve also noticed our banner is kinda lame; It doesn’t say what our app does nor does it give an overview of how to use it. It should look like so:

$ awesome_app.rb --help
Does so many awesome things, you won't believe it.

Usage:  awesome_app.rb [options] thing other_thing [optional_thing]

Since Methadone knows that our app takes options (by virtue of us having declared them), and it knows the name of our app, we just need to tell it what our app does, and it will assemble the banner for us³.

1
2
3
4
5
6
7
8
9
10

main do |thing,other_thing,optional_thing|
  # logic
end

on("-u USER","--username","The user name")
on("-v","--verbose","Be verbose")

description "Does so many awesome things, you won't believe it."

go!

Finally, you’ll note that our main block takes three arguments. Methadone provides the method arg that allows us to name them (in the language the user will understand) and indicate which are required and which are optional. Methadone will put this information into the banner, and will fail if any required arguments are missing:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

main do |thing,other_thing,optional_thing|
  # logic
end

on("-u USER","--username","The user name")
on("-v","--verbose","Be verbose")

description "Does so many awesome things, you won't believe it."

arg :thing
arg :other_thing
arg :optional_thing, :optional

go!

Now, the banner looks like we’d like it, and we didn’t have to do much more than describe our program. You can even bootstrap your app using the methadone command-line app. It will create an empty app, using this structure, with some helpful comments to let you describe your UI easily and quickly. But it won’t prevent you from doing any sort of crazy thing with OptionParser that you need to.

Sweet, Sweet Sugar

But wait! There’s more! Complex programs start to look like this:

1
2
3
4
5
6
7
8
9

if have_connection
  # puts "got a connection"
  file = request_data
  puts "Got data"
  if file.nil?
    STDERR.puts "Data was nil?"
  end
end
# puts "Moving on"

You’ve got a mix of commented-out debug statements, informational messages and tediously long statements sending error messages to the standard error. Methadone includes a special Logger instance, along with some helper methods, that does away with all this:

1
2
3
4
5
6
7
8
9
10
11

include Methdone::CLILogging # sets up Logger, provides helper methods

if have_connection
  debug "got a connection"   # Calls logger.debug 
  file = request_data
  info "Got data"            # Calls logger.info
  if file.nil?
    error "Data was nil?"    # Calls logger.error
  end
end
debug "Moving on"            # Calls logger.debug

The logger is set up as follows:

• debug messages don’t go anywhere.
• info goes to the standard output.
• warn, error, and fatal go to the standard error.
• Log messages are unformatted when logged to a TTY
• Log messages are formatted with timestampes, levels, etc, when logged to a file

This means that for command-line use, the user sees messages formatted for them, and not horrible Maven-style enterprise logging. As soon as you use your app in cron, however, the logger senses the absence of a TTY and switches its format to this style, so that the log files do have that valuable information.

You have complete access to the logger via logger and logger=, so you can ultimatley do whatever you want.

Methdone::CLILogging is included in Methdone::Main, so, if you followed the structure above, you have access to the logger and these methods.

Is there more?

In addition to all of this, Methadone provides some Cucumber step definitions, based on Aruba that allow you to test-drive your command-line app. When you bootstrap your app using methadone, this will be set up for you.

I’m planning a few more things before v1.0.0, so checkout the roadmap for more info.

And, don’t forget the buy the book