This release brings in some changes from Routes 1.8. The most noticeable change is that custom actions on RESTful routes are now delimited with the forward slash (/) instead of the semicolon (;). This was done for parity with Ruby on Rails.

I have also fixed some bugs, notably that the resource route generator failed to generate routes that recognized PUT and DELETE requests on “formatted” resources (/messages/1.xml). This fix will be merged upstream to the Python version.

I am also using the Python version and I met with Ben Bangert, the author of the Python version, at PyCon 2008. Each release of Horde/Routes has resulted in patches to the Python version. It’s nice how this small ecosystem has developed around the routes concept between these projects (Ruby on Rails, Pylons, and our work in Horde).

Since Horde/Routes 0.3, the default RESTful routes generated by Horde/Routes are fully compatible with the latest version of ActiveResource. We have a new project at work that is using Horde/Routes and ActiveResource together and it works well.

>>> import shlex
>>> shlex.split('foo "bar baz" qux')
['foo', 'bar baz', 'qux']

It’s useful for creating your own mini-languages or external DSLs that need to parse quoted strings like the one shown above.

We recently built an inventory tracking application in Ruby that has a user interface for selecting search filters. To expose the same search capabilities as a web service, we created a simple query language. I was looking for an shlex equivalent in Ruby.

It turns out that the Ruby Standard Library has a module called Shellwords:

>> require 'shellwords'
=> true
>> Shellwords::shellwords('foo "bar baz" qux')
=> ["foo", "bar baz", "qux"]

Shellwords is a little less capable than shlex but handles the most common use case just fine. It’s a convenient solution for a problem that comes up too often.

Update: Ruby 1.8.7 has added the shortcut methods Shellwords.split and String#shellsplit. Very nice.

I’m pleased to have been able to contribute a recipe to Mike Clark’s new book, Advanced Rails Recipes. The concept presented in my recipe, “Fail Early”, is that you can use initializers to prevent your application from starting up under certain conditions.

Rails applications typically run under persistent application server processes, like mongrel or thin. When a Rails application starts, it goes through a startup procedure that is performed only once. The startup includes reading the environment configuration files and running any initializers that have been set up. This can also be used as an opportunity to detect potentially dangerous situations and bail out.

“Fail Early” uses the case of pending migrations to demonstrate. If the application is started while there are pending migrations for the production database, the results can wreck production data. Instead, an initializer detects this condition and exits by calling Ruby’s Kernel.abort.

Here’s another case where this idea is useful. It’s well-known that the Ruby-based MySQL driver included with Rails isn’t suitable for use in production. In fact, Rails will produce this warning in the log if it is in use:

WARNING: You’re using the Ruby-based MySQL library that ships with Rails. This library is not suited for production. Please install the C-based MySQL library instead (gem install mysql).

This can go unnoticed in the log. Instead, we can write a short initializer that detects this condition and aborts the application start if the production server is misconfigured.

config/initializers/check_mysql_driver.rb:

if RAILS_ENV == 'production'
  config = ActiveRecord::Base.configurations['production']
  if config['adapter'] == 'mysql' 
    ActiveRecord::Base.require_mysql
    if Mysql::VERSION.to_s.include?('-ruby')
      abort "Ruby-based MySQL driver is not suitable for production"
    end
  end
end

When the initializer above is run in a production environment that has the Ruby-based MySQL driver instead of the C-based one, startup will be aborted.

$ mongrel_rails start -e production
** Starting Mongrel listening at 0.0.0.0:3000
** Starting Rails with production environment...
Ruby-based MySQL driver is not suitable for production
$

You can run many other safety checks like this at startup. Since they will be run only once and not per-request, your application incurs no performance penalty by doing so.

Rails for PHP Developers is a new website that’s a companion to the new book by the same name. Like the book, it’s aimed towards PHP developers who have an interest in Rails and Ruby. The website features articles that alternate between Ruby and PHP focus, so PHP developers that aren’t interested in Ruby should still find it useful.

I was pleased to learn today that I am a winner in the Rails Hackfest.

The Hackfest is a contest where your ranking is primarily determined by how many of your patches get accepted into Rails core during the contest month.

This makes is very useful one-time events, such as an item being added to a shopping cart:

flash[:success] = "#{cart.items.size} items added to your cart."

The flash[:success] will be available for the next request only.

However, Ajax requests will also clear the flash. This can lead to the sometimes mysterious problem of the flash contents disappearing before their intended request because an intermediate Ajax request caused them to be cleared.

The solution is to explicitly preserve the flash contents in actions that could unintentionally clear it. This is done using flash.keep:

flash.keep

The current contents of the flash will then be preserved for the next request. You can also pass a specific key such as flash.keep(:foo).

On one application I work on, we make Ajax requests periodically on a timer. Putting flash.keep in these Ajax actions was a simple way to make sure they didn’t unexpectedly gobble the flash contents.

Of course, once adding flash.keep, we also want to add a functional test for it. You might try doing this:

def test_something_keeps_flash
  @request.flash[:foo] = 'bar'
  xhr :get, :something
  assert_response :success
  assert_equal 'bar', @response.flash[:foo]
end

You’d be close but wrong. That would seem like a natural way to do it but unfortunately, the flash can’t be populated that way due to how TestRequest was built. It doesn’t have a flash attribute and the session doesn’t have a FlashHash. However, that won’t stop us from writing our test.

We could try monkeypatching but I try to avoid clever things like that. This problem is easily remedied with a helper in test_helper.rb:

def make_flash_hash(with_contents = {})
  returning ActionController::Flash::FlashHash.new do |flash_hash|
    flash_hash.update with_contents
  end
end

Our test case now can now use the simple make_flash_hash helper to populate the request’s session with flash:

def test_something_keeps_flash
  @request.session['flash'] = make_flash_hash(:foo => 'bar')
  xhr :get, :something
  assert_response :success
  assert_equal 'bar', @response.flash[:foo]
end

In addition to using @request.session as shown above, you could also populate the session in the xhr method directly. I like the former for readability.

Whichever way you choose to do it, writing the functional test will ensure that you’ll continue to preserve the flash when the application changes later.

The only problem with Autotest is that it is specific to Ruby. At work, I do a mix of different kinds of programming including Ruby, PHP, Python, and C. I’d like my TDD to be accelerated for all of these languages.

Thanks to Geoffrey Grossenbach, last week I came across stakeout.rb from Mike Clark. This is a tiny, dead simple Ruby script that runs an arbitrary command when certain files change. This is a stripped-down Autotest for everybody else. I’m sure it has all kinds of other uses as well.

To get started testing with stakeout.rb, you’ll need Ruby installed. Any recent version is fine and you might already have it installed. Next, grab the stakeout.rb script and add the shebang line to the top (Unix-like OS assumed):

#!/usr/bin/env ruby -w
 
if ARGV.size < 2
  puts "Usage: stakeout.rb <command> [files to watch]+"
...

Make the file executable and put it somewhere in your PATH. You can test it out by typing stakeout.rb from an arbitrary directory and you should see the help message.

Next, change over to a project directory where you have some test files. Most of the projects that I am involved with tend to use some directory structure similar to this:

/project_name
  /lib
  /test
  ...

To test such a project, run stakeout.rb from the /project_name directory. Most PHP projects using PHPUnit tend to have an AllTests.php file or equivalent to run all the tests, so we’ll assume this for the example:

project_name$ stakeout.rb "php test/AllTests.php" **/*

The first argument is what command to run when the tests change. The second argument, and any subsequent arguments, are the files to watch for changes. These can use a Ruby globbing pattern. The pattern **/* will watch all files under project_name recursively, which includes lib/ and test/.

Once stakeout.rb is run, it will show no output but will sit and wait for changes. As soon as you change a watched file, stakeout.rb will automatically rerun you tests and will continue to do so until you exit with Control-C.

The new site features updated information from Laurent and I, including a new guide. Over the coming weeks, we’ll continue to expand and improve its content.

Please let us know what you think about it!

Update: This post was featured on Laurent Sansonetti’s diary.

Sometimes you need to collect an attribute from every object in the specifier list. Normally, you’d do something like this:

names = OSA.app('iCal').calendars.collect { |c| c.name }

Symbol#to_proc fans use the convenient form:

names = OSA.app('iCal').calendars.collect(&:name)

Now, OSA::ObjectSpecifierList also has the #every method:

names = OSA.app('iCal').calendars.every(:name)

The difference is subtle but #every will fetch all of the attributes in a single Apple Event, something not possible when iterating over each item in the collection. For most purposes this is not important but it is a nice feature that could make a difference on larger collections.

This feature is currently in the RubyOSA trunk and will appear in the next stable release (coming soon).

Update: RubyOSA 4.0 has been released and includes this feature!

Autotest will DRY up your testing by running your tests automatically whenever your files change. In this article, we’ll explore Autotest:

• Installation
• Starting Autotest
• Stopping Autotest
• Autotest Plugins
• Coloring with RedGreen
• Notifications
• Next Steps

Installation

Autotest is a smart little program included in the ZenTest bundle of goodies. To install it, you’ll just need to install the gem for ZenTest.

gem install ZenTest

Depending on how your system is set up, you might need to run this as the root user or through sudo.

Starting Autotest

Running Autotest is as simple as running rake. First, change to the root directory of your Rails project. This is the directory that has Rakefile, app/, config/, etc. Next, run the autotest command:

$ autotest

Autotest will discover that it is running inside a Rails project and your tests will run just as they do with rake (or the wordier rake test).

After your tests run, Autotest will not exit back to the shell prompt. It will then sit and poll your files. When it notices files that change, it will run the tests for only the files that you’ve changed! It will do this continuously until you stop it.

Stopping Autotest

Pressing Control-C once will run your entire test suite again.

Pressing Control-C twice in quick succession will exit Autotest back to the shell prompt.

Autotest Plugins

Autotest includes a plugin mechanism that allows plugins to monitor different aspects of the testing lifecycle. Autotest includes a number of useful plugins out of the box.

In the next sections, we’ll see how to activate the plugins and what functionality they provide.

Coloring with RedGreen

One of the problems of testing under rake and autotest is that a lot of output can be generated and when looking at the results, you sometimes have to filter out the normal output to see the failures.

RedGreen is a simple Autotest plugin that solves this problem by coloring the summary lines of the test output either red or green to indicate whether the tests passed or failed:

Autotest automatically looks for a dotfile (.autotest) when it is started. This file may be in your Rails project directory or in your home directory where it will be used by all projects.

To install RedGreen or any other plugin, create the .autotest file with a simple require to load the plugin:

# .autotest
 
require 'autotest/redgreen'

That’s it! When you run autotest again, the plugin will be automatically loaded and your test output colored.

Notifications

Autotest also comes with the plugins growl, snarl, and kdenotify. Each are installed the same way as shown above, simply add the require line to your .autotest file. These allow Autotest to communicate each respective notification system.

Using one of these can be useful when running autotest in the background or in a minimized window. The screenshot above shows a Growl pop-up notification from Autotest under Mac OS X.

Note that for Autotest to send notifications to Growl, the growlnotify utility must be installed. This comes in the Extras/ directory of the Growl disk image.

Next Steps

Autotest isn’t limited to plugins shown here. There are a number of other useful plugins you can explore and more are added all the time. The plugins can be found in /path/to/your/gems/ZenTest-x.x.x/lib/autotest.

While Autotest can be an invaluable tool when testing Rails applications, it isn’t limited to Rails at all. Autotest can be used with an Ruby project that follows some simple conventions.

Visit the Autotest section of the ZenTest RDoc to learn about this, writing plugins, and more.

Update: This article was featured on Ryan Davis’ blog.