Tutorial
This is a detailed tutorial showing how to create an example Rails 3.1.1 application using Devise with RSpec and Cucumber.
- Devise gives you ready-made authentication and user management.
- RSpec is a popular alternative to the Test::Unit testing framework.
- Cucumber is used with RSpec for Behaviour Driven Development.
This tutorial also gives you the option of using Haml.
If you’d like to use the Mongoid ORM with the MongoDB datastore instead of ActiveRecord and a SQLite database, see the rails3-mongoid-devise example app and tutorial. Mongoid makes development quicker without schemas or migrations. The rails3-mongoid-devise example app and tutorial shows how to set up Devise and Mongoid with RSpec and Cucumber.
See a list of similar Rails examples, tutorials, and starter apps.
Follow the project on Twitter: rails_apps. Tweet some praise if you like what you’ve found.
Join the email list (low volume, announcements only) for project updates and my tips about Rails resources.
TutorialThis tutorial documents each step that you must follow to create this application. Every step is documented concisely, so a complete beginner can create this application without any additional knowledge. However, no explanation is offered for any of the steps, so if you are a beginner, you’re advised to look for an introduction to Rails elsewhere. See a list of recommended books and online resources for learning Rails.
If you follow this tutorial closely, you’ll have a working application that closely matches the example app in this GitHub repository. The example app is your reference implementation. If you find problems with the app you build from this tutorial, download the example app (in Git speak, clone it) and use a file compare tool to identify differences that may be causing errors. On a Mac, good file compare tools are FileMerge, DiffMerge, Kaleidoscope, or Ian Baird’s Changes.
If you clone and install the example app and find problems or wish to suggest improvements, please create a GitHub issue.
To improve this tutorial, please edit this wiki page.
Use the ready-made application template to generate the code.
You can use an application template to generate a new Rails app with code that closely matches the tutorial. You’ll find an application template for this tutorial in the Rails Application Templates repository.
Use the command:
$ rails new APP_NAME -m https://raw.github.com/RailsApps/rails3-application-templates/master/rails3-devise-rspec-cucumber-template.rb -T
Use the -T flag to skip Test::Unit files. Add the -J flag to skip Prototype files for Rails 3.0 (not needed for Rails 3.1).
This creates a new Rails app (with the APP_NAME you provide) on your computer. It includes everything in the example app. You can read through the tutorial with the code already on your computer.
You MUST be using Rails 3.0.4 or newer. Generating a Rails application from an “HTTPS” URL does not work in Rails 3.0.3 and earlier versions.
Use the rails_apps_composer gem to create a reusuable application template.
This is optimal if you are creating a “starter app” based on this example app but wish to customize the code for your own preferences.
Each step in this tutorial has a corresponding application template recipe from the Rails Apps Composer recipes repository. You can create your own application template using the template recipes. To do so, download the Rails Apps Composer project, customize recipes as needed, and follow the instructions to create a reusable application template file.
Follow this tutorial
To create the application, you can cut and paste the code from the tutorial into your own files. It’s a bit tedious and error-prone but you’ll have a good opportunity to examine the code closely. This is also more likely to teach you how to setup future applications with these features, as you’re actually typing out the example code.
Before beginning this tutorial, you need to install
- The Ruby language (version 1.9.2 or newer)
- Rails 3.1.1
Check that appropriate versions of Ruby and Rails are installed in your development environment:
$ ruby -v
$ rails -v
See Installing Rails 3.1 and Managing Rails Versions and Gems for detailed instructions and advice.
Open a terminal, navigate to a folder where you have rights to create files, and type:
$ rails new rails3-devise-rspec-cucumber -T
Use the -T flags to skip Test::Unit files (since you are using RSpec). Add the -J flag to skip Prototype files for Rails 3.0 (not needed for Rails 3.1).
You may give the app a different name if you are building it for your own use. For this tutorial, we’ll assume the name is “rails3-devise-rspec-cucumber.”
This will create a Rails application that uses a SQLite database for data storage.
After you create the application, switch to its folder to continue work directly in that application:
$ cd rails3-devise-rspec-cucumber
If you’re open sourcing the app on GitHub, please edit the README file to add a description of the app and your contact info. Changing the README is important if you’re using a clone of the example app. I’ve been mistaken (and contacted) as the author of apps that are copied from my example.
If you are creating an application template, this step uses the git recipe from the rails_apps_composer repository.
If you’re creating an app for deployment into production, you’ll want to set up a source control repository at this point. If you are building a throw-away app for your own education, you may skip this step.
$ git init .
$ git add .
$ git commit -m 'Initial commit'
See detailed instructions for Using Git with Rails.
The application uses the following gems:
See an example Rails 3.1.1 Gemfile.
See Managing Rails Versions and Gems for advice and details. It’s a good idea to create a new gemset using rvm, the Ruby Version Manager.
Install the required gems on your computer:
$ bundle install
You can check which gems are installed on your computer with:
$ gem list --local
Keep in mind that you have installed these gems locally. When you deploy the app to another server, the same gems (and versions) must be available.
If you are creating an application template, this step uses the jquery recipe from the rails_apps_composer repository.
Rails 3.1 uses jQuery by default so no additional effort is required. If you are using Rails 3.0, you can see instructions for Using jQuery with Rails 3.0.
If you are creating an application template, this step uses the haml recipe from the rails_apps_composer repository.
In this example, we’ll use the default “ERB” Rails template engine. Optionally, you can use another template engine, such as Haml. See instructions for adding Haml to Rails.
If you are creating an application template, this step uses the rspec recipe from the rails_apps_composer repository.
This tutorial shows how to set up RSpec and provides example specs for use with Devise. To learn more about using RSpec, refer to The RSpec Book.
Use the gem rspec-rails to set up the app for RSpec.
You should have the following gems in your Gemfile file:
gem 'rspec-rails', :group => [:development, :test] gem 'database_cleaner', :group => :test gem 'factory_girl_rails', :group => :test
The gem rspec-rails needs to be in the :development group (as well as the :test group) to expose generators and rake tasks during development.
Install the required gems on your computer:
$ bundle install
Use the rspec-rails generator to set up files needed for RSpec:
$ rails generate rspec:install
The rspec-rails generator creates the files:
- .rspec
- spec/spec_helper.rb
You can remove the test folder (it is not needed for RSpec):
$ rm -rf test/
The Factory Girl gem is used to create default model objects for tests. For example, if a controller action requires finding a User object before displaying a “show” page, Factory Girl will create a user just for a test of the controller. You’ll need gem 'factory_girl_rails', :group => :test in your Gemfile.
You’ll need a spec/factories.rb file to contain the factory definitions for any default objects used for testing. You can create one like this:
require 'factory_girl' Factory.define :user do |u| u.name 'Test User' u.email '[email protected]' u.password 'please' end
Using Devise, your controllers will often include before_filter :authenticate_user! to limit access to signed-in users. Your tests will fail unless a default user is created and logs in before each test runs. Devise provides test helpers to make it simple to create and log in a default user.
Create a file spec/support/devise.rb:
RSpec.configure do |config| config.include Devise::TestHelpers, :type => :controller end
Now you can write controller specs that set up a signed-in user before tests are run.
Run rake -T to check that rake tasks for RSpec are available.
Run rake db:migrate to create a db/schema.rb file so rake spec can run successfully.
You should be able to run rake spec to run all specs. If you haven’t written any specs, you’ll see the message “No examples matching ./spec//_spec.rb could be found”.
You can copy the files from the example spec directory to use our ready-made specs.
cd spec curl -o factories.rb https://raw.github.com/railsapps/rails3-devise-rspec-cucumber/master/spec/factories.rb mkdir controllers cd controllers curl -o home_controller_spec.rb https://raw.github.com/railsapps/rails3-devise-rspec-cucumber/master/spec/controllers/home_controller_spec.rb curl -o users_controller_spec.rb https://raw.github.com/railsapps/rails3-devise-rspec-cucumber/master/spec/controllers/users_controller_spec.rb cd ../ mkdir models cd models curl -o user_spec.rb https://raw.github.com/railsapps/rails3-devise-rspec-cucumber/master/spec/models/user_spec.rb
You’ll have to complete the tutorial before the specs will run successfully.
If you are creating an application template, this step uses the cucumber recipe from the rails_apps_composer repository.
It’s not necessary to add Cucumber (the example will run without it). However, it’s a recommended practice to specify use cases (“user stories”) as Cucumber scenarios. It’s a good way to plan development and, using Cucumber, you’ll have specifications for automated acceptance testing.
This tutorial shows how to set up Cucumber with Devise.
Use the gem cucumber-rails to set up the app for Cucumber.
You should have the following gems in your Gemfile file:
group :test do gem 'cucumber-rails' gem 'capybara' gem 'database_cleaner' end
Install the required gems on your computer:
$ bundle install
Use the cucumber-rails generator to set up files needed for Cucumber:
$ rails generate cucumber:install --capybara --rspec
The -–capybara option specifies Capybara instead of the default Webrat for acceptance testing. The -–rspec option enables RSpec matchers for your step definitions.
To reset your application database to a pristine state during testing, Cucumber makes use of Database Cleaner. The file features/support/env.rb is already set up to use Database Cleaner:
begin DatabaseCleaner.strategy = :transaction rescue NameError raise "You need to add database_cleaner to your Gemfile (in the :test group) if you wish to use it." end
Run rake -T to check that rake tasks for Cucumber are available.
You should be able to run rake cucumber (or more simply, cucumber) to run all Cucumber scenarios and steps. If you haven’t written any Cucumber scenarios and steps, you’ll see the message “0 scenarios, 0 steps”.
To learn more about using Cucumber, refer to The Cucumber Book or the free introduction to Cucumber, The Secret Ninja Cucumber Scrolls.
There are two approaches to writing Cucumber scenarios. The newest (and recommended) approach uses Capybara to write the code (“steps”) that turn Cucumber scenarios into executable specifications. Older versions of Cucumber provided a web_steps.rb file that implemented common features. See the The Training Wheels Came Off by Aslak Hellesøy to understand why the web_steps.rb approach is no longer recommended.
You can check that your app runs properly by entering the command
$ rails server
To see your application in action, open a browser window and navigate to http://localhost:3000/. You should see the Rails default information page.
Stop the server with Control-C.
If you are creating an application template, this step uses the action_mailer recipe from the rails_apps_composer repository.
In its default configuration, Devise sends email messages to confirm new users and reset passwords. You’ll want to configure ActionMailer to show errors during development and suppress failures when the app is deployed to production.
Set up action_mailer in your development environment in the file
config/environments/development.rb
by commenting out the line in the file:
# Don't care if the mailer can't send # config.action_mailer.raise_delivery_errors = false
and adding:
# ActionMailer Config
config.action_mailer.default_url_options = { :host => 'localhost:3000' }
# A dummy setup for development - no deliveries, but logged
config.action_mailer.delivery_method = :smtp
config.action_mailer.perform_deliveries = false
config.action_mailer.raise_delivery_errors = true
config.action_mailer.default :charset => "utf-8"
Set up action_mailer in your production environment in the file
config/environments/production.rb
by adding:
config.action_mailer.default_url_options = { :host => 'yourhost.com' }
# ActionMailer Config
# Setup for production - deliveries, no errors raised
config.action_mailer.delivery_method = :smtp
config.action_mailer.perform_deliveries = true
config.action_mailer.raise_delivery_errors = false
config.action_mailer.default :charset => "utf-8"
If you are creating an application template, this step uses the devise recipe from the rails_apps_composer repository.
You should add the following gem to your Gemfile file:
gem 'devise'
and run
$ bundle install
This app uses Devise for user management and authentication. Devise is at http://github.com/plataformatec/devise.
We’ve already installed the Devise gem with the $ bundle install command. Run the generator:
$ rails generate devise:install
which installs a configuration file:
config/initializers/devise.rb
and a localization file.
Devise can manage users and administrators separately, allowing two (or more) roles to be implemented differently. For this example, we just implement Users.
Use Devise to generate models and routes for a User:
$ rails generate devise User
Devise will modify the config/routes.rb file to add:
devise_for :users
which provides a complete set of routes for user signup and login. If you run rake routes you can see the routes that this line of code creates.
By default, Devise uses an http DELETE request for sign out requests (destroy_user_session_path). Rails uses Javascript to implement http DELETE requests. Prior to Devise 1.4.1 (27 June 2011), Devise used an http GET request for sign out requests. Jose Valim explained the change: “GET requests should not change the state of the server. When sign out is a GET request, CSRF can be used to sign you out automatically and things that preload links can eventually sign you out by mistake as well.”
However, Cucumber wants to test GET requests not DELETE requests. If you intend to use Cucumber with Devise, you must change the Devise default from DELETE to GET in /config/initializers/devise.rb for the Rails test environment. You may see a suggestion elsewhere to tweak the routes.rb file or change the log_out link to make the fix. It isn’t necessary if you change the /config/initializers/devise.rb file.
# The default HTTP method used to sign out a resource. Default is :delete. config.sign_out_via = Rails.env.test? ? :get : :delete
Since you only use Cucumber during testing, switching the default is only needed for testing.
If you’re not going to use Cucumber, leave Devise’s new default (DELETE) in place.
We don’t want passwords written to our log file. In Rails 2, we would change the file
app/controllers/application_controller.rb
to include:
filter_parameter_logging :password, :password_confirmation
In Rails 3, this is deprecated and instead we modify the file config/application.rb to include:
config.filter_parameters += [:password, :password_confirmation]
Note that filter_parameters is an array.
If you are creating an application template, this step uses the add_user recipe from the rails_apps_composer repository.
By default, Devise uses an email address to identify users. We’ll add a “name” attribute as well. Your application may not require a user to provide a name. But showing you how to add a name will help you see what you need to do if you decide to make changes to the default Devise user model.
Devise created a migration file to establish the schema for the SQLite database with a migration file named something like db/migrate/xxxxxxx_devise_create_users.rb. We won’t modify the migration file. Instead we’ll add an additional migration that adds the “name” field to the User record.
rails generate migration AddNameToUsers name:string
Run rake db:migrate again to pick up the “name” field.
$ rake db:migrate
Next, we’ll modify the user model to validate the presence and uniqueness of the “name” attribute. Modify the file app/models/user.rb and add:
validates_presence_of :name validates_uniqueness_of :name, :email, :case_sensitive => false
This will allow users to be created (or edited) with a name attribute. When a user is created, a name and email address must be present and must be unique (not used before). Note that Devise (by default) will check that the email address and password are not blank.
You’ll also want to prevent malicious hackers from creating fake web forms that would allow changing of passwords through the mass-assignment operations of update_attributes(attrs) and new(attrs). Devise already added this to the models/user.rb file:
attr_accessible :email, :password, :password_confirmation, :remember_me
but you’ll need to add the “name” attribute:
attr_accessible :name, :email, :password, :password_confirmation, :remember_me
Devise provides a controller and views for registering users. It is called the “registerable” module. The controller and views are hidden in the Devise gem so we don’t need to create anything. However, because we want our users to provide a name when registering, we will create custom views for creating and editing a user. Our custom views will override the Devise gem defaults.
First, to copy all the default Devise views to your application, run
rails generate devise:views
This will generate a set of views in the directory app/views/devise/.
Next, modify the views to create and edit users.
Add the following code to each file:
app/views/devise/registrations/edit.html.erb
<p><%= f.label :name %><br /> <%= f.text_field :name %></p>
app/views/devise/registrations/new.html.erb
<p><%= f.label :name %><br /> <%= f.text_field :name %></p>
We do not need to add a controller with methods to create a new user or edit or delete a user. We use the existing “registerable” module from Devise which provides a controller with methods to create, edit or delete a user.
Note that Devise’s default behaviour allows any logged-in user to edit or delete his or her own record (but no one else’s). When you access the edit page you are editing just your info, and not info of other users.
If you are using Haml, Devise does not generate views for Haml (it did before February 15, 2011; see Devise issue 878).
You can create the files:
app/views/devise/registrations/edit.html.haml
%h2
Edit #{resource_name.to_s.humanize}
= form_for(resource, :as => resource_name, :url => registration_path(resource_name), :html => { :method => :put }) do |f|
= devise_error_messages!
%p
= f.label :name
%br/
= f.text_field :name
%p
= f.label :email
%br/
= f.email_field :email
%p
= f.label :password
%i (leave blank if you don't want to change it)
%br/
= f.password_field :password
%p
= f.label :password_confirmation
%br/
= f.password_field :password_confirmation
%p
= f.label :current_password
%i (we need your current password to confirm your changes)
%br/
= f.password_field :current_password
%p= f.submit "Update"
%h3 Cancel my account
%p
Unhappy? #{link_to "Cancel my account", registration_path(resource_name), :confirm => "Are you sure?", :method => :delete}.
= link_to "Back", :back
app/views/devise/registrations/new.html.haml
%h2 Sign up
= form_for(resource, :as => resource_name, :url => registration_path(resource_name)) do |f|
= devise_error_messages!
%p
= f.label :name
%br/
= f.text_field :name
%p
= f.label :email
%br/
= f.email_field :email
%p
= f.label :password
%br/
= f.password_field :password
%p
= f.label :password_confirmation
%br/
= f.password_field :password_confirmation
%p= f.submit "Sign up"
= render :partial => "devise/shared/links"
If you are creating an application template, this step uses the home_page recipe from the rails_apps_composer repository.
Delete the default home page from your application:
$ rm public/index.html
Create the first page of the application. Use the Rails generate command to create a “home” controller and a “views/home/index” page.
$ rails generate controller home index
If you’re using the default template engine, you’ll find an erb file with placeholder content:
app/views/home/index.html.erb
If you’re using Haml, you’ll find a haml file with placeholder content:
app/views/home/index.html.haml
We’ll assume you’re using the default template engine for the remainder of this tutorial.
Now, you have to set a route to your home page. Edit the file config/routes.rb and replace:
get "home/index"
with
root :to => "home#index"
We’ll add some content to the home page in the next step.
You can check that your app runs properly by entering the command
$ rails server
To see your application in action, open a browser window and navigate to http://localhost:3000/. You should see your new home page.
Stop the server with Control-C.
If you are creating an application template, this step uses the home_page_users recipe from the rails_apps_composer repository.
Modify the file app/controllers/home_controller.rb and add:
def index @users = User.all end
Modify the file app/views/home/index.html.erb and add:
<h3>Home</h3> <% @users.each do |user| %> <p>User: <%= user.name %> </p> <% end %>
If you are creating an application template, this step uses the seed_database recipe from the rails_apps_composer repository.
You’ll want to set up a default user so you can test the app. Modify the file db/seeds.rb by adding:
puts 'SETTING UP DEFAULT USER LOGIN' user = User.create! :name => 'First User', :email => '[email protected]', :password => 'please', :password_confirmation => 'please' puts 'New user created: ' << user.name
You can change the values for name, email, and password as you wish.
Add the default user to the database by running the command:
$ rake db:seed
If you need to, you can run $ rake db:reset to drop and then recreate the database using your seeds.rb file.
If the task fails with “Validation failed: Name can’t be blank” you should check that the file models/user.rb allows the “name” attribute to be mass updated:
attr_accessible :name, :email, :password, :password_confirmation, :remember_me
At this point, you may want to know if the default user has been saved to the database.
You can check that your app runs properly by entering the command
$ rails server
To see your application in action, open a browser window and navigate to http://localhost:3000/. You should see your new home page.
Stop the server with Control-C.
You’ll want to see how Devise manages authentication.
If you are creating an application template, this step uses the users_page recipe from the rails_apps_composer repository.
Use the Rails generate command to create a “users” controller and a “views/user/show” page.
$ rails generate controller users show
Note that “users” is plural when you create the controller.
Modify the file app/controllers/users_controller.rb and add:
before_filter :authenticate_user! def show @user = User.find(params[:id]) end
The file config/routes.rb has already been modified to include:
get "users/show"
Remove that and change the routes to:
root :to => "home#index" devise_for :users resources :users, :only => :show
Important note: The devise_for :users route must be placed above resources :users, :only => :show.
Modify the file app/views/users/show.html.erb and add:
<p>User: <%= @user.name %></p>
You’ve already modified the file app/controllers/home_controller.rb to include this:
def index @users = User.all end
Now modify the file app/views/home/index.html.erb to look like this:
<h3>Home</h3> <% @users.each do |user| %> <p>User: <%=link_to user.name, user %></p> <% end %>
If you are creating an application template, this step uses the css_setup recipe from the rails_apps_composer repository.
We’ll create a very simple stylesheet with styling for a horizontal menu and flash messages:
For Rails 3.0, you’ll need to create a public/stylesheets/application.css file.
For Rails 3.1, you’ll find a app/assets/stylesheets/application.css file.
You can add this to the application.css file:
ul.hmenu {
list-style: none;
margin: 0 0 2em;
padding: 0;
}
ul.hmenu li {
display: inline;
}
#flash_notice, #flash_alert {
padding: 5px 8px;
margin: 10px 0;
}
#flash_notice {
background-color: #CFC;
border: solid 1px #6C6;
}
#flash_alert {
background-color: #FCC;
border: solid 1px #C66;
}
If you are creating an application template, this step uses the application_layout recipe from the rails_apps_composer repository.
Rails will use the layout defined in the file app/views/layouts/application.html.erb or app/views/layouts/application.html.haml as a default for rendering any page.
You’ll want to include flash messages for errors and notifications. Set up your application layout by modifying the default as described in the instructions for the Rails default application layout.
If you are creating an application template, this step uses the navigation recipe from the rails_apps_composer repository.
You will want to add navigation links to the application layout for the Devise sign-up and log-in actions. You’ll find a simple example on the Devise wiki.
Create a shared directory under app/views/. Then create the file app/views/shared/_navigation.html.erb and add:
<% if user_signed_in? %>
<li>
<%= link_to('Logout', destroy_user_session_path, :method=>'delete') %>
</li>
<% else %>
<li>
<%= link_to('Login', new_user_session_path) %>
</li>
<% end %>
<% if user_signed_in? %>
<li>
<%= link_to('Edit account', edit_user_registration_path) %>
</li>
<% else %>
<li>
<%= link_to('Sign up', new_user_registration_path) %>
</li>
<% end %>
Then use these partials in your app/views/layouts/application.html.erb file, like this:
<body>
<ul class="hmenu">
<%= render 'shared/navigation' %>
</ul>
<%- flash.each do |name, msg| -%>
<%= content_tag :div, msg, :id => "flash_#{name}" if msg.is_a?(String) %>
<%- end -%>
<%= yield %>
For Haml, modify app/views/layouts/application.html.haml like this:
%body
%ul.hmenu
= render 'shared/navigation'
- flash.each do |name, msg|
= content_tag :div, msg, :id => "flash_#{name}" if msg.is_a?(String)
= yield
Several unneeded files are generated in the process of creating a new Rails application.
Additionally, you may want to prevent search engines from indexing your website if you’ve deployed it publicly while still in development.
See instructions for cleaning up unneeded files in Rails and banning spiders.
If you are creating an application template, this step uses the cleanup recipe from the rails_apps_composer repository.
If you are creating an application template, this step uses the ban_spiders recipe from the rails_apps_composer repository.
You can check that your app runs properly by entering the command
$ rails server
To see your application in action, open a browser window and navigate to http://localhost:3000/. You should see the default user listed on the home page. When you click on the user’s name, you should be required to log in before seeing the user’s detail page.
Stop the server with Control-C.
For your convenience, here are instructions for deploying your app to Heroku. Heroku provides low cost, easily configured Rails application hosting.
This concludes the tutorial for creating a Ruby on Rails web application that requires Rails 3 and uses Devise for user management and authentication with RSpec and Cucumber.
Daniel Kehoe (http://danielkehoe.com/) implemented the application and wrote the tutorial.
Was this useful to you? Follow me on Twitter:
rails_apps
and tweet some praise. I’d love to know you were helped out by the tutorial.
Any issues? Please create an Issue on GitHub.