aslakhellesoy / cucumber

160

1176

Description:

BDD that talks to domain experts first and code second

Home | Edit | New

Ruby on Rails

Cucumber supports Ruby on Rails out of the box. Currently the following Rails versions are known to be working:

v2.3.2
v2.2.2
v2.2.1
v2.2.0
v2.1.2
v2.1.1
v2.1.0

Older versions will never be supported as it requires too much work.

We strongly recommend you use Webrat in the Step Definitions. Here is how to get you started.

Install Cucumber, Webrat and RSpec

Ubuntu/Debian users: Follow these Nokogiri install instructions first.

You can use both Rubygems or Rails’ plugin mechanism. We usually recommend Rubygems. You can read a longer discussion here.

Using Rubygems

The easiest is to install everything as a gem.

[sudo] gem install rspec rspec-rails cucumber webrat

If you use gems, you have to make sure everybody on the team has the same version of the gems installed. Also note that you don’t have to use rspec and rspec-rails and webrat, but we suggest you use them unless you have good reasons to use something else.

Using plugins

Another option is to install the libraries as Rails plugins. If you use Git for your Rails app, here is how to do that:

git submodule add git://github.com/aslakhellesoy/cucumber.git vendor/plugins/cucumber
git submodule add git://github.com/brynary/webrat.git vendor/plugins/webrat
git submodule add git://github.com/dchelimsky/rspec.git vendor/plugins/rspec
git submodule add git://github.com/dchelimsky/rspec-rails.git vendor/plugins/rspec-rails

If your own Rails code is not in Git, just replace submodule add with clone. If you’re behind a proxy, try to replace git:// with http:// and set the http_proxy environment variable.

Install dependencies

The plugins’ dependencies must be installed separately:

gem install term-ansicolor treetop diff-lcs nokogiri builder

Behind a firewall?

As a last resort, download tarballs from GitHub.

Create Your Rails Project

Create the rails project with the following command:

rails YourProjectName

Don’t forget to create the corresponding databases.

Write all commands in the next steps from this project’s path.

Bootstrap Cucumber

You’ll need a Rake task and a couple of files that configure Cucumber for use with Ruby on Rails and Webrat. You create these with:

ruby script/generate cucumber

We recommend you use Spork and—drb so you can run your features faster:

ruby script/generate cucumber --spork

For more help on the generator you can just ask for help:

ruby script/generate cucumber --help

Take a look at the generated files. If you need to, you can tweak them later.

Start a feature

It’s really, really recommended that you write your features by hand – in collaboration with your customer / business analyst / domain expert / interaction designer. However, to get you started (and so you can see how to use Webrat), you can use the feature generator to generate the first few features:

ruby script/generate feature Frooble name:string color:string description:text

This will generate a simple plain text feature with associated steps. Don’t get addicted to this generator – you’re better off writing these by hand in the long run.

Important: The generated feature will fail unless you have set up a layout in your app. This is because Webrat fails to parse HTML that isn’t well formed (i.e. has a single <html> root node). Here is a simple layout you can use, but I hope you have a better one yourself.

Run features

If working on a fresh Rails project, first set up the (empty) database:

rake db:migrate

(Otherwise Cucumber fails with the error no such file to load -- YourProjectName/db/schema.rb.)

Then run the features:

rake features

This should result in failing scenarios, because you haven’t written any code yet (I hope).

Now it’s time to write some code, or generate some. Try this:

script/generate rspec_scaffold Frooble name:string color:string description:text
rake db:migrate
rake features

Other ways of running features

You can also run specific features directly with cucumber:

cucumber --require features --require lib features/subdir/
cucumber --require features --require lib features/some-nifty.feature

And using autospec with a similar setting (--require features --require lib), applied in your project’s /cucumber.yml:

autotest-all: --require features --require lib --format progress features
autotest: --require features --require lib features  
default: --format pretty
html: --format html --out features.html

Remember that you need AUTOFEATURE=true for autospec to include cucumber features. See Running Features and Autotest Integration for more info.

View spec redundancy

Since I recommend you verify outcomes (Then steps) by looking at the HTML, you might end up having some degree of redundancy with view specs. I recommend you delete generated view specs if you run into too much maintenance headaches and rely on the features instead of view specs. However, in some cases it can be handy to use both.

Authentication

Some guidance for authentication is provided below. It is recommended that a new user is created, rather than loaded through fixtures or etc.

In the .feature, use a phrase similar to Given a user is logged in as "markEmark", and add the following to your relevent step definitions.

Given /^a user is logged in as "(.*)"$/ do |login|
  @current_user = User.create!(
    :login => login,
    :password => 'generic',
    :password_confirmation => 'generic',
    :email => "#{login}@example.com" 
  )

  # :create syntax for restful_authentication w/ aasm. Tweak as needed.
  # @current_user.activate! 

  visit "/login" 
  fill_in("login", :with => login) 
  fill_in("password", :with => 'generic') 
  click_button("Log in")
  response.body.should =~ /Logged/m  
end

Upgrading to Cucumber 0.2 from Earlier Versions

From the release notes:


IMPORTANT NOTE FOR RAILS USERS.
The template used to generate your features/support/env.rb has changed. You have to apply a minor change
manually for existing Rails projects when you upgrade to this version. Change this:

  require 'webrat/rspec-rails'

to this:

  require 'webrat/core/matchers'

Last edited by aslakhellesoy, Fri Jun 05 07:45:48 -0700 2009