Anyways, I just finished presenting at the Ruby Hoedown. It was roughly the same talk I gave at Mountain West Ruby conf but with a lot more advanced material and content in general. It went somewhat okay. I think I went too fast leaving some people behind when I was racing through the “basics”. I had wanted to cover some of the more advanced topics that don’t get covered usually, but in the end I feel like the presentation came off as rushed and unfocused. It didn’t help that I was going off of 3 hours of sleep either. :/ Another issue was the color of my code slides, which looked awesome at MWRC but just didn’t project well on this projector- so, planning fail on my part. I apologize for failing to recognizing my audience and the sub-par delivery. Regardless, I’m glad I did it and I’d like to thank Jeremy for inviting me to speak. </presentation_retrospective>

The presentation was a little meta… I was using a sinatra app I wrote called CodeNote that allows audience members to follow along but not go ahead. A presenter is able to define the slides in a variant of Pat Nakajima’s awesome slidedown format. I also integrated it with twitter so that I could ask questions and people could respond to them via twitter to win a book. This explains the spamming of the #cucumber hash tag during my presentation. The meta part was that I showed how to test the twitter integration during the presentation. Writing a test for that involved using a webservice (twitter), AJAX, and running background jobs. I didn’t get into it nearly as much as I had hoped (which may be a good thing in retrospect) so if you are curious I would suggest checking out the code on github.

Here are the slides:

Note: Since SlideShare is lame now and won’t let you download the slides without an account here is a PDF copy of the slides if interested.

Cucumber is a BDD tool that aids in outside-in development by executing plain-text features/stories as automated acceptance tests. Written in conjunction with the stakeholder, these Cucumber features clearly articulate business value and also serve as a practical guide throughout the development process: by explicitly outlining the expected outcomes of various scenarios developers know both where to begin and when they are finished. I will present the basic usage of Cucumber, primarily in the context of web applications, which will include a survey of the common tools used for simulated and automated browser-testing. Common questions and pitfalls that arise will also be discussed.

MountainWest decided to cut the presentation times down to 30 minutes this year. I think the new format was awesome and I hope they stick to it. However, I did have to cut some topics from my presentation. Namely, I wasn’t able to explain Selenium and Celerity so those interested in testing JS with Cucumber should take a look at webrat’s selenium adapter, Celerity, Culerity, and the Celeriry webrat adapter (work-in-progress). on github. I should also point out that you can use Watir or any other tool within Cucumber as well.

Note: Some of the code samples are not properly highlighted when viewing the presentation from slideshare.net so I would suggest downloading the PDF version.

During the presentation I was serving up my slides with a little sinatra app called slide_server. (The app didn’t allow people to skip ahead in the presentation.) I’ll be putting that code on github for any of those interested. Many thanks to Brian Mitchel for helping me out with running the server during the presentation.

The Feature

Developers often struggle when writing features that entail systems or are purely technical in nature. I highly recommend Liz Keogh’s post about this subject as it greatly helped me in learning how to phrase such technical stories. With that said, lets look at the example feature:

  In order to enable accurate reporting
  As an analyst I want System A
  to keep it's widget data in sync with System B

  Scenario: widget creation
    Given I am logged in to System A
    When I create a widget
    Then the same widget should exist in System B

As you can see there is not much to the actual feature itself. In real situations more context (more Givens) is usually needed to set up needed data, but outside of that the above is a good representation of what we found to be a good scenario format to stick to. The key is to be simple and state declaratively the behaviour of the two systems. This allows you keep the details of the implementations in the step definitions and not clutter the overall intent of the scenario with technical noise.

Step Definitions

I said above that both projects use the exact same plain-text feature, but implement the steps differently. While this is true, we actually ended up having the exact same step definition files as well. Blocks were then used to distinguish the code for either system within each step. Continuing the example from above the pertinent step definitions would be:

When "I create a widget" do
  @expected_message = {"name" => "Foo", "color" => "Red"} 

  system_a do
    create_widget(@expected_message)  # this call should then make system_a publish a message
  end

  system_b do
    # when system_b runs the feature it needs to simulate a message from system_a
    publish_message(@expected_message, :to => :widget_queue)
  end

end

Then "the same widget should exist in System B" do
  system_a do
   # to ensure system_a is working correctly we need to make sure that the message was published
   @expected_message.should be_published_to(:widget_queue)
  end

  system_b do
    consume_once_with WidgetConsumer # have the consumer process the expected message from above
    Widget.count(:conditions => @expected_message).should == 1
  end

end

end

We gravitated to this solution because by keeping the files the same it was easy to keep the two systems in sync. If one system changed the expected message or queue the step definitions would be updated and then both systems would make the feature pass again.

To be clear, these step definitions do not run both systems simultaneously. Each system runs the feature independent of the other. That is why System B in our example simulates what System A is publishing. At this point we are trusting that the messaging system will do it’s job and deliver the message. If the systems are publishing and subscribing to the correct queues with an agreed upon message format then the messaging system should take care of the rest. We did investigate running both systems from the same feature but in our situation the hassle and cost was not justified by the little value we saw that adding.

In order to accommodate this the following helpers were needed:

System A:

module MessagingHelpers
  def system_a
    yield
  end

  def system_b
    #no-op
  end

end

World(MessagingHelpers)

For System B the opposite was needed:

module MessagingHelpers
  def system_a
    # no-op
  end

  def system_b
    yield
  end

end

World(MessagingHelpers)

Of course you will need the actual messaging helpers too…

Introducing Rosetta Queue

The above step definitions have some nice messaging helpers (i.e. publish_message, should be_published_to, etc…). These are not just imaginary helpers for use in the example, but are helpers in a library Chris Wyckoff and I recently released called Rosetta Queue. Rosetta Queue is named such because it has an adapter layer built-in that allows you to easily swap out which messaging system you are using. For example, you could start out by using the stomp adapter with ActiveMQ but then later switch to use the AMQP adapter for use with RabbitMQ. We used a real messaging system in our Cucumber features but for our RSpec code examples (unit tests) we disconnected the messaging system and used null and fake adapters provided by Rosetta Queue. You can read more about how to use Rosetta Queue on github.

As a disclaimer, I should say that Rosetta Queue is still relatively immature. It is being used in production systems, but we aren’t happy with the API for publishing and receiving messages. We will most likely be moving to an API that looks like:

queue(:widgets) << "some message"
message = queue(:widgets).pop

The fake adapter is also really a dummy adapter that I want to replace with an actual in-memory fake adapter. But overall, it is a nice library that aids in testing asynchronous messaging on the acceptance and unit level.

Conclusion

The pattern I’ve outlined above could be used with any messaging library, not just Rosetta Queue. We found that using Cucumber in this fashion greatly eased the work required to integrate our systems and reduced our error rate. By hitting the real messaging systems in our features we gained confidence in our system and helped prevent against regressions. This also allowed us to disconnect our messaging systems from our unit tests so we could test our objects in isolation and keep them lightning fast. (Yep, our unit tests were actual unit tests!)

In the context of Cucumber these test builders work well when you need to create some records with default values in Given steps. Combined with the power of Cucumber step tables you can further leverage the builder pattern by providing the pertinent values to just the attributes that matter in each scenario. The code below works out of the box for builders that adhere to the “create_model_name” API, but can be easily adapted to any API. I have some thoughts on how to further leverage these builders in Cucumber along with Webrat but that is for another post. In the mean time, enjoy and fork away!

# step_definitions/builder_steps.rb
module BuilderStepHelpers

  def create_model(model_name, attributes={})
    send("create_#{model_name.gsub(' ','_')}",attributes)
  end

end
World do |world|
  world.extend BuilderStepHelpers
end

# Examples:
# Given the following widget exists:
# | Name  | Price |
# | Foo   | 20.00 |
# Given the following pets exist:
# |  Pet Type | Months Old     |
# | Dog       | 23             |
# | Cat       | 34             |
Given /^the following (.+?)(?:s|) exist(?:s|):$/ do |model_name, table|
  table.hashes.each do |hash|
    attributes = {}
    hash.each { |k, v| attributes[k.gsub(' ','').underscore] = v }
    create_model(model_name, attributes)
  end
end

# Example:
# Given widgets named 'Foo', 'Bar', and 'Car' exist
Given /^(.+?)(?:s|) named (.+) exist$/ do |model_name, names|
  names.extract_list.each do |name|
    create_model(model_name, {:name => name})
  end
end

# Example:
# Given an expensive widget exists  (assumes you have a create_expensive_widget method)
# Given a widget exists
# Given 3 widgets exist
# Given 33 widgets exist
#
# Warning: this one can be a little too greedy at times so YMMV from project to project.
Given /^(a|an|\d+) (.+?)(?:s|) exist(?:s|)$/ do |ammount, model_name|
  how_many = ammount =~ /a|an/ ? 1 : ammount.to_i
  1.upto(how_many) { create_model(model_name) }
end

# support/string.rb
# Examples:
# "'Foo', 'Bar', and 'Jar'".extract_list # => ["Foo", "Bar", "Jar"]
# '"Dog", "Cat"'.extract_list # => ["Dog", "Cat"]
class String
  def extract_list
    self.scan((/['"](.*?)["']/)).flatten
  end
end

• December 9 2008 – While hanging out in #cucumber, on freenode, agib (Aaron Gibralter) asked about testing emails in a rails app. I had some old RSpec Story Runner steps for such the thing so I quickly extracted them into a plugin and modified them to work in Cucumber. I pushed it to GitHub and email-spec was born.

• December 11 – Aaron sent me a pull request with some additional functionality he had added.

• December 17 7:46pm – Mischa Fierer sent an email to the rspec-users mailing list telling about the new plugin and some cool additions he made in his own fork (which he had forked off of Aaron’s.) He also added a cucumber feature example in the README on how to use the steps.

• December 17 9:37pm – I see Mischa’s email and pull in his changes. I then created a sample rails app to illustrate how to use the plugin and ended up implementing the feature Mischa listed in the README. I also did this so we could verify that the plugin still worked after we made further changes. In one of my comments I alluded to making it more accessible to other web frameworks.

• December 18 8:00am – I woke up and found two GitHub pull requests. Shortly after I had pushed the sample app to GitHub Mischa had taken it, extended it and then used it to improve the error messaging in the plugin. Then he converted the plugin into a gem (making it more accessible to other web frameworks), rolled the sample app into it with a handy rake task to test it, and improved the documentation! I merged in his changes and then made some minor tweaks.

So in less than 10 days code that was sitting around in one of my projects had been extracted, forked twice, and turned into a gem. Pretty cool, huh? This is why I believe GitHub has changed the way open source projects are started and developed. Yes, I could have released my code on RubyForge, or SourceForge, etc.. but the fact is that I never would have. It takes so much longer, and is more intimidating to start a project on *Forge that I simply never would have done it. The code I was sharing was small, had some rough edges and just wasn’t “official” looking enough to warrant spending the time to do that.

When someone asks for code on a mailing list or in an IRC room you used to have two options: copy and paste the code into the email/room or use a site like pastie and send the link. With how easy it is to create repos on GitHub you can now simply “throw it on GitHub” (yes. you could also do a gist.) Since forking and sending pull requests is just as easy you will likely see more patches and contributors with it on GitHub than you would otherwise. GitHub also spreads the word of your code/project a lot faster too since it starts showing up in people’s activity feeds. I had originally put the code on GitHub for Aaron to look at and other people seemed to just stumble upon it. In short, the combination of git and GitHub’s collaboration tools makes one awesome platform to develop open source software on.

Global Setup for Specs

In order to announce the running of a spec in rail’s test log for all of the specs you need to take advantage of RSpec’s global setup capabilities. To recreate the same type of logging message that Brian did for Test::Unit in RSpec you would simply need to add this in your spec_helper.rb:

    Spec::Runner.configure do |config|
      ...
      config.before(:each) do
          full_example_description = "Starting #{self.class.description} #{@method_name}"
          RAILS_DEFAULT_LOGGER.info("\n\n#{full_example_description}\n#{'-' * (full_example_description.length)}")
      end

    end

Note, that I am using the RAILS_DEFAULT_LOGGER constant instead of Rails::logger which was just introduced in Rails 2.1. If you are using Rails 2.1 then I would suggest using the prettier and newer way. I personally don’t feel the need to have “Starting” preface each description in the log file and prefer just to use the example description:

    Spec::Runner.configure do |config|

      ...
      config.before(:each) do
          full_example_description = "#{self.class.description} #{@method_name}"
          RAILS_DEFAULT_LOGGER.info("\n\n#{full_example_description}\n#{'-' * (full_example_description.length)}")
      end
    end

Global Setup for Stories

When using the RSpec Story Runner you often want to do some standard setup and teardown for each story and/or scenario. (Such as cleaning up the database, or resetting ActionMailer::Base.deliveries.) While the Story language does not provide a way to express this sort of setup and teardown (which is a good thing IMO) you can achieve the same effect by registering Listeners with the correct hooks. The useful available hooks you can use are as follows:

    class MyStoryListener
       def run_started(number_of_scenarios); end
       def story_started(story, narrative); end
       def story_ended(story, narrative); end
       def scenario_started(story, scenario); end
       def scenario_succeeded(story, scenario); end
       def scenario_pending(story, scenario, error); end
       def scenario_failed(story, scenario, error); end
       def run_ended; end
    end

For example, if you wanted to add similar logging capabilities to your stories as we did with our specs above you would need to create a custom Listener and register it. The code to do that is as follows: (this should live in your stories/helper.rb file)

    class StoryLoggerListener

       def scenario_started(story, scenario)
        story_description    = "Story: #{story}"
        scenario_description = "  Scenario: #{scenario}"
        line_width = (story_description.length > scenario_description.length) ? story_description.length : scenario_description.length
        # yes, I know I could do [story_description.length, scenario_description.length].max
        RAILS_DEFAULT_LOGGER.info("\n\n#{story_description}\n#{scenario_description}\n#{"-"*line_width}")
       end

       def method_missing(method, *args)
          # no-op
        end
    end

    # This is how you register your listener
    Spec::Story::Runner.register_listener(StoryLoggerListener.new)

The trick is to have method_missing handle all of your unimplemented hooks and just implement the ones you care about. The last line is what lets the Story Runner know about your listener so that the hooks are actually called.

Since scenarios tend to take a lot more space in a log file than an individual spec I don’t find this logging as useful. The use of Listeners within the Story framework, in general, can be extremely useful though and is a nice feature to know about.

I hope this post helps in shedding some light on some lesser known features of RSpec and results in more useful log files.

I should preface this explanation by saying that RSpec’s built in Shared Behaviour capabilities are very powerful and are usually the appropriate solution when abstracting common behaviour. Pat Maddox recently outlined some best practices of using shared behaviours in a refactoring . I generally use macros when I want to pass in an argument so that I can either a) use them multiple times in a given describe context, or b) customize the example and/or the description for specdoc output.

Macro Example: it_should_assign

A useful macro I use in my Rails controller specs is “it_should_assign”. For example, say we have this simple show action on a nested resource controller:

class UserPhotosController
  def show
    @user = User.find(params['user_id'])
    @photo = @user.photos.find(params['id'])
    @page_title = "Best photo evar."
  end
end

And the specs dealing with assignment:

describe UserPhotosController do

  describe "GET 'users/1/photos/2'" do

    before(:each) do
      User.stub!(:find).and_return( @user = mock_user )
      @user.stub_association!(:photos, :find => (@users_photo = mock_model(Photo)) )
    end

    def do_get
      get :show, :user_id => @user.id, :id => @users_photo.id
    end

    ...

    it "should assign the user to the view" do
      do_get
      assigns[:user].should == @user
    end

    it "should assign the photo to the view" do
      do_get
      assigns[:photo].should == @users_photo
    end

    it "should assign the page title to the view" do
      do_get
      assigns[:page_title].should == "Best photo evar."
    end

  end

end

As you can see, the three specs are very similar and have some duplication between them. I should point out that duplication in tests is expected and is usually not a bad thing since documentation and readability are primary goals of having a test/spec suite. When extracting duplication from your specs you need to be very careful that these two aspects of the specs are not diminished. A lot of this will depend on the situation and the skill level of your team. In this example I would argue that this is such a common pattern that an abstraction wouldn’t hurt readability and in fact would help reduce some of the implementation noise (such as ‘do_get’.)

How do we want the “it_should_assign” macro to work? This example illustrates the different ways I use it in my specs:

describe UserPhotosController do

  describe "GET 'users/1/photos/2'" do

    before(:each) do
      User.stub!(:find).and_return( @user = mock_user)
      @user.stub_association!(:photos, :find => (@users_photo = mock_model(Photo, :caption => "Best photo evar.")) )
    end

    def do_get
      get :show, :user_id => @user.id, :id => @users_photo.id
    end

    it_should_assign :user # Here, the macro assumes assigns[:user].should == @user
    it_should_assign :photo, "@users_photo" # Have flexibility when the name differs in the spec
    it_should_assign :page_title, "Best photo evar." # Ability to check literals

  end

end

Dissecting part of RSpec’s DSL

Before I show the implementation, it is important to realize what the “describe” keyword really does. The “describe” keyword in rspec is actually a factory method (that in turn delegates to a factory object) that creates ExampleGroup sub-classes. In rspec source terminology your “describe” blocks are example groups and your “it” blocks are the examples. So, you can think of “describe” as being a sort of wrapper for “class.” To make this point more clear, we can forgo the use of the describe keyword and subclass the ExampleGroup class ourselves:

class UserPhotosControllerSpec < Spec::Rails::Example::ControllerExampleGroup
  describe UserPhotosController, "GET 'users/1/photos/2'"

    before(:each) do
      User.stub!(:find).and_return( @user = mock_user)
      @user.stub_association!(:photos, :find => (@users_photo = mock_model(Photo, :caption => "Best photo evar.")) )
    end

    def do_get
      get :show, :user_id => @user.id, :id => @users_photo.id
    end

    it_should_assign :user
    it_should_assign :photo, "@users_photo"
    it_should_assign :page_title, "Best photo evar."

  end

end

Inline the macro implementation into the current example group

Alright, so “describe” just subclasses the correct example group class for us and the block that gets passed in becomes our class definition. With that knowledge we can create our macro as a regular class method inside our example group:

describe UserPhotosController do

  describe "GET 'users/1/photos/2'" do

    before(:each) do
      User.stub!(:find).and_return( @user = mock_user)
      @user.stub_association!(:photos, :find => (@users_photo = mock_model(Photo)) )
    end

    def do_get
      get :show, :user_id => @user.id, :id => @users_photo.id
    end

    def self.it_should_assign(variable_name, value=nil)
      it "should assign #{variable_name} to the view" do
        raise "Variable '@#{variable_name}' was not defined in the spec" if value.nil? && !instance_variables.include?("@#{variable_name}")
        value ||= instance_variable_get("@#{variable_name}")
        if value.kind_of?(String) && value.starts_with?("@")
          value = instance_variable_get(value)
        end
        do_get
        assigns[variable_name].should == value
      end
    end

    it_should_assign :user
    it_should_assign :photo, "@users_photo"
    it_should_assign :page_title, "Best photo evar."

  end

end

Pretty simple, huh? At this point the macro is only available to that example group. There are several ways you can extract it so that it can be used elsewhere. Before we extract the macro we need to address the problem with the “do_get” call.

In my controller specs I follow the convention of defining a “do_get”, “do_put”, etc. based on the HTTP verb the action responds to. In order for the assigns macro to work across specs for different actions it needs to be able to call the correct do_verb method. We can accomplish this by defining a “do_action” method which calls the correct method:

describe UserPhotosController do

  describe "GET 'users/1/photos/2'" do

    ...

    def do_action
      verb = [:get, :post, :put, :delete].find{|verb| respond_to? :"do_#{verb}"}
      raise "No do_get, do_post_ do_put, or do_delete has been defined!" unless verb
      send("do_#{verb}")
    end

    def do_get
      get :show, :user_id => @user.id, :id => @users_photo.id
    end

    def self.it_should_assign(variable_name, value=nil)
      it "should assign #{variable_name} to the view" do
        ...
        do_action
        assigns[variable_name].should == value
      end
    end
    ...

  end

end

Extracting the macro

With the do_verb calls abstracted into the do_action method we can now extract the macro. The most flexible option is to turn it into a module. The following is a standard ruby module taking advantage of the Module#included hook so both instance and class methods are mixed in:

module AssignMacro
  module ExampleMethods
    def do_action
      verb = [:get, :post, :put, :delete].find{|verb| respond_to? :"do_#{verb}"}
      raise "No do_get, do_post_ do_put, or do_delete has been defined!" unless verb
      send("do_#{verb}")
    end
  end

  module ExampleGroupMethods
    def it_should_assign(variable_name, value=nil)
      it "should assign #{variable_name} to the view" do
        raise "Variable '@#{variable_name}' was not defined in the spec" if value.nil? && !instance_variables.include?("@#{variable_name}")
        value ||= instance_variable_get("@#{variable_name}")
        if value.kind_of?(String) && value.starts_with?("@")
          value = instance_variable_get(value)
        end
        do_action
        assigns[variable_name].should == value
      end
    end
  end

  def self.included(receiver)
    receiver.extend         ExampleGroupMethods
    receiver.send :include, ExampleMethods
  end
end

# Now, we can just include it wherever we need it...
describe UserPhotosController do

  describe "GET 'users/1/photos/2'" do
    include AssignMacro
    ...
  end

end

Extracting the macros out into modules allows you to mix them only into example groups that you want them to be in. In the case of this macro it would be nice to have it available for all controller specs. This is possible by monkey patching the ControllerExampleGroup in your spec_helper.rb:

module Spec::Rails::Example

  class ControllerExampleGroup
    include AssignMacro
  end

end

For controller macros I usually don’t take the extra step of extracting it into a standalone module. Instead, I just monkey patch my class and instance methods directly into ControllerExampleGroup. If you have a macro that you want available for all of your example groups rspec already has a place where you can put them:

    module Spec::Example

      module ExampleGroupMethods
        # place example group methods (class methods) here
      end

      module ExampleMethods
        # place your example helper methods (instance methods) like do_action here
      end

  end

Summary

Macros are useful when extracting granular facets of behaviour which you want to customize by passing in arguments. They are similar to shared behaviours but live at a different level (the class level) which allows for the additional flexibility. Shared behaviours are usually a better fit when a refactoring causes you to consolidate behaviour in a module or a class higher up in the inheritance chain. Macros tend to evolve out of common usage patterns within your specs and should be created when you want to dynamically create these slightly different specs. Documentation and readability are paramount when using both methods. If a macro saves you a couple of lines of duplicated code, but ends up hurting those two aspects of the spec, don’t use it!

I hope this article is helpful to people new to RSpec and to those who haven’t yet discovered this pattern. If anything is unclear just ask. Several people have asked me to release some of my macros and other rspec extensions that I use in all of my rails and merb projects. When I get the time I will clean them up and put them onto my github account . Until then, happy spec’ing!

Imperative Style

Lets look at the example I gave in my previous post (slightly modified):

Story: Animal Submission

  As a Zoologist
  I want to add a new animal to the site
  So that I can share my animal knowledge with the community

  Scenario: successful submission
  Given I'm on the animal creation page

  When I fill in Name with 'Alligator'
  And select Phylum as 'Chordata'
  And fill in Animal Class with 'Sauropsida'
  And fill in Order with 'Crocodilia'
  And fill in Family with 'Alligatoridae'
  And fill in Genus with 'Alligator'
  And check Lay Eggs
  And click the Create button

  Then I should see the notice 'Thank you for your animal submission!'
  And the page should include the animal's name, phylum, animal class, order, family, and genus

The imperative style uses highly reusable granular steps which outlines much of the user interface. This binds the scenario to that interface and requires more design decisions made up front. The step matchers for these granular steps are very easy to write as I demonstrated in my webrat post. Once these steps are in place you can write the majority of your scenarios in this fashion without having to write custom step matchers. Due to the granularity of the scenarios however they become very brittle as they are subject to requirement changes from the customer. If a new field is added, for example, you must update the scenario to reflect this even though the underlying goal of the scenario has not changed.

Declarative Style

Lets rewrite the above example in a more declarative fashion. The story narrative and scenario title will remain the same.

Story: Animal Submission

  As a Zoologist
  I want to add a new animal to the site
  So that I can share my animal knowledge with the community

  Scenario: successful submission
  Given I'm on the animal creation page

  When I add a new animal

  Then I should see the page for my newly created animal
  And the notice 'Thank you for your animal submission!'

This style is more aligned with User Stories in the agile sense having more of the “token for conversation” feel to it. The first thing that you should observe about this style is how much smaller it is than the imperative one. This is a good thing. The imperative style tends to produce noisy scenarios that drown out the signal. With the declarative style the goal of the scenario remains clear. When a new field is added to the form the scenario does not have to be modified. Yes, you will have to modify the underlying step matcher but the scenario does not have to suffer dilution due to the change. The trade off is, of course, that you will now be writing step matchers for all of your scenarios. Looking at our example, the implementation for the When step is very similar to the imperative scenario steps:

# animal_steps.rb
When "I add a new animal" do
  fills_in 'Name', :with => 'Alligator'
  selects 'Chordata', :from => 'Phylum'
  fills_in 'Animal Class', :with => 'Sauropsida'
  fills_in 'Order', :with => 'Crocodilia'
  fills_in 'Family', :with => 'Alligatoridae'
  fills_in 'Genus', :with => 'Alligator'
  checks 'Lay Eggs'
  clicks_button 'Create'
end

The majority of the imperative step matchers were merely wrappers for webrat so creating custom steps for each scenario is not much of a deterrent. Additionally, the reuse of steps will only take you so far before your stories start to feel unnatural as you try to force each scenario to use the same phrasing. Creating custom steps for each scenario actually turns out to be better for reducing duplication in most cases. That is because you can now extract duplicate code from the step matchers into helper methods. The place to put these helpers is in the Spec::Story::World module (monkey patch it.)

Another way to reduce duplication in step matchers that I learned recently is to call other steps directly within another one. For example, if you have this step:

Given "a user named $user_name" do |user_name|
  User.create!(:name => user_name, ....)
end

and you now want to have a step that matches ‘Given a user named Jim with a photo album’ you can reuse the above step directly in the new one like so:

Given "a user named $user_name with a photo album" do |user_name|
  Given "a user named #{user_name}"
  ....
end

I haven’t experimented with this approach too much so I’m not sure how much I like it, but I can see occasions where it would prove useful.

Choosing which style to use

I have made a strong case for the declarative style of writing scenarios. It would seem that one should never write a scenario imperatively based solely on the merits of maintenance and communicating story intent. While I think the declarative style has many strengths it is not the best choice for all situations. The imperative style should not be discounted entirely because when used judiciously in the right scenario it can highlight certain aspects of the functionality and improve communication. It is also important to realize that the two types are not mutually exclusive. The styles can be mixed throughout an app, a story, and even an individual scenario to provide the appropriate level of granularity as the situation demands.

One of the most important factors in deciding which type of style to adopt however has nothing to do with maintenance or code duplication; that factor is the customer. While these stories may be acting as integration tests for the developer that is not the original purpose. The stories are meant to facilitate communication between developer and stakeholder about business value and functionality. If your stakeholder needs each form field outlined in the scenario in order to have confidence in the system then the imperative style is a better route to go. Specs (unit tests) are just for the developer but stories need to appease the wider audience of developer and stakeholder so an appropriate balance needs to be reached. As in most areas of software development there is no right answer and in the end it just depends on the situation.

References

Aside from the materials already linked to in this post another great resource (actually, it is the best that I have found) on the various ways to approach story runner is David Chelimsky’s ETEC slides. In the slides he refers to the imperative style as detailed scenarios. He will be giving a similar talk at at RailsConf, so be sure to catch it if your able to make it to RailsConf this year.

I’d like to thank David Chelimsky, Kyle Hargraves, and Zach Dennis for their discussion on this topic on the rspec-users mailing list.

| View | Upload your own

During the presentation I attempted to show some actual code. Using git I had previously walked through the different ways of using the rspec story runner (ruby with inlined steps, with steps libraries, and plain text with steps) and tagged the progress as I went. You can download the git repo and look at the different ways of using the story runner by checking out the different tags.

To list the tags simply type ‘git tag’ and to checkout a tag into a new branch type ‘git checkout -b tag_name tag_name’.

story_runner_demo.tar.gz

Now, if you’re like me you have tons of git aliases setup. Shortly after setting up bash completion you will notice that your aliases don’t work with the new found goodness. What is a poor developer to do? Can’t I have bash completion with my aliases thus reducing the actual typing I have to do to close to zero? Well, not knowing too much about how bash completion works this was the best solution I came up with:

	
		## in my .bash_profile

		#Git aliases
		alias gco='git co'
		.....

		source ~/bin/git-completion.bash
		complete -o default -o nospace -F _git_checkout gco
		.....
	

If you look in git-completion.bash at the bottom you will see where it declares which bash functions are suppose to handle which git commands (via the built-in ‘complete’ command.) What I did was just find the correct function and assigned it to my corresponding git alias after the git bash completion file was sourced. I can now type ‘gco ‘, hit tab, and see all of my branches. Pretty cool, huh? I don’t think I can get any lazier.

I know that my bash-fu is still weak and I have much to learn… Is there a simpler way to do this so that bash completion expands your aliases? If not, I hope this helps other lazy git users.