Much of the online documentation for Cucumber dives right in. Here are some pointers for those very first cucumber steps for absolute newbies. I also recommend Ryan Bates’s RailsCast for a good introduction.

Step 1.
Install & configure your gems:

sudo gem install rspec rspec-rails webrat cucumber-rails thoughtbot-factory_girl

To install git for textmate, see

Go to environments/test.rb.

Add these gems to the bottom of this file:

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

(note: if you don’t include the :lib => false parameter you might get a “no such file to load – rspec” – not sure why this happens)

Step 2.

script/generate cucumber

(this creates a features/ and features/step_definitions directory)

Step 3.
make a new xyz.feature file in features/
(where “xyz” is the name of your feature)

Step 4.
Write your feature. See numerous examples and documentation for how to write features.

Step 5.
run “cucumber features/xyz.feature”
(where “xyz” is the name of your feature)

You will see undefined steps which say “pending” only in the body of the method. Cucumber conveniently creates these to help you along your way

Step 6. Make a new file here:

Copy and paste the undefined steps from Cucumber (these are in yellow at the bottom of your code).


cucumber scenarios -t sometag

where “sometag” is the name of your tag (tags appear with @ before the scenario you want to tag inside your feature definitions)


There are two important Cucumber configuration settings you should know about. Most important, you should know & understand what they do so you can choose when to comment them out or leave them enabled.

Both of these are in features/support/env.rb which is where Cucumber’s settings are.

1. Cucumber::Rails.use_transactional_fixtures

This setting tells Cucumber to use database transactions when running the tests. Why this is significant is because when using Factories, you probably DO want to leave this enabled. This will mean that when your tests are finished running, the transactions will be rolled-back and whatever data was loaded during the running of the tests will be removed from the database. (This is how you want it when using factories). However, if you’re debugging something, you might want to SEE the data in the database just to make sure you’ve setup your factories correctly. If the data is erased after the tests run, you can’t see it. So comment out this line and Cucumber will leave the data you loaded in the database when the test finish for you to examine.

In some applications, this might cause problems the next time you run your tests. For example, you might get a “duplicate not allow” error if the next time you run your factory you are trying to insert a record that already exists (possibly because of a Rails validation error or because of a duplicate MySQL primary key). So generally I leave the line above ENABLED (using transactional fixtures), but only disable it if I have to see the data after the test runs. Then, I manually empty those tables after I run my test because I’ll get some duplicate error if I don’t and try to re-run my tests. (If you have no validates_uniqueness_of and your factories don’t have ID numbers in them, this problem might not apply to you.)

2. Cucumber::Rails.bypass_rescue

I was having some trouble debugging some failing tests, so I did a bit of research and found out that there are some key things to know to make this easier.

For one, when you have a rails error (raised exception), by default you don’t see the full text of the stack trace. You just see the error in red when you run your cucumber test. In my case, I was getting “You have a nil object when you didn’t expect it,” but without a stack trace I couldn’t tell where that nil was being evaluated, so I couldn’t track it down to see where the error was being raised. In my cucumber output I could see the error but it wasn’t showing me the file name of where the error was raised or the line number.

All you have to do to fix this is DISABLE the setting Cucumber::Rails.bypass_rescue. If Rails raises an error during your tests, Cucumber will A) show you the full output in red in your test runner, and B) open a new window in your web browser that shows a special cache of the Rails error itself, just like it looks when you are in development.

By Jason