Learning to Use RSpec

February 25, 2008

Most of the “Intro to Rails” books show how to develop web apps by writing code and then tests. (The more sophisticated books advise to write the tests and then write the code.) The books give good examples of using the built-in Test::Unit facility. But many experienced Rails developers are now using RSpec. There’s only one book I’ve seen that covers RSpec and that’s Obie Fernandez’s The Rails Way. The book doesn’t really explain why so many developers are moving to RSpec; for that, see an article by Dan North or an article by Dave Astels. They argue that we should be writing specifications, not tests.

There are a few tutorials that introduce RSpec, notably a series on the O’Reilly Network on Behavior Driven Development Using Ruby, with Part 1, Part 2, and Part 3. There are also four Peepcode screencasts, starting with RSpec Basics.

RSpec is in the midst of rapid development and there are enough differences between RSpec version 1.1.0, which introduced new functionality (“user stories’), and earlier versions which are covered in the tutorials, that it is possible to get confused.

With so much rapid development of RSpec, the best place to get guidance is the Rspec Users mailing list.

Just a note, you might want to install the Textmate bundle for RSpec.


TextMate and Rails 2.0

February 24, 2008

I’m using TextMate on Mac OS X version 10.5 to develop Rails apps. Rails 2.0 has a new naming convention for views (the “.rhtml” file extension becomes “.html.erb”). TextMate’s syntax coloring doesn’t recognize the new file extension. What to do? A few people have suggested tweaks using TextMate’s Bundle Editor (here and here). A better option is the new TextMate Rails 2.0 bundle now under development by Dr Nic Williams. Right now, it’s only available for download using git but maybe by the time you read this it will have moved to the official Textmate svn repository. Check the Ruby on Rails: TextMate Google Group for more information.


Rails Tutorial Showing RESTful Authentication

February 22, 2008

This tutorial, Restful Authentication with all the bells and whistles, uses Rails 2.0.2 and accommodates user account activation, changing passwords, forgotten passwords, enabling/disabling users, roles and OpenID.

It has advantages over the Caboose Sample rails application because it is accompanied by extensive community discussion, which serves as documentation. It is also more full-featured and up-to-date.

It’s missing any testing (no Test::Unit or rspec). Otherwise, it could be a good starting point for a Rails example app.

UPDATE: Rails has advanced since this discussion was relevant. As of February 2010, Rails is currently at version 2.3.5 (and Rails 3 is in beta). Several Rails gems are now available that provide a turnkey authentication solution, including Authlogic, Devise, and Clearance. You can also look at Technoweenie’s restful-authentication generator. The Ruby Toolbox page for Rails Authentication shows which are most popular. I personally recommend Devise and the Devise Example Application.


How to Tell if a Rails Example is Up-to-Date

February 19, 2008

Do you check the “sell-by” date on a carton of milk before you buy it? Unfortunately, there is no date on a Rails app to indicate if it has been written with recent best practices in mind. So check for a sour smell. Here are some indicators I look for.

First, is it RESTful? More than anything else, a RESTful architecture makes an app easier to understand, customize, and maintain. To determine if the developer used a RESTful architecture, look at the code for the controllers. If there are any methods other than index, show, new, create, edit, update, and destroy the developer has strayed from RESTful purity.

Second, has the app been written or updated for use with Rails 2.0? If you’re beginning a project, you’ll want to start with Rails 2.0. Some things are done a little differently in Rails 2.0. If you’re using an example app as a guide, make sure it’s a good example of how to do things with Rails 2.0.

To determine if the developer wrote for Rails 2.0:

In the config/environment.rb file, look for
RAILS_GEM_VERSION = '2.0.2'

Look for the folder config/initializers. Before Rails 2.0, the config/environment.rb file was cluttered with bits of initialization code. With Rails 2.0, we are encouraged to move initialization code to separate files in the config/initializers folder.

Take a look at the files in the Views folder. With Rails 2.0, the recommended practice is to use the file extension .html.rb. You don’t have to do that, but it is now recommended.

Finally, here is a script that will check a rails app to determine if it is compatible with Rails 2.0:

http://pastie.caboo.se/99900.txt?key=krcevozww61drdeza13e3a


Survey of Rails Example Applications

February 18, 2008

UPDATE FOR RAILS 3.0: After seeing what was available, I began developing my own Rails example apps. They’ve become quite popular, judging from the number of Rails developers visiting the GitHub repo. Each is accompanied by a detailed tutorial and an application template that can be used to generate a starter app. You can find them here.

THE ORIGINAL POST (from February 18, 2008):

I’m a firm believer that, as software developers, we always are standing on the toes of those who have gone before us.

So, in that spirit, I’m looking around for Rails example apps that I can use as a starting point for my own.

Many Rails books introduce Rails development through the process of building an example application. The best-documented Rails example apps are the ones in the books. I’ve looked through the books I have at hand. Most of the apps in the books are overly simple (for example, no authentication) or dated (no RESTful architecture).

I looked closely at RailsSpace. The authors Michael Hartl and Aurelius Prochazka fully document the steps to building a typical social networking web site. It is a full-featured app that is more complete than most tutorial applications. Unfortunately, the book was written before RESTful architectures became de rigueur. Only one part of the app is RESTful. Otherwise it might be suitable. UPDATE: Michael Hartl, one of the authors of RailsSpace, is leading development of an open source social network app, named Insoshi, which improves on RailsSpace.

I also looked at RailsCoders, the example app from the book Practical Rails Social Networking Sites, published by Apress. It’s a full-featured app and it is RESTful. The author chose to implement his own authentication (using RESTful principles); I would prefer to use the restful_authentication plugin. The app was written for Rails 1.2.3, not Rails 2.0, but an upgrade is relatively easy.

How about open source projects? I looked at a few.

I’ve used the Caboose Sample rails application on other projects, so that’s a potential starting point. The downside? It’s complex and not well documented. (The authors warn, “much of the code is targeted at an intermediate/advanced level”.)

A promising beginning point appears to be the Altered Beast forums application, a newer version of Beast. It’s RESTful. It uses Rails 2.0, rspec, and restful_authentication (with the acts_as_state_machine option). I also liked LovdbyLess, a free open source social network platform. It uses Rails 2.0 but not rspec or restful_authentication.

I posted here to ask for more recommendations.

UPDATE: I found an interesting example app named Jumpstart from the people at Relevance Inc. There’s also kickstart-rails from Mislav Marohnić. And I found RailsStarterApp from David Andrew Thompson and Six Hour Startup.

UPDATE: There’s a new site (announced here) that provides a gallery of open source rails applications. Great idea! And a good place to look for apps that can be studied, adapted, or improved.

UPDATE: I’ve released my own Rails RESTful Authentication Example Application.


Setting Up a Mac User Account for Building Web Apps

February 17, 2008

When I start a new project, I like a fresh and uncluttered workspace, so I created a new user account on my Mac. I needed development tools, so I added Firefox, Locomotive, iTerm, TextMate, and Navicat to the application dock.

Firefox needs a few extras to be useful for web development, so I added the HTML Validator extension (so I can check if my HTML pages conform to standards), the del.icio.us bookmarks extension (so I can get to my haphazardly organized collection of important reference web pages), and the Firebug extension (which is the only practical way I’ve found to figure out what’s going on with any complicated web page).

iTerm needed my favorite easy-on-the-eyes font, so I installed Inconsolata 14.

All that took about an hour.


Setting Up Mac OS X 10.5 (Leopard) for Rails Development

February 17, 2008

Here are directions for setting up Mac OS X 10.5 (Leopard) for developing a Rails web application. This covers everything you need to set up a Macintosh from scratch for Rails development. These instructions are suitable for a developer working offsite or independently (if you’re in an office with a support staff you probably don’t need this!).

These instructions make a number of assumptions about your development environment and requirements. This is what I used in a recent typical project.

  1. If the Mac has been used before, and there’s reason to save what’s already on the machine, back up all the user folders you want to keep to an external drive.
  2. You’ll need the disks that came with the Mac or disks from a Mac OS X 10.5 upgrade package. Do an “Erase and Install” to perform a clean install of Mac OS 10.5 (Leopard).
    1. Once the Macintosh HD is selected, click “Options.”
    2. Select “Erase and Install.”
    3. For “Format disk as” select the default “Mac OS Extended (Journaled).”
    4. Click “OK” and complete the Mac OS X installation.
  3. Create a new account with the name “Computer Administrator” (or something suitable for an account you will only use for system administration) and the short name “admin.”
  4. Create any user accounts you’ll need for yourself or anyone else using the machine.
  5. From the admin account, install the applications you’ll need for development. Here’s what I use:
    1. TextMate – http://macromates.com/
    2. iTerminal – http://iterm.sourceforge.net/
    3. Navicat – http://www.navicat.com/
    4. Firefox – http://www.mozilla.com/en-US/firefox/
    5. Firebug – https://addons.mozilla.org/en-US/firefox/addon/1843
  6. I like to use Locomotive as a graphical interface to manage my Rails projects. Before Mac OS X 10.5 (Leopard) was released, Locomotive offered an easy way to install a Rails stack on a Mac. Now it’s no longer needed to run Rails but it is still useful as an interface to start and stop an app, open iTerminal or TextMate, and preview an app in a web browser. You might want to try it, though it is not needed. If you are using Locomotive, go to to the Locomotive web site and download and install the “/usr/local” Rails bundle.
  7. Our team uses Skype and Pyro for interteam communication.
    1. Pyro – http://www.karppinen.fi/pyro/
    2. Skype – http://www.skype.com/
  8. From the admin account, install the developer XCode Tools package:
    1. Double click the XcodeTools.mpkg package.
    2. On the “Standard install on ‘Mac HD'” screen, select “Customize”.
    3. Check “Mac OS X 10.3.9 Support”.
    4. Click “Install”.
  9. If you’ll be working with uploaded images (probably with attachment_fu), you’ll need to compile and install FreeImage at a later point in the process, in which case you’ll need some header files from an older version of Mac OS X. From the admin account, after installing the XCode Developer package, install the MacOSX10.3.9 developer tools package (this provides the old header files that you’ll need for compiling FreeImage later): Double click the MacOSX10.3.9.pkg file in the packages folder.
  10. Install the X Window System (X11) from the Leopard install disk when you install the XCode developer package:
    1. Install X11Documentation.pkg.
    2. Install X11SDK.pkg.
  11. You’ll need MacPorts to later install FreeImage and Git. Install MacPorts 1.5 to “/opt/local” using the package from macports.org:
    http://www.macports.org/install.php
  12. Set the “/etc/bashrc” and “/etc/profile” files for the admin user and everyone else.
    1. Set aliases in “/etc/bashrc”
    2. Set the PATH in “/etc/profile”
  13. Modify the PATH environment variable in the “/etc/profile” file to add a path to “/opt/local” for Macports.
  14. Modify the PATH environment variable in the “/etc/profile” file to add a path to “/usr/local/mysql/bin” for MySQL (which you’ll add next).
  15. Compile and install MySQL 5.0.45 using the shell script at hivelogic.com: http://hivelogic.com/articles/installing-mysql-on-mac-os-x/
  16. Check your MySQL version.
    1. In iTerminal, type “mysql –version”.
    2. You should see “mysql Ver 14.12 Distrib 5.0.45, for
      apple-darwin9.1.0 (i686)”.
  17. You may be using Subversion for revision control or you may need to download open source code that is only available via Subversion. Open iTerminal and make sure you have access to Subversion (“which svn”).

    1. In iTerminal, type “svn –version”
    2. You should see “svn, version 1.4.4 (r25188)” (or something similar).
  18. You may be using Git for revision control or you may need to download open source code that is only available via Git. Git does not come with Mac OS X 10.5 (Leopard) so you’ll need to install it using MacPorts: “sudo port install git-core”.
  19. Check your Ruby version.
    1. In iTerminal, type “ruby –version”.
    2. You should see “ruby 1.8.6 (2007-09-24 patchlevel 111)
      [universal-darwin9.0]”.
  20. See which Ruby gems are installed with “gem list –local”. If you know which gems you’ll need for your application, you can install them now.
  21. Update to the current version of Rails.
    1. In iTerminal, “sudo gem update rails”.
    2. In iTerminal, “rails –version” should display
      “Rails 2.0.2”.
  22. If you’ll be working with attachment_fu and uploaded images, install Freeimage and Imagescience.
    1. Install Freeimage with “sudo port install freeimage”.
    2. If you receive any errors, check the install of XCode Tools.
    3. This discussion may be helpful: http://www.ruby-forum.com/topic/129554
    4. Install Imagescience with “sudo gem install -y image_science”.
  23. Log in to your user account and add your applications to the dock for easy access. This is a good time to look in System Preferences and set System/Accounts “Login Items” for applications such as Mail that you want to launch as soon as you log in.
  24. Get Mail set up properly for your user account.
  25. In your user account, set up the web browsers Firefox and Safari (and any others you’ll use) in the dock. You may want to set the Firefox home page to “http://localhost:3000/” so you’ll see your local development version of the your app when you launch Firefox. It’s a good idea to develop in Firefox so you’ll be developing to a standards-based browser. You may want to set the Safari home page to your production web site so you can see your app after it is deployed with a non-Firefox browser. Even better, set up Microsoft Internet Explorer running under VMWare Fusion so you check the app for browser compatibility issues.
  26. Set up Navicat to connect to your MySQL databases.
    1. Connect to your development database on “localhost.”
    2. You may also use Navicat to connect to your staging or production databases on your hosting server. But unless you have the authority and can take responsibility for the consequences, be cautious about modifying data on the production database!
  27. In your user account, create a folder for your Rails projects.
  28. Open iTerminal, change directories to your Rails projects folder, and create a new Rails application. Or find an existing open source application at GitHub and do a “git clone” for an application you want to modify.
  29. Build your Rails app.