Michael MacDonald

Pickle my Cucumber!

In Rails, Testing on October 28, 2009 at 8:00 am

If you are using Cucumber then I would highly recommend using Ian White‘s fantastic little add-on called Pickle.

Pickle makes life in the Cucumber world so much easier by providing you with convenient step definitions that take care of common object operations leaving you free to focus on the fun stuff. Combined with the pre-packaged Webrat steps you can dramatically reduce the number of step definitions you need to write.

Pickle allows you to easily create objects from your factories (Factory Girl), blueprints (Machinist) or ActiveRecord. Here’s a simple example:

Given a person exists

This simple cucumber step will use your User factory/blueprint/model to create a user object. You can also pass in specific values for your object, overriding the factory default (notice the use of the word ‘another’):

And another person exists with name: "Digby"

And for multiple attributes:

And another person exists with name: "Ethyl", age: 27, employed: true

We can also assert the existence of an object:

Then a person should exist with name: "Ethyl"

And you can verify the number of objects that exist:

And 3 people should exist

We can now access each one of these objects and check the truth of a predicate:

And the last person should be an adult
And the 2nd person should not be employed

This will assert that Ethyl is an adult eg @ethyl.adult? And finally we can label our objects for easy reference to distinguish between multiple objects of the same type:

Given a company exists
And another company: "rubyflare" exists

Pickle can also handle associations:

And a person exists with company: company "rubyflare"
And another person exists with company: the first company

And assertions with those associations:

Then the first person should be one of company: "rubyflare"'s employees

Wow! That’s a lot already and all without writing a single step definition. But wait, there’s more. Pickle also provides step definitions for email and paths. Here’s a scenario with an email cucumber step:

Given a person exists with email: "fake@address.com"
When I activate that person
Then 1 email should be delivered to fake@address.com

The last step is provided by Pickle’s email step definitions. Now let’s look at using Pickle for paths:

Given a company exists with name: "Ruby Flare"
When I go to the companies page
Then I should see "Listing companies"

Pickle adds onto the paths setup provided by Cucumber to give more generic path matchers including named routes. In this case, we are visiting the companies_path, the index action of our companies controller. Now we are going to the show action of the controller for the specified company:

When I go to the company's page
Then I should see "Ruby Flare"

And also to a named route:

When I go to the users page
Then I should see "Listing people"

Pickle can also handle nested routes:

When I go to the company's employees page
Then I should see "Listing employees"

Finally, you can create custom step definitions that use Pickle methods. Earlier I had the following step:

When I activate that person

This was actually a step that I had to write a step definition for:

When /^I activate #{capture_model}$/ do |name|

The model method is from Pickle and lets me access the object that is captured via Pickle’s #{capture_model} regexp. My step will let me match any of the following examples:

When I activate the person
When I activate the 2nd person
When I activate the person: "maya"

There is a whole range of other Pickle regexps and additional methods like models, create_model and find_model. These allow you to create your own special step definitions leveraging off the fantastic convenience provided to you by Pickle.

So that’s a quick introduction to the joys of using Pickle with Cucumber. Download the gem, check out the readme and the code, and start using it in your Rails projects. You can also clone a copy of my pickle_example project and play around with it.

Pickle is an essential ingredient in my recipe for pure BDD joy. I hope you enjoy it too!

Update (4/11/09): Ryan Bates has done a screencast about Pickle! Go check it out.

  1. […] Pickle Action In Rails, Testing on November 3, 2009 at 8:00 am In a previous blogpost I championed the benefits of using Pickle with Cucumber to speed up your BDD. Recently, I was able […]

  2. Great write-up schlick!

  3. […] In Rails, Testing on November 26, 2009 at 12:12 am Following on from my original and followup articles on using Pickle with Cucumber, a brand new version of Pickle is now […]

  4. […] Pickle is a step definition builder which intelligently generates step definitions based on your activerecord/mongomapper/mongoid models.  I re-wrote a lot of our features today using pickle and managed, with a bit of feature fiddling, to cut down the number of definitions by half.  There is nothing better than a good example to get started and there is a great example […]

  5. Very interesting write-up, great work!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: