Add a ? immediately following the pluralized word:

        Then /^the users? should receive an email$/ do
          # ...
        end
    

The ? specifies that your looking for zero or more of the proceeding character. So the above example will capture both user and users.

2. Use non-capturing groups to help steps read naturally.

You can create non-capturing groups by adding a ?: to the beginning of a otherwise normal group (e.g. (?:some text) rather than (some text)). This is treated exactly like a normal group except that the result will is not captured and thus not passed as an argument to your step definition. This often useful in conjunction with alternation:

        And /^once the files? (?:have|has) finished processing$/ do
          # ...
        end
    

Or another pattern I use regularly:

        When /^(?:I|they) create a profile$/ do
          # ...
        end
    

3. Consolidate step definitions by capturing optional groups.

Often I find myself writing essentially the same step with both positive and negative assertions. You can remove this duplication by capturing an optional group:

        Then /^I should( not)? see the following columns: "([^"]*)"$/ do |negate, columns|
          within('table thead tr') do
            columns.split(', ').each do |column|
              negate ? page.should_not(have_content(column)) : page.should(have_content(column))
            end
          end
        end
    

Here we’re capturing an optional group (note ( not)? using the ? mentioned above). We then pass that into our step as the negate variable which we can use to write conditional assertions.

4. Not all matched phrases need to be surrounded by quotes.

Don’t assume that matched phrases must (or should) be enclosed in double quotes. Often quotes are a good idea. They make it visually clear which phrases will be passed to the step definition. For example:

        Given I have "potatoes" in my cart
    

That’s reasonable. The quotes highlight the parts that change without hurting readability. But sometimes, quotes are just poor style:

        Given I have "7" items in my cart
    

It should be pretty obvious that the number is variable. The quotes add nothing except noise. A better step would read:

        Then /^I have (\d+) items? in my cart$/ do |item_count|
          item_count.to_i.times { ... }
        end
    

5. Use transforms to make smarter, DRYer regular expressions.

There’s an opportunity to refactor the previous example. Do you see it? Cucumber passes everything as a string, so you must remember to convert types within your step definition (e.g. above we use to_i to transform item_count into a proper integer). That’s annoying and easy to forget.

Fortunately, Cucumber gives us a way to avoid this peskiness by using Transform:

        CAPTURE_A_NUMBER = Transform /^\d+$/ do |number|
          number.to_i
        end
    

And we can use this in our steps:

        Then /^I have (#{CAPTURE_A_NUMBER}) items? in my cart$/ do |item_count|
          item_count.times { ... }
        end
    

Not only have we removed the need to call to_i but we’ve also moved our regex into a reusable constant.

6. Define methods to DRY up your step definitions.

Sometimes it’s a good idea to remove duplication by defining methods. For example, it’s common to define a current_user method:

        def current_user
          User.find_by_email('current_user@example.com')
        end
    

Similarly, if you find yourself wrapping several steps with the same logic, you might consider making a helper method. On Scholastica, we test a lot of lightboxes using of this method:

        def within_lightbox(opts = {sleep: 0} )
          sleep(opts[:sleep])
          within_frame("prettyPhotoIframe") { yield }
        end
    

And our step definitions stay nice and clean:

        Then /^some stuff should be visible in the lightbox$/ do
          within_lightbox { page.should have_content('Some Stuff') }
        end
    

By convention, these methods should live in features/support/world_extensions.rb and be included in the Cucumber World module. But keep in mind this is a tradeoff: you’re removing duplication but adding indirection. You should be reluctant to define methods until the code makes it very obvious that it’s a good idea.

7. Use steps within steps.

Sometimes it’s useful to call steps within steps. Another example from Scholastica:

        When /^the request for an expedited decision should be canceled$/ do
          manuscript.should_not be_expedited
          step %{"#{current_user.email}" should receive an email with subject "Expedited decision request canceled"}
        end
    

But don’t go crazy, it’s better to use the capybara methods directly when possible:

        When /^I update the email template to read "([^"]*)"$/ do |text|
          fill_in("email_template[text], with: text)
          click_button("Save changes and close")
          # Rather than...
          # step %{I fill in "email_template[text]" with "#{text}"}
          # step %{I press "Save changes and close"}
        end
    

8. Improve readability with unanchored regular expressions.

Most step definitions look something like:

        Given /^I am an admin user$/ do |item_count|
          # ...
        end
    

Note we’re using ^ and $ to anchor our regex to the start and end of the captured string. This ensures the regular expression exactly matches “I am an admin user” (i.e. allows no additional words at the beginning or end of the step). Most of the time, this is exactly what want.

Occasionally, however, it makes sense to omit the final $. Take this step for example:

        Then /^wait (\d+) seconds/ do |seconds|
          sleep(seconds.to_i)
        end
    

Now you can use this definition to write flexible, expressive steps:

        Then wait 2 seconds for the revenue statistics to finish loading
        Then wait 5 seconds while the document is converted
    

9. When your steps must include data, use tables.

Generally, steps should be human readable and that means they shouldn’t include loads of cryptic data. But sometimes, you have no other choice. In those cases, use tables to clearly represent the data:

        Given "Frankie's Hams" are selling for $25:
        And the following orders have been placed:
          | buyer email      | quantity |
          | eddy@example.com | 3        |
          | matt@example.com | 2        |
    

Using tables within your step definitions can get a bit tricky. I use this helper method but you should really read the relevant source code and figure out what makes sense for your application.

10. Don’t get carried away and spoil a good thing.

As you use these tips, remember that tests should favor clarity over cleverness. In other words, if you’re removing a small amount of duplication but adding a lot of complexity, that’s a poor tradeoff. Here’s an example from Scholastica:

        Given /^(?:I|they) have opened (?:a|an) ([^\s]+) invitation$/ do |invitation_type|
          invitation = Factory("#{invitation_type}_invitation".to_sym, recipient: current_user, to: current_user.email)
          reset_mailer
          eval "ApplicationMailer.invite_#{invitation_type}(invitation).deliver"
          open_email(current_user.email)
        end
    

This steps allows us to write both Given I have opened a reviewer invitation and Given I have opened an editor invitation. I’d say this step is borderline too complex (lots of interpolation and an eval). Maybe it would be better to just write two separate steps? Remember no one is testing your tests so don’t fuck around. A little bit of duplication is not the end of the world.

      has_attached_file :article_text,
        :storage => :s3,
        :s3_credentials => {
          :bucket => ENV['AS3_BUCKET'],
          :access_key_id => ENV['AS3_ACCESS_KEY_ID'],
          :secret_access_key => ENV['AS3_SECRET_ACCESS_KEY']
        }
       :s3_permissions => :private,
       :processors => [:manuscript_converter],
       :path => "manuscript/:id/:uploaded_manuscript_filename"
    

Many of these settings will be repeated in every paperclip’d model. You can easily remove that duplication by adding an initializer. In config/initializers/paperclip_defaults.rb:

      Paperclip::Attachment.default_options.merge!(
        :storage => :s3,
        :s3_credentials => {
          :bucket => ENV['AS3_BUCKET'],
          :access_key_id => ENV['AS3_ACCESS_KEY_ID'],
          :secret_access_key => ENV['AS3_SECRET_ACCESS_KEY']
        }
      )
    

And now you can remove those options from all your models – separating the parts that change from the parts that stay the same.

I had trouble finding this online and had to dig through the source code to figure it out. So maybe it will help someone else save a little time.

        def twitter_url(resource, tweet_text="Check out this article from my-site.com:")
          tweet_url = root_url.chop + url_for(resource)
          "http://twitter.com/home?status=#{tweet_text} #{tweet_url}"
        end
    

This method just builds a url to twitter and supplies some default text which you may optionally override by passing a second argument. Call it in your view like this:

        <%= link_to "Retweet this post!", twitter_url(@post) %>
    

Now, this method works but it would be much better if we could use shortened urls. So let’s change things a bit in order to use bit.ly — twitter’s preferred url shortening service. Before we write any code…

1. You’ll need to sign up for bit.ly.
2. And grap your api key.

With that info on hand, we’re ready to interface with the bit.ly api. Let’s make another helper method also located in app/helpers/application_helper.rb:

        def shorten_with_bitly(url)
          # build url to bitly api
          user = "insert-your-username"
          apikey = "insert-your-api-key"
          version = "2.0.1"
          bitly_url = "http://api.bit.ly/shorten?version=#{version}&longUrl=#{url}&login=#{user}&apiKey=#{apikey}"

          # parse result and return shortened url
          buffer = open(bitly_url, "UserAgent" => "Ruby-ExpandLink").read
          result = JSON.parse(buffer)
          short_url = result['results'][url]['shortUrl']
        end
    

This method uses your credentials to build a url to interface with the bit.ly api. Bitly receives our request and returns a JSON object containing a shortened url. We’ll parse this object, grab the shortened url, and return it.

Finally, we need to change our initial twitter_url method to include url shortening:

        def twitter_url(resource, tweet_text="Check out this article from my-site.com:")
          tweet_url = root_url.chop + url_for(resource)
          tweet_url = shorten_with_bitly(tweet_url) if Rails.env.production?

          "http://twitter.com/home?status=#{tweet_text} #{tweet_url}"
        end
    

This is identical to our original method except we’ve added a new line which calls shorten_with_bitly. This line overwrites the tweet_url variable — replacing the long url with a shortened version. Finally, we’ll include a condition to ensure this only happens in production. This saves us from creating a bunch of useless bit.ly links that point to localhost urls.

Some final points.

• The shorten_with_bitly method borrows heavily form a ruby snippet posted by Puneet Pandey. Pandey definitely deserves some credit here.
• If you’re looking for a more robust way to interface with the bit.ly api, checkout this url shortening gem by Nasir Jamal. I’ve never used it but appears to be fully featured and well documented.

Just add these lines to config/environments/test.rb:

		config.gem 'rspec-rails' , :lib => false
		config.gem 'rspec' , :lib => false
		config.gem 'cucumber'
		config.gem 'webrat'
	

Next, make sure these gems are installed by typing:

		RAILS_ENV=test sudo rake gems:install
	

Finally, you’ll need to bootstrap your rails application for development with Cucumber and RSpec. Simply type:

		script/generate rspec
		script/generate cucumber
	

That’s it. Now you’re set up for behavior driven development in your rails app.

Now, jQuery makes this functionality super easy – just a few lines of code. But here’s the tricky part: the configuration of each profile page needs to be stored in your database and be associated with a given user. Otherwise users would lose all their changes on page refresh. No good.

This means every time a user changes something (e.g. removes a stock ticker) you need to let rails know the profile has been changed so that the appropriate columns can be updated in your database (e.g. set the ticker’s ‘hidden’ boolean to true). And ideally, this should all happen silently in the background so that the user’s not even aware their changes are being saved on the fly.

Now, we’re talking about making the client talk to the server without a page refresh. That means AJAX. So here’s the plan…

1. Create your javascript event.

For simplicity, say you’d like to let the user can change the background color of their profile page. Let’s give them three buttons to toggle between red, yellow, and purple. Your html would look like this:

<body>
Make Green
Make Yellow
Make Purple

</body>

And your jQuery would look like this:

$('.change_bg_color').click(function() {
	if (this.id == 'green') { $('body').css('background-color', 'green') };
	if (this.id == 'yellow') { $('body').css('background-color', 'yellow') };
	if (this.id == 'purple') { $('body').css('background-color', 'purple') };
});

That will get our background changing color, but as soon as the page refreshes we’ll lose our changes. So let’s get rails involved.

2. Set up the appropriate models and associations

I’ll move pretty quickly here cause it’s so easy. I assume you have a current_user stored in your session. I’ll also assume you’ve set up a one-to-one association between ‘users’ and ‘profile_settings.’ This means you should be able to do something like this in your controller:

def make_background_green
	current_user.profile_setting.update_attributes(:background_color => 'green')
end

And then you can apply this color using inline style:

<body style="background-color=<%= current_user.profile_setting.background_color %>;" >
<%= link_to "Make Green", :action => "make_background_green" %>
<%= link_to "Make Yellow", :action => "make_background_yellow" %>
<%= link_to "Make Purple", :action => "make_background_purple" %>

</body>

Of course this is just nasty for a couple of reasons: (a) you’d have to write a new method for each possible color, (b) the markup is sort of ugly, and (c) we’re relying on a page refresh to do the work. So let’s clean this up a bit using AJAX.

3. Update your profile settings via AJAX.

First, let’s get our html looking better:

<body style="background-color=<%= current_user.profile_setting.background_color %>;" >
Make Green
Make Yellow
Make Purple

</body>

Then lets add some AJAX to our click event:

$('h3').click(function() {
	if (this.id == 'green') { $('body').css('background-color', 'green') };
	if (this.id == 'yellow') { $('body').css('background-color', 'yellow') };
	if (this.id == 'purple') { $('body').css('background-color', 'purple') };		

	$.post('http://your_site.com/profile_controller/change_background_color', {
		'background_color' : this.id
	});
});

Here’s where you need to pay attention. We’re sending an AJAX post request with two arguments: (1) the url we’d like to load and (2) the data we’d like to pass along as a key/value pair. This means your controller is going to fire the ‘change_background_color’ action and will have access to the params[:background_color] with a value equal to the clicked element’s id.

And so your controller will look like this:

def change_background_color
  current_user.profile_setting.update_attributes(:background_color => params[:background_color])
  render :nothing => true  # make sure the action knows not to load a template
end

4. Mission accomplished.

Your profile settings should now be updating quietly in the background. If you have any problems, start up firebug and watch your AJAX hit register in the console log. This can be very helpful when debugging. But don’t get discouraged. Once you get this process down, all sorts of cool things become possible.

class String
  def reverse_each_word
    self.split.collect { |word| word.reverse }
  end
end

That works but suppose you wanted to abstract this logic to use elsewhere. So instead let’s write a method to iterate through each word in the sentence, yielding the result to a block. Then you can do whatever you want to each word (upcase, reverse, length, capitalize, etc). Now that’s a bit trickier:

class String
  def each_word
    self.split.each { |word| yield word }
  end
end

And now you have a more flexible method which can do things like this:

"This is a very short sample string".each_word do |word|
  word.reverse.upcase
end

Neat. But what’s going on here? The reverse_each_word method is pretty vanilla – take a string, split the words into an array, reverse them, and return the collection. The each_word method, however, is less straight forward. It starts out much the same – take a string, split the words into an array but then…

Well, it’s actually pretty simple. We use the keyword yield to let ruby know that our method is going to accept a block. And, more specifically, we’re telling ruby we’d like each word in our array to be yielded as parameters within that block. Now we can iterate through through each of our words – manipulating them however we please.