Jim Drannbauer home resume

Rails 3, RSpec, Cucumber, jQuery, Devise, Mongoid, and Compass

29 Jan 2011

Want to build a Rails 3 app with this stuff?

Here’s how.

Just A Checklist

This article is mostly written for myself so I don’t have to remember where I found all of the information. There’s nothing particularly difficult about anything here. I just like the idea of having it all in one place. I figured it might be helpful to others, so… uh… here it is.

Having said that, this is not a tutorial. I don’t explain how to do Behavior Driven Development, how to use CanCan, or why to use any of this stuff. It’s just a checklist… a detailed checklist. It would probably make a good Rails Template.


The installation of MongoDB and Git are beyond the scope…

Initialize the app

In your shell:

mkdir awesome-app
cd awesome-app
git init
rails new . -T -J -O

Create the empty directory first so that you can init an empty git repo. The -T option excludes the Test/Unit files so that we can use RSpec instead. The -J option excludes the prototype.js files so that we can use jQuery instead. The -O option excludes ActiveRecord (O is for ORM) so that we can use Mongoid instead.

Commit it:

git add .
git commit -m "initial commit"

Bundle the Gems

Here’s the first place you need to modify files. In Gemfile:

source 'http://rubygems.org'
gem 'rails',    '3.0.3'
gem 'mongoid',  '2.0.0.rc.6'
gem 'bson_ext', '~> 1.2'
gem 'devise'
gem 'cancan'
gem 'jquery-rails'
gem 'passenger'
gem 'capistrano'
gem "compass", ">= 0.10.6"
gem 'haml'
group :development, :test do
  gem 'capybara'
  gem 'cucumber'
  gem 'cucumber-rails'
  gem 'database_cleaner'
  gem 'rspec'
  gem 'rspec-rails'
  gem 'shoulda'
  gem 'factory_girl_rails'
  gem 'autotest'
  gem 'launchy'
  gem 'faker'
  gem 'ruby-debug19'
  gem 'haml-rails'
  gem 'metric_fu'

Then, back in your shell:

bundle install

Commit it:

git add .
git commit -m "Added Gems"


Mongoid is an ORM for MongoDB. I’ll assume you have it installed already. Dig it:

# Ignore this message if you see it since you're
# running the command it's asking for right now:

# Mongoid config not found. Create a config file at: config/mongoid.yml
# to generate one run: rails generate mongoid:config

rails g mongoid:config

After running the mongoid generator, your app is configured to use Mongoid instead of ActiveRecord. When you generate a model, Rails will generate a Mongoid Document.

Let’s edit some files and get it set up.

In config/mongoid.yml:

defaults: &defaults
  host: localhost
  # mongoid defaults for configurable settings
  autocreate_indexes: false
  allow_dynamic_fields: true
  include_root_in_json: false
  parameterize_keys: true
  persist_in_safe_mode: false
  raise_not_found_error: true
  reconnect_time: 3
  <<: *defaults
  database: awesome_app_development
test: &TEST
  <<: *defaults
  database: awesome_app_test
  <<: *TEST
# set these environment variables on your prod server
  host: <%= ENV['MONGOID_HOST'] %>
  port: <%= ENV['MONGOID_PORT'] %>
  username: <%= ENV['MONGOID_USERNAME'] %>
  password: <%= ENV['MONGOID_PASSWORD'] %>
  database: <%= ENV['MONGOID_DATABASE'] %>

There are 2 things to notice here. First, the configurable settings can be excluded. Even though Mongoid will default to the above options, leave them so that you don’t have to look at the documentation. Second, we added an environment for Cucumber which just points back to the test environment.

Commit it:

git add .
git commit -m "Added Mongoid"


Now, we use the rails generator to install RSpec. Shell:

rails g rspec:install

Next, in spec/spec_helper.rb:

RSpec.configure do |config|
  config.mock_with :rspec

  require 'database_cleaner'

  config.before(:suite) do
    DatabaseCleaner.strategy = :truncation
    DatabaseCleaner.orm = "mongoid"

  config.before(:each) do

This is all you need in your RSpec configuration to use it with Mongoid. MongoDB doesn’t do transactions so we need to truncate the database between tests instead of rolling back. DatabaseCleaner helps with that.

Commit it:

git add .
git commit -m "Added RSpec"


Next, we use the rails generator again to install Cucumber. Shell:

rails g cucumber:install --capybara --rspec --skip-database

The –capybara option sets up Capybara instead of Webrat. The –rspec option enables RSpec matchers for your step definitions.

The Cucumber generator will bark at you about a missing database.yml file without the –skip-database option because we skipped the ORM when we created the app.

Like RSpec, some configuration is necessary to make Cucumber play nice with Mongoid. Add this file, features/support/database_cleaner.rb:

require 'database_cleaner'
DatabaseCleaner.strategy = :truncation
DatabaseCleaner.orm = "mongoid"
Before { DatabaseCleaner.clean }

This does the same thing for Cucumber that it does for RSpec: truncates your data between scenarios.

Commit it:

git add .
git commit -m "Added Cucumber"


Devise is used for authentication.

Shell it:

rails g devise:install

Devise needs a few things in place so that it can provide it’s functionality and it’ll let you know it when the installation is done:


Some setup you must do manually if you haven't yet:

  1. Setup default url options for your specific environment. Here is an
     example of development environment:

       config.action_mailer.default_url_options = { :host => 'localhost:3000' }

     This is a required Rails configuration. In production it must be the
     actual host of your application

  2. Ensure you have defined root_url to *something* in your config/routes.rb.
     For example:

       root :to => "home#index"

  3. Ensure you have flash messages in app/views/layouts/application.html.erb.
     For example:

       <p class="notice"><%= notice %></p>
       <p class="alert"><%= alert %></p>


For now, all you need to do are steps 1 and 2 above. We’ll handle step 3 when we get into the Haml/Sass/Compass stuff later.

In config/environments/development.rb, add this:

config.action_mailer.default_url_options = { :host => 'localhost:3000' }

In config/routes.rb, add this:

root :to => "home#index"

Finally, Devise needs a model to hold login credentials. Let’s call it User. In the shell:

rails g mongoid:devise User

Take a look in app/models/user.rb. Notice that it generated a Mongoid Document.

Finish up by adding this to routes.rb:

devise_for :users

Commit it:

git add .
git commit -m "Added Devise"


CanCan does role-based user authorization.

rails g cancan:ability

That’s it.

Commit it:

git add .
git commit -m "Added CanCan"


We used the -J option when we created the app so that we could use jQuery instead of Prototype. In your shell, run the jQuery generator:

rails g jquery:install --ui

This’ll do 3 main things: remove the existing protoypejs-based javascript files (which, in our case, aren’t there anyway), drop in the latest jQuery, and drop in the jQuery version of the Rails Unobtrusive Javascript (UJS) Adapter. Since jQueryUI is pretty cool too, we drop that in too with the –ui option.

In order to make the :defaults argument to javascript_include_tag load the .js files in the right order, we need to modify config/application.rb. Look for:

config.action_view.javascript_expansions[:defaults] = %w()

and change it to:

config.action_view.javascript_expansions[:defaults] =
  %w(jquery.min jquery-ui.min rails)

Notice that we load the minified versions which were downloaded by the generator.

Commit it:

git add .
git commit -m "Added jQuery"


Haml is a template langauge like erb. When we added “gem ‘haml’” to the Gemfile, we made Rails recognize that files with the .haml extension contain Haml markup. Sass is a superset of css3 that helps keep your stylesheets clean. Blueprintcss is a css framework that provides easy to use reset, grid, and typographical styles. Compass ties all this together and provides a way to integrate it into your app.

Run this to install Compass into your app using Blueprintcss:

compass init rails . --using blueprint/semantic

Compass will ask you a few questions. Just say yes to both of them.

Compass recommends that you keep your stylesheets in app/stylesheets
  instead of the Sass default location of public/stylesheets/sass.
  Is this OK? (Y/n) Y

Compass recommends that you keep your compiled css in public/stylesheets/compiled/
  instead the Sass default of public/stylesheets/.
  However, if you're exclusively using Sass, then public/stylesheets/ is recommended.
  Emit compiled stylesheets to public/stylesheets/compiled/? (Y/n) Y

After that, it’ll drop a bunch of files into the app and finish up with some instructions. We’ve already done the first suggestion, added Compass to the Gemfile. The second suggestion gives us the opportunity to put together our layout.

Create app/views/layout/application.html.haml and place this inside:

!!! XML
    %title Awesome App
    = javascript_include_tag :defaults
    = csrf_meta_tag
    = stylesheet_link_tag :all
    = stylesheet_link_tag 'compiled/screen.css', :media => 'screen, projection'
    = stylesheet_link_tag 'compiled/print.css',  :media => 'print'
    /[if lt IE 8]
      = stylesheet_link_tag 'compiled/ie.css', :media => 'screen, projection'



        %h1 Awesome App Header

        %div item 1
        %div item 2
        %div item 3
        %div item 4


        %p.notice= notice
        %p.error= alert
        %p.success= notice

        = yield

        %h3 Awesome App Footer

There are a few things to notice in there. First, it’s Haml. Second, we’ve included the stylesheet info from the compass command output in the head. Third, we’re using the built-in Blueprintcss 2-column layout. Finally, we’ve added the notice and alert elements that Devise asked for earlier. There’s also a success element in there to show off some of the coloring that Blueprintcss gives you.

If you try to look at it now, it won’t work. Sit tight, we’re close.

Making Compass Just Work

The Compass documentation seems to lack a simple explanation of how to see if things just work. Here it is:

Create app/stylesheets/partials/_application.scss, and place this inside:

#container {
  @include showgrid;

Use this file to get started adding your own styles. The showgrid mixin is useful for debugging your Blueprintcss grid. Delete it or comment it out when you’re done.

Then, add this to app/stylesheets/screen.scss:

// Add the application styles.
@import "partials/application";

This makes sure that your own styles are available when you get around to adding them.

Commit it:

git add .
git commit -m "Added Compass"

Last Steps Before Starting the App

Delete public/index.html:

rm public/index.html

Earlier, Devise instructed us to setup the root route in routes.rb. The problem is the route we added won’t actually work until we have a home controller with an index action.

Shell it:

rails g controller home index

Notice that the views generated use Haml. That works because we added the ‘haml-rails’ gem to the Gemfile.

Then, so that we can see Devise in action:

rails g controller vip index

In app/controllers/vip_controller.rb, add:

before_filter :authenticate_user!

Commit it:

git add .
git commit -m "Added Home and Vip controllers and views"

Start It Up

passenger start

Now go to: http://localhost:3000

Nice! See the grid? Clean.

How about this one? http://localhost:3000/vip/index

Go ahead. Mess with the login stuff. It’ll just kinda work.

One More Thing, metric_fu

Add this to your Rakefile:

require 'metric_fu'
MetricFu::Configuration.run do |config|
  config.rcov[:test_files] = ['spec/**/*_spec.rb']
  config.rcov[:rcov_opts] << "-Ispec" # Needed to find spec_helper

Get your metrics by running this:

rake metrics:all

Commit it:

git add .
git commit -m "Added metric_fu"


Okay, so it doesn’t really do anything… yet. That’s okay. You’re smart. Make.

There were a few things in the list at the top that I didn’t go into more detail about (Capistrano, Passenger, Factory Girl, and Shoulda). That’s because they’re ready to go; inclusion in the Gemfile was enough. Just start using ‘em.

Here’s a list of links to the documentation and articles I used to pull this together:

blog comments powered by Disqus