Hieraki recent changes

rabble: Blogs

There are many places you can get more information about testing rails.

rabble: Blogs

There are many places you can get more information about testing rails.

Sascha Ebach: Translating Rails Apps

Using Gettext To Translate Your Rails Application

The version of this document is optimized for Ruby-GetText 1.9.0 and Rails 1.2.

Introduction

Stand on the shoulders of Giants

Gettext is a great tool for translating user interfaces of applications into different languages. It has been around for a long time and is very well established for this task. Gettext helps you to open up your application to a much wider user base than you would normaly reach in only one language. Since it is used in many open source projects it has a lot of useful tools you can use to your own advantage. It would be possible to “roll your own” solution, but this would consume a large amount of time. Time you would lose for the development of your app. And this is not something you would want, right?

So in this tutorial I am going to show you how to effectively use Gettext for all your translation needs in your Ruby on Rails application.

What can Gettext do for you?

Here is a quick explanation of Gettext for those of you who haven’t worked with it, yet. Gettext is a set of tools that provide help when translating strings in your software. It gives you (straight from the gettext manual):

A set of conventions about how programs should be written to support message catalogs.
A directory and file naming organization for the message catalogs themselves.
A runtime library supporting the retrieval of translated messages.
A few stand-alone programs to massage in various ways the sets of translatable strings, or already translated strings.

The only thing you have to do to your program sources is wrap all translatable strings with a method call: gettext(text) or shorter _(text). Example:

Without gettext:

notice = 'Thank you for buying our product.'

With gettext:

notice = _('Thank you for buying our product.')

If you have wrapped everything between the method call Gettext will provide you with the tools to extract these messages (called a harvester) from your source code and save the results to a portable file format. A runtime library will allow you to display a translated message whenever _() is called. In essence this is what Gettext does. It can do a couple of more things (like update / merge message catalogs, handling plurals, ...) but essentially it tries to make it as easy and as unobtrusive as possible to translate the language strings in your source code and then get out of your way.

Preperation is everything—use UTF-8 everywhere

Edit your files with UTF-8 only

The W3C has an awesome page with all you need to know about character sets (choosing, declaring, serving, editing, ...) and other important stuff concerning internationalization on their site called W3C I18N Topic Index. There you will find a lot of good help and suggestions on everything you need to know about general internationalization topics. You really want to spend at least a couple of hours reading through the resources they offer or link to.

If you happen to use VIM like I do you can put these two lines in your .vimrc and it will from then on treat your files as UTF-8 and convert everything to UTF-8 whenever you save a file:

set encoding=utf8
set fileencoding=utf8

If your editor of choice doesn’t provide support for UTF-8 it is probably time to get a new one ;)

Feed your database with UTF-8

If I need a database I usually go for MySQL. At least most of the time. Since version 4.1.x MySQL has very good support for different character sets. Please read the extensive MySQL Character Set Support article. It will give you a very good idea about the kind of support MySQL has to offer.

Here is a table definition I use in a current project:

CREATE TABLE `pages` (
 `id` int(10) unsigned NOT NULL auto_increment,
 `title` varchar(255) default NULL,
 `keywords` varchar(255) default NULL,
 `description` varchar(255) default NULL,
 `block1` text,
 `block2` text,
 `block3` text,
 `block4` text,
 `block5` text,
 `lang` varchar(10) NOT NULL default 'en_EN',
 `category` varchar(255) default NULL,
 `path` varchar(255) default '/',
 `updated_at` datetime default NULL,
 `created_at` datetime default NULL,
 `published_at` datetime default NULL,
 `layout` varchar(255) default 'main.rhtml',
 `template` varchar(255) default NULL,
 `access` tinyint(3) unsigned default '3',
 `version` int(10) unsigned default '1',
 `is_published` tinyint(3) unsigned default '0',
 PRIMARY KEY  (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 ROW_FORMAT=DYNAMIC;

There is nothing really special about it except the DEFAULT CHARSET=utf8 in the last line. It will make MySQL use UTF-8 for every field that holds text like varchar and text.

Add the following line to your database.yml to connect with UTF-8.

encoding: UTF8

If you use another maybe more mature and feature rich database like PostgreSQL UTF-8 support should also be available. Just make sure you configure everything upfront, because it might save you time later on.

If you still think you are going to tack on support for UTF-8 later you might reconsider after reading David’s and Jamis’ experiences: Forty-four grueling hours (or Welcome to 37s!) by David Heinemeier Hansson and On the job by Jamis Buck.

If for any reason you need to use anything other than UTF-8 you might want to know that you can use the Iconv module to convert between different character sets. This module should be installed by default on most distributions. If it is not it is usually easy to get. Just be sure to get it if you need charcter set conversion. On Debian you might need a apt-get install libiconv-ruby to get started. Here is a little example stolen from Pickaxe 2 page 686:

Example: Convert olé from UTF-8 to ISO-8859-1

$ irb -riconv
>> Iconv.conv('ISO-8859-1', 'UTF-8', "ol\303\251")
=> "ol\351"

Installing Ruby-GetText

After everything in your setup will accept UTF-8 we can go ahead and install Gettext support in Ruby. We will use the Ruby-GetText-Package which is a Ruby implementation of the Gettext interface that also has some c-bindings for the Locale.

If you have rubygems, you can easily install Ruby-GetText:

$ gem install gettext
Select which gem to install for your platform (...)
 1. gettext 1.9.0 (ruby)
 2. gettext 1.9.0 (mswin32)
 ...
>

Be sure to choose option 2 if you want Ruby-GetText to work on native Windows (with One-Click Ruby Installer) as you are most likely not able to compile otherwise. For all other platforms use 1.

Alternative: If you need the source you can get it from the author’s site: Ruby-GetText-Package. Besides installation instructions you will find a small HOWTO, API Reference and documentation on how to use provided tools.

Check the sample Rails application that is delivered with Ruby-GetText. If you installed via RubyGems it is most likely here: /usr/lib/ruby/gems/1.8/gems/gettext-1.9.0/samples/rails/, but it could be somewhere else depending on where your Ruby is installed. Later I will call that path $RUBYGETTEXT_RAILS_SAMPLE. So keep this in mind when you read.

Create the “po” directory structure

Create a po dir right in your $RAILS_ROOT. In it you will create a subdir for every language/dialect combination (actually the second part of this abbreviation stands for “geographic region”, but I will just call it dialect throughout this document). If you don’t know the right code for your language you can seek help at the Language section of the W3C I18N Topic Index.

Ultimately your directory structure is going to look like this:

simplepages@colinux: /home/simplepages/rails/po:
$ d -T
/home/simplepages/rails/po/:
 |-myapp.pot
 |-de_DE/:
 |    `-myapp.po
 |-en_GB/:
 |    `-myapp.po
 |-en_US/:
 |    `-myapp.po
 |-fr_FR/:
 |    `-myapp.po
 |-fr_CH/:
 |    `-myapp.po
 `-ja/:
      `-myapp.po

The myapp.pot file is the original file created by the rgettext script introduced later. The po files will contain the translation messages that your application is going to use depending on the language that is requested.

Convert pofiles to mofiles

After creating pofiles, you need to convert them to mofiles. If you haven’t yet, please read the the GNU Gettext manual with the explanation of what mo and po stands for.

Add the code below to Rakefile:

simplepages@colinux: /home/simplepages/rails/Rakefile
require 'gettext/utils'
desc "Create mo-files for L10n" 
task :makemo do
 GetText.create_mofiles(true, "po", "locale")
end

Then,

$ rake makemo

It will create locale directories and subdirectroies such as:

simplepages@colinux: /home/simplepages/rails/locale:
$ d -T
/home/simplepages/rails/locale/:
 |-de_DE/:
 |   `-LC_MESSAGES/:
 |       |-myapp.mo
 |-en_GB/:
 |   `-LC_MESSAGES/:
 |       |-myapp.mo
 |-en_US/:
 |   `-LC_MESSAGES/:
 |       |-myapp.mo
 |-fr_FR/:
 |   `-LC_MESSAGES/:
 |       |-myapp.mo
 |-fr_CH/:
 |   `-LC_MESSAGES/:
 |       |-myapp.mo
 `-ja/:
     `-LC_MESSAGES/:
         |-myapp.mo

These files are used by Ruby-GetText. You don’t need to touch these files.

Tools of trade

Gettext

You will need to install Gettext. On Debian I would do apt-get install gettext to do that. It contains a couple of tools that will be handy later on, most importantly msgmerge which can merge different po files so updating your message files will be a snap and msginitwhich can set default values to the header of pofile in your locale.

Ruby-GetText and rgettext

After you have installed Ruby-GetText and tools you should able to call rgettext on the command line. rgettext is a replacement for xgettext which comes with the main Gettext application. Beyond xgettext, rgettext supports not only ruby scripts(.rb) but also ERB files (.rhtml), ActiveRecord(.rb) directly.

h4. ActiveRecord support rgettext extracts all the table names and field names within subclasses of ActiveRecord::Base.

Notice: You need to run your database server and configure the config/database.xml correctly before executing rgettext.

poEdit

poEdit is a great tool to manage and edit your translations. It gives you a nice graphical frontend to translate all your messages. It is available for many different platforms. A nice side effect about using an easy to use GUI tool is that you can tell non-programmers to install it, open the po file and just start translating. They might have nothing to do with the coding in your project but will be able to help you translate your software. So if your grandma can translate English to Chinese she can maybe help you with your software project :)

Collecting messages

Add the code below to Rakefile:

simplepages@colinux: /home/simplepages/rails/Rakefile
desc "Update pot/po files to match new version." 
task :updatepo do
 MY_APP_TEXT_DOMAIN = "myapp" 
 MY_APP_VERSION     = "myapp 1.1.0" 
 GetText.update_pofiles(YOUR_APP_TEXT_DOMAIN,
                        Dir.glob("{app,lib}/**/*.{rb,rhtml}"),
                        MY_APP_VERSION)
end

Running this task will either create or update your po/myapp.pot and po/*/myapp.po files in the relevant directories. It will go through all the important directories of your rails app and harvest all the Gettext strings in files ending in *.rb, *.rhtml.

$ rake updatepo

Translating and compiling with and without poEdit

After you have successfully harvested your files you should have a myapp.po file in every locale dir. Now you need to translate them. Since the myapp.po files are mere text files you could just use your favourite text editors to translate them. Given that your text editor can edit in UTF-8 mode and you know the escaping rules of Gettext this is all you actually need. Open the file, translate the text and save it. After you have saved the file compile it. Gettext doesn’t work with the text files (myapp.po) directly. It wants a compiled version of it (myapp.mo). Use the rake makemo command to compile:

simplepages@colinux: /home/simplepages/rails/po/de_DE:
$ ls
myapp.po

simplepages@colinux: /home/simplepages/rails:
$ rake makemo

simplepages@colinux: /home/simplepages/rails/locale/de_DE/LC_MESSAGES:
$ ls
myapp.mo

However, it is way more comfortable to use an application like poEdit for this. With poEdit you can also easily open up the myapp.po file. It will give you a nice side by side view your original strings and the translated version, telling what is already translated and what is not. You click on a message and start translating it in a special field. Hit the save button and poEdit will automatically compile the myapp.mo file for you (check the preferences if it doesn’t do it by default). That’s it. With a compiled myapp.mo you can start to teach your rails app how to translate your user interface.

See Documents for Translators for more details to translate the po-file.

When creating a po file it is useful to include header information at the top of the po file. This adds useful information such as character set, last translator etc. If you are not using poEdit add something similar to the top of the po file.

msgid "" 
msgstr "" 
"POT-Creation-Date: 2007-02-19 17:15-0000\n" 
"PO-Revision-Date: 2003-04-03 10:49--500\n" 
"Last-Translator: Alastair Brunton <alastair@brunton.com>\n" 
"Language-Team: fr_FR <langteam@langteam.com>\n" 
"MIME-Version: 1.0\n" 
"Content-Type: text/plain; charset=UTF-8\n" 
"Content-Transfer-Encoding: 8bit\n"

Implementing Ruby-GetText into your rails app

By now you should have a translated and compiled myapp.mo in your locale dir. For example my German translation of SimplePages is at $RAILS_ROOT/locale/de_DE/LC_MESSAGES/myapp.mo.

Including Ruby-GetText

Edit application.rb to bind textdomain to your application.

simplepages@colinux: /home/simplepages/rails/app/controllers/application.rb:
require 'gettext/rails'

class ApplicationController < ActionController::Base
 init_gettext "myapp" 
 #init_gettext "myapp", "UTF-8", "text/html" # <= Also you can set charset and content_type.
end

In this sample, the textdomain name is “myapp”. Replace it as you like to fit your application. Maybe you want to have different textdomains for your site and the admin section.

Selecting the scope of your textdomain

If you call bindtextdomain in ApplicationControler, the textdomain applies to the entire application.
If you call bindtextdomain in any other controller with a different textdomain, this textdomain only applies to this specific controller. For example if you call a different textdomain in myapp_controller.rb it will only be used in myapp_controller.rb.

The textdomains are applied to each controller/view/model.

Choosing the right language on every request

Since we are developing a web application we want to be able to choose the current language by request. Additionally we might want to offer the user the possibilty to choose the language from a menu.

Ruby-GetText chooses the current language by following these rules in the given order:

the first value passed to the ‘locale’ parameter of GetText.bindtextdomain method call
‘lang’ value of QUERY_STRING
‘lang’ value of the Cookie
the value of HTTP_ACCEPT_LANGUAGE
or default ‘en’ (English).

The script $RUBYGETTEXT_RAILS_SAMPLE/vendor/plugins/lang_helper.rb is a sample that selects locale using the cookie value of the user.

It may be useful to implement a simple controller action to change between languages eg.

class CookieController < ApplicationController
 def set_cookie
   code = params[:id]
   cookies[:lang] =
     {
      :value => code,
      :expires => Time.now + 1.year,
      :path => '/'
     }
   redirect_to home_url
 end
end

So /cookie/set_cookie/fr_FR would change the language to French.

Using the Locale in your templates

Depending on the selected locale you will want to customize the language and character set in your templates.

File: $RAILS_ROOT/app/view/layouts/main.rhtml

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="<%= Locale.get %>" lang="<%= Locale.get %>">
<head>
<title><%= @page["title"] %></title>
<meta http-equiv="content-type" content="text/html; charset=<%= Locale.charset %>" />
...

Have your own textdomain for plugin applications

If you are a plugin developer and want to have your own textdomain, you need to separate the Class/Module from ActionView::Base/ApplicationController.

simplepages@colinux: /home/simplepages/rails/vendor/plugins/gettext/lib/gettext_plugin.rb:
require 'gettext/rails'

module LangHelper
 # If you need to bind yet another textdomain to your plugin.
 # Separate the name space from ActionView::Base/ApplicationController.
 class YetanotherTextDomain
   include GetText::Rails

   def initialize
     # You need to call bindtextdomain in an instance of ActionView::Base.
     # The locale is used a same values which define ApplicationController#init_gettext instead of
     # the textdomain.
     bindtextdomain("gettext_plugin")
   end

   def show_language(actionview)
     langs = ["en"] + Dir.glob(File.join(RAILS_ROOT,"locale/*")).collect{|item| File.basename(item)}
     langs.delete("CVS")
     langs.uniq!
     ret = "<h4>" + _("Select locale") + "</h4>" 
     langs.sort.each do |lang|
       ret << actionview.link_to("[#{lang}]", :action => "cookie_locale", :lang => lang)
     end
     ret
   end

   def cookie_locale(cookies, flash, params)
     cookies["lang"] = params["lang"]
     flash[:notice] = _('Cookie &quot;lang&quot; is set: %s') % params["lang"]
   end
 end

 # This function shows supported languages with link to set cookie
 # action (cookie_locale).
 def show_language
   YetanotherTextDomain.new.show_language(self)
 end

 # This function is called when the language link is set.
 def cookie_locale
   YetanotherTextDomain.new.cookie_locale(cookies, flash, params)
   redirect_to :action => 'list'
 end
end

Simply put gettext_plugin.po into the po directory.

Conclusion

That’s it. If you have your translated message catalogs (myapp.mo) in all the right places your application should show your message strings in your favourite language.

You can now easily start to translate your application into all the different languages you want. I hope this guide helps you to get started. There are certainly many more aspects of internationalization that you will have to learn and apply. Remember that this is only one of many possible ways to do it. If you find any mistakes, shortcomings or have good suggestions on how to improve this guide I would be more than happy to hear from you.

If you want you can download the original Textile document, make modifications and send them back to me. I will be sure to include you in the credits section.

Sascha Ebach se at digitale-wertschoepfung dot de

Credits

David Heinemeier Hansson for creating the best web application framework that has ever existed P-E-R-I-O-D
Masao Mutoh – The Author of Ruby-GetText: mutoh at highway dot ne dot jp. Thanks to Masao for extending the old version and making it more flexible.
Alastair Brunton for providing some sorely needed modifications to this article.

Author

Sascha Ebach is the owner and lead developer of a small web design and development shop Digitale Wertschöpfung in Cologne, Germany. Together with his two partners he develops and designs complete online solutions for small to medium sized businesses. Up until the surfacing of Rails he used to develop everything in PHP although he has already fallen deeply in love with Ruby since version 1.6.2 came out. For him it is very clear that Rails and Ruby will be The Future Way of developing web applications and he already looks forward to the day when he has ported his last line of PHP to Ruby.

Appendix A: Downloads

Used files

Download the archive with files and scripts I use and talk about in this guide. The file includes the complete skeleton of files that you need to get started.

/home/simplepages/using-gettext-with-rails/:
 |-app/:
 |   `-controllers/:
 |       `-application.rb (the ApplicationController with the .init_gettext method)
 `-po/: (sample directory structure)
     |-de_DE/:
     |-en_GB/:
     `-en_US/:

Download using-gettext-with-rails.tgz

Chris Carter: The 4 Hashes of the Apocolypse

After the request has been made by using one of the 5 methods (get, post, etc…), you will have 4 Hash objects ready for use.

They are (starring in alphabetical order):

assigns : any objects that are stored as instance variables in actions for use in views
cookies : any objects cookies that are set
flash : any objects living in the flash
session : any object living in session variables

For example, let’s say we have a MoviesController with an action called movie. The code for that action might look something like:

def movie
  @movie = Movie.find(params[:id])
  if @movie.nil?
    flash['message'] = "That movie has been burned." 
    redirect_to :controller => 'error', :action => 'missing'
  end
end

Now, to test out if the proper movie is being set, we could have a series of tests that look like this:

# this test proves that fetching a movie works
def test_successfully_finding_a_movie
  get :movie, "id" => "1" 
  assert_not_nil assigns["movie"]
  assert_equal 1, assigns["movie"].id
  assert flash.empty?
end

# and when we can't find a movie...
def test_movie_not_found
  get :movie, "id" => "666999" 
  assert_nil assigns["movie"]
  assert flash.has_key?("message")
  assert assigns.empty?
end

As is the case with normal Hash objects, you can access the values by referencing the keys by string. You can also reference them by symbol name… except assigns. Check it out:

flash["gordon"]  flash[:gordon]
session["shmession"]  session[:shmession]
cookies[“are_good_for_u”]  cookies[:are_good_for_u]

assigns["something"]  assigns(:something) # because you can’t use assigns[:something] for historical reasons

Keep an eye out for that. mmmm kay?

Chris Carter: An Anatomy Lesson

So let’s take a look at an example of a functional test.

require File.dirname(__FILE__) + '/../test_helper'

# grab our HomeController because we're going to test it
require 'home_controller'

# Raise errors beyond the default web-based presentation
class HomeController; def rescue_action(e) raise e end; end

class HomeControllerTest < Test::Unit::TestCase
  def setup
    @controller = HomeController.new
    @request = ActionController::TestRequest.new
    @response = ActionController::TestResponse.new
  end

  # let's test our main index page
  def test_index
    get :index
    assert_response :success
  end
end

The big three

In the setup method, we create 3 objects:

One of your controllers to be tested (aka. @controller)
A TestRequest to simulate a web request (aka. @request)
A TestResponse to provide information about the test request (aka. @response)

99% if not 100% of your functional tests will have these 3 objects in the setup.

Making the moves

In the one test we have called test_index, we are simulating a request on the action called index and making sure the request was successful.

The get method kicks off the web request and populates the results into the response. get method accepts 4 arguments.

The action of the controller you are requesting. It can be in the form of a string or a symbol. Cool people use symbols. ;)
An optional hash of request parameters to pass into the action (eg. query string parameters or post variables).
An optional hash of session variables to pass along with the request.
An optional hash of flash to stash your goulash.

Example: Calling the :show action, passing an id of 12 as the params and setting user_id of 5 in the session.

get :show, {'id' => "12"}, {'user_id' => 5}

Another Example: Calling the :view action, passing an id of 12 as the params, this time with no session, but with a flash message.

get :view, {'id' => '12'}, nil, {'message' => 'booya!'}

Available at your disposal

For those of you familiar with HTTP protocol, you’ll know that get is a type of request. There are 5 request types supported in Rails:

get
post
put
head
delete

All of request types are methods that you can use, however, you’ll probably end up using the first two more ofter than the others.

Chris Carter: An Anatomy Lesson

So let’s take a look at an example of a functional test.

require File.dirname(__FILE__) + '/../test_helper'

# grab our HomeController because we're going to test it
require 'home_controller'

# Raise errors beyond the default web-based presentation
class HomeController; def rescue_action(e) raise e end; end

class HomeControllerTest < Test::Unit::TestCase
  def setup
    @controller = HomeController.new
    @request = ActionController::TestRequest.new
    @response = ActionController::TestResponse.new
  end

  # let's test our main index page
  def test_index
    get :index
    assert_response :success
  end
end

The big three

In the setup method, we create 3 objects:

One of your controllers to be tested (aka. @controller)
A TestRequest to simulate a web request (aka. @request)
A TestResponse to provide information about the test request (aka. @response)

99% if not 100% of your functional tests will have these 3 objects in the setup.

Making the moves

In the one test we have called test_index, we are simulating a request on the action called index and making sure the request was successful.

The get method kicks off the web request and populates the results into the response. get method accepts 4 arguments.

The action of the controller you are requesting. It can be in the form of a string or a symbol. Cool people use symbols. ;)
An optional hash of request parameters to pass into the action (eg. query string parameters or post variables).
An optional hash of session variables to pass along with the request.
An optional hash of flash to stash your goulash.

Example: Calling the :show action, passing an id of 12 as the @params and setting user_id of 5 in the session.

get :show, {'id' => "12"}, {'user_id' => 5}

Another Example: Calling the :view action, passing an id of 12 as the params, this time with no session, but with a flash message.

get :view, {'id' => '12'}, nil, {'message' => 'booya!'}

Available at your disposal

For those of you familiar with HTTP protocol, you’ll know that get is a type of request. There are 5 request types supported in Rails:

get
post
put
head
delete

All of request types are methods that you can use, however, you’ll probably end up using the first two more ofter than the others.

Chris Carter: Fixtures in Action

Rails makes no assumptions when it comes to fixtures. You must explicitly load them yourself by using the fixtures method within your TestCase. For example, a users model unit test might look like this:

# allow this test to hook into the Rails framework
require File.dirname(__FILE__) + '/../test_helper'

# we're testing a User, so we need to include it
require 'user'

class UserTest < Test::Unit::TestCase

  fixtures :users

  # count the fixtures
  def test_count_my_fixtures
    assert_equal 5, User.count
  end

end

Using the fixtures method and placing the symbol name of the model, Rails will automatically load up the fixtures for you at the start of each test method.

fixtures :users

What exactly does this line of code do? It does 3 things:

it nukes any existing data living in the users table
it loads the fixture data (if any) into the users table
it dumps the data into a variable in case you want to access it directly

So, in the above example, if we had another test method, we wouldn’t have 10 users on the 2nd test because they would be wiped out before being created.

You can load multiple fixtures by including them on the same line separated by commas.

fixtures :users, :losers, :bruisers, :cruisers

Chris Carter: Hashes with Special Powers

Fixtures are basically Hash objects. As mentioned in point #3 above, you can access the hash object directly because it is automatically setup as a local variable of the test case.

...
  fixtures :users

  def test_user
    # this will return the Hash for the fixture named david
    users(:david)

    # this will return the property for david called id
    users(:david).id
  end
...

But, by there’s another side to fixtures… at night, if the moon is full and the wind completely still, fixtures can also transform themselves into the form of the original class!

Now you can get at the methods only available to that class.

...
  fixtures :users

  def test_user
    # using the find method, we grab the "real" david as a User
    david = users(:david).find

    # an now we have access to methods only available to a User class
    email( david.girlfriend.email, david.illegitimate_children )
  end
...

rabble: Response-Related Assertions

There are 3 assertions that deal with the overall response to a request. They are:

assert_template `( expected_template, [msg] )`

Ensures the expected template was responsible for rendering. For example:

assert_template "user/profile"

This code will fail unless the template located at app/views/user/profile.rhtml was rendered.

assert_response `( type_or_code, [msg] )`

Ensures the response type/status code is as expected. The possible options are:

:success (status code is 200)
:redirect (status code is within 300..399)
:missing (status code is 404)
:error (status code is within 500..599)
any number (to specifically reference a particular status code)

assert_response :success      # page rendered ok
assert_response :redirect     # we've been redirected
assert_response :missing      # not found
assert_response 505           # status code was 505

assert_redirected_to `( options={}, [msg] )`

Ensures we’ve been redirected to a specific place within our application.

assert_redirected_to :controller => 'widget', :action => 'view', :id => 555

rabble: Response-Related Assertions

There are 3 assertions that deal with the overall response to a request. They are:

assert_template `( expected_template, [msg] )`

Ensures the expected template was responsible for rendering. For example:

assert_template "user/profile"

This code will fail unless the template located at app/views/user/profile.rhtml was rendered.

assert_response `( type_or_code, [msg] )`

Ensures the response type/status code is as expected. The possible options are:

:success (status code is 200)
:redirect (status code is within 300..399)
:missing (status code is 404)
:error (status code is within 500..599)
any number (to specifically reference a particular status code)

assert_response :success      # page rendered ok
assert_response :redirect     # we've been redirected
assert_response :missing      # not found
assert_response 505           # status code was 505

assert_redirected_to `( options={}, [msg] )`

Ensures we’ve been redirected to a specific place within our application.

assert_redirectd_to :controller => 'widget', :action => 'view', :id => 555

rabble: The Assertion Lineup

By now you’ve caught a glimpse of some of the assertions that are available. Assertions are the worker bees of testing. They are the ones that actually perform the checks to ensure things are going as planned.

There are a bunch of different types of assertions you can use. Here’s the complete list of assertions that ship with test/unit. The [msg] is an optional string message you can specify to make your test failure messages clearer. It’s not required.

*assert* ( boolean, [msg] ) ... ensures the object/expression is true

*assert_equal* ( obj1, obj2, [msg] ) ... ensures obj1 obj2 is true @*assert_not_equal* ( obj1, obj2, [msg] )@ ... ensures obj1 obj2 is false

*assert_same* ( obj1, obj2, [msg] ) ... ensures obj1.equal?(obj2) is true

*assert_not_same* ( obj1, obj2, [msg] ) ... ensures obj1.equal?(obj2) is false

*assert_nil* ( obj, [msg] ) ... ensures obj.nil? is true

*assert_not_nil* ( obj, [msg] ) ... ensures obj.nil? is false

*assert_match* ( regexp, string, [msg] ) ... ensures a string matches the regular expression

*assert_no_match* ( regexp, string, [msg] ) ... ensures a string doesn’t matches the regular expression

*assert_in_delta* ( expecting, actual, delta, [msg] ) ... ensures the numbers expecting and actual are within delta of each other

*assert_throws* ( symbol, [msg] ){ block } ... ensures a block throws the symbol

*assert_raises* ( exceptions ){ block } ... ensures a block raises one of the comma-separated exceptions

*assert_nothing_raised* ( exceptions ){ block } ... a block doesn’t raise one of the comma-separated exceptions

*assert_instance_of* ( class, obj, [msg] ) ... ensures obj is the class type

*assert_kind_of* ( class, obj, [msg] ) ... ensures obj is or descends from class

*assert_respond_to* ( obj, symbol, [msg] ) ... ensures obj has a method called symbol

*assert_operator* ( obj1, operator, obj2, [msg] ) ... ensures obj1.operator(obj2) is true

*assert_send* ( array, [msg] ) ... ensures that executing the method listed in array[ 1 ] on the object in array[ 0 ] with the parameters of array[ 2 and up ] is true. This one is weird eh?

*flunk* ( [msg] ) ... ensures failure… like me and high school chemistry exams.

Because of the modular nature of the testing framework, it is possible to create your own assertions. In fact, that’s exactly what Rails does. It has some specialized assertions to make your life easier.

Creating your own assertions is more of an advanced topic we won’t cover in this tutorial.

Jamis Buck: Deploying

The first deployment is a bit tricky with this setup, because you have to do some bootstrapping. The spinner isn’t running, and you have to get it running. But we can’t get it running until we’ve deployed the application…

Not to worry. We’ll just create a couple of custom tasks that will get everything set up for us:

Tasks for initial deployment [ruby]

1
2
3
4
5
6
7
8
9
10
11
12
13
14

  desc "Start the spinner daemon"
  task :spinner, :roles => :app do
    run "#{current_path}/script/spin"
  end

  desc "Used only for deploying when the spinner isn't running"
  task :cold_deploy do
    transaction do
      update_code
      symlink
    end

    spinner
  end

The first task only applies to the app servers, and all it does is start the spinner by invoking our custom spin script.

The second task is a more complicated one. It calls the update_code and symlink tasks in a transaction. This means that if either of those tasks fails, they will be rolled back, leaving the system in a consistent state. Once those two tasks finish successfully (executing on all boxes), our new spinner task is invoked (which will only be executed on the app servers, remember).

Once that’s all done, you just have to invoke the cold_deploy task, and you’re golden!

Invoking cold_deploy [shell]

  rake remote:exec ACTION=cold_deploy

Once you’ve got the spinner running, future deployments can simply use the default deploy task:

Invoking deploy [shell]

  rake deploy

Jamis Buck: Deployment Recipe

The first thing we need to do is revisit our deployment recipe. The roles, in particular need to be completely revisited, and we can also get rid of our custom restart task. The complete deploy.rb file looks like this:

Multi-server deployment recipe [ruby]

1
2
3
4
5
6
7

  set :application, "flipper"
  set :repository,  "http://svn.capistrano.com/flipper/trunk"

  role :web, "www1.capistrano.com", "www2.capistrano.com"
  role :app, "app1.capistrano.com", "app2.capistrano.com"
  role :db,  "db1.capistrano.com", :primary => true
  role :db,  "db2.capistrano.com"

We now have two servers (www1 and www2) in the web role, and two servers (app1 and app2) in the app role. Fairly self-explanatory.

Looking at the db role, though, we have one server (db1) with the extra information :primary => true. This tells Capistrano that some tasks should be executed only on this server, and not on all db servers. (This is useful for things like migrations, where you only want them applied to the primary copy of the data. You could also add :slave => true to the db2 server and then define a backup task that only ran on the slave.)

We can now run the setup task again to make sure our directories are all set up on all six machines. Just type:

Running setup [shell]

  rake remote:exec ACTION=setup

Jamis Buck: Setup

Okay, now that we’ve got a basic deployment recipe going, we can try it out by executing the setup task. This task will set up the basic deployment directory structure on our production box for us.

The deployment directory structure is:

Deployment directory structure [chart]

[deploy_to]
  +- releases
  |    +- 20050725121411
  |    +- 20050801090107
  |    +- 20050802231414
  |    ...
  |    +- 20050824141402
  |    |   +- Rakefile
  |    |   |  app
  |    |   |  config
  |    |   |  db
  |    |   |  lib
  |    |   |  log --> [deploy_to]/shared/log
  |    |   |  public
  |    |   |    +- ...
  |    |   |       system --> [deploy_to]/shared/system
  |    |   |       ...
  |    |   |  script
  |    |   |  test
  |    |   |  vendor
  |
  +- shared
  |    +- log
  |    +- system
  |
  + current --> [deploy_to]/releases/20050824141402

The [deploy_to] represents the root of your deployment path. By default, Capistrano uses "/u/apps/#{application}" as the root of the deployment path, but you can specify whatever root you want via the :deploy_to variable in your recipe file:

Custom deployment root [ruby]

set :deploy_to, "/var/www/flipper"

Beneath the deployment root are two other directories, releases and shared. The releases directory contains one subdirectory for every released version of your software. Each subdirectory is named for the time (in Universal Standard Time) at which it was deployed.

The shared directory contains directories and files that should be shared between multiple releases, like log files and static system HTML files (like a “down for maintenance page”).

Finally, the deployment root contains a symlink called current that points the current release.

It isn’t necessary to build all these directories yourself. You can use the default setup Capistrano task to do it for you. Just type the following:

Executing the setup task [shell]

rake remote:exec ACTION=setup

This will prompt you for your server’s password. (If you don’t want the password to echo to the screen as you type it, be sure you have the termios gem installed—only guaranteed to work in *nix environments.)

After you enter the password, Capistrano will go out to your server and build the necessary directories, chmod-ing them as necessary.

Nifty, huh? But this is only the beginning…

Sam Joseph: Filtering emails in development

Sometimes you want to be somewhere inbetween the :test and :smtp settings. Say you’re working on your development site, and you have a few testers working with you. The site isn’t in production yet, but you’d like the testers to be able to receive emails from the site, but no one else. Here’s a handy way to handle that situation, add this to your environment.rb or development.rb file

class ActionMailer::Base

  def perform_delivery_fixed_email(mail)
    destinations = mail.destinations
    if destinations.nil?
      destinations = ["mymail@me.com"]
      mail.subject = '[TEST-FAILURE]:'+mail.subject
    else
      mail.subject = '[TEST]:'+mail.subject
    end
    approved = ["testerone@me.com","testertwo@me.com"]
    destinations = destinations.collect{|x| approved.collect{|y| (x==y ? x : nil)}}.flatten.compact
    mail.to = destinations
    if destinations.size > 0
      mail.ready_to_send
      Net::SMTP.start(server_settings[:address], server_settings[:port], server_settings[:domain], 
                    server_settings[:user_name], server_settings[:password], server_settings[:authentication]) do |smtp|
        smtp.sendmail(mail.encoded, mail.from, destinations)
      end
    end

  end

end

Sam Joseph: Functional Testing

Functional testing involves more than just checking that the email body, recipients and so forth are correct. In functional mail tests we call the mail deliver methods and check that the appropriate emails have been appended to the delivery list. It is fairly safe to assume that the deliver methods themselves do their job – what we are probably more interested in is whether our own business logic is sending emails when we expect them to. For example the password reset operation we used an example in the previous section will probably be called in response to a user requesting a password reset through some sort of controller.

require File.dirname(__FILE__) + '/../test_helper'
require 'my_controller'

# Raise errors beyond the default web-based presentation
class MyController; def rescue_action(e) raise e end; end

class MyControllerTest < Test::Unit::TestCase

  def setup
    @controller = MyController.new
    @request, @response = ActionController::TestRequest.new, ActionController::TestResponse.new
  end

  def test_reset_password
    num_deliveries = ActionMailer::Base.deliveries.size
    post :reset_password, :email => 'bob@test.com'

    assert_equal num_deliveries+1, ActionMailer::Base.deliveries.size
  end

end

Sam Joseph: Unit Testing

In order to test that your mailer is working as expected, we can use unit tests to compare the actual results of the mailer with pre-writen examples of what should be produced.

revenge of the fixtures

For the purposes of unit testing a mailer, fixtures are used to provide an example of how output “should” look. Because these are example emails, and not Active Record data like the other fixtures, they are kept in their own subdirectory from the other fixtures. Don’t tease them about it though, they hate that.

When you generated your mailer (you did that right?) the generator created stub fixtures for each of the mailers actions. If you didn’t use the generator you’ll have to make those files yourself.

The basic test case

Here is an example of what you start with.

require File.dirname(__FILE__) + '/. ./test_helper'
require 'my_mailer'

class MyMailerTest < Test::Unit::TestCase
  FIXTURES_PATH = File.dirname(__FILE__) + '/. ./fixtures'

  def setup
    ActionMailer::Base.delivery_method = :test
    ActionMailer::Base.perform_deliveries = true
    ActionMailer::Base.deliveries = []

    @expected = TMail::Mail.new
  end

  def test_signup
    @expected.subject = 'MyMailer#signup'
    @expected.body    = read_fixture('signup')
    @expected.date    = Time.now

    assert_equal @expected.encoded, MyMailer.create_signup(@expected.date).encoded
  end

  private
    def read_fixture(action)
      IO.readlines("#{FIXTURES_PATH}/my_mailer/#{action}")
    end
end

The setup method is mostly concerned with setting up a blank slate for the next test. However it is worth describing what each statement does

ActionMailer::Base.delivery_method = :test

sets the delivery method to test mode so that email will not actually be delivered (useful to avoid spamming your users while testing) but instead it will be appended to an array (ActionMailer::Base.deliveries).

ActionMailer::Base.perform_deliveries = true

Ensures the mail will be sent using the method specified by ActionMailer::Base.delivery_method, and finally

ActionMailer::Base.deliveries = []

sets the array of sent messages to an empty array so we can be sure that anything we find there was sent as part of our current test.

However often in unit tests, mails will not actually be sent, simply constructed, as in the example above, where the precise content of the email is checked against what it should be. Dave Thomas suggests an alternative approach, which is just to check the part of the email that is likely to break, i.e. the dynamic content. The following example assumes we have some kind of user table, and we might want to mail those users new passwords:

require File.dirname(__FILE__) + '/../test_helper'
require 'my_mailer'

class MyMailerTest < Test::Unit::TestCase
  fixtures :users
  FIXTURES_PATH = File.dirname(__FILE__) + '/../fixtures'
  CHARSET = "utf-8" 

  include ActionMailer::Quoting

  def setup
    ActionMailer::Base.delivery_method = :test
    ActionMailer::Base.perform_deliveries = true
    ActionMailer::Base.deliveries = []

    @expected = TMail::Mail.new
    @expected.set_content_type "text", "plain", { "charset" => CHARSET }
  end

  def test_reset_password
    user = User.find(:first)
    newpass = 'newpass'
    response = MyMailer.create_reset_password(user,newpass)
    assert_equal 'Your New Password', response.subject
    assert_match /Dear #{user.full_name},/, response.body
    assert_match /New Password: #{newpass}/, response.body
    assert_equal user.email, response.to[0]
  end

  private
    def read_fixture(action)
      IO.readlines("#{FIXTURES_PATH}/community_mailer/#{action}")
    end

    def encode(subject)
      quoted_printable(subject, CHARSET)
    end
end

and here we check the dynamic parts of the mail, specifically that we use the users’ correct full name and that we give them the correct password.

Sam Joseph: Unit Testing

In order to test that your mailer is working as expected, we can use unit tests to compare the actual results of the mailer with pre-writen examples of what should be produced.

revenge of the fixtures

When you generated your mailer (you did that right?) the generator created stub fixtures for each of the mailers actions. If you didn’t use the generator you’ll have to make those files yourself.

The basic test case

Here is an example of what you start with.

require File.dirname(__FILE__) + '/. ./test_helper'
require 'my_mailer'

class MyMailerTest < Test::Unit::TestCase
  FIXTURES_PATH = File.dirname(__FILE__) + '/. ./fixtures'

  def setup
    ActionMailer::Base.delivery_method = :test
    ActionMailer::Base.perform_deliveries = true
    ActionMailer::Base.deliveries = []

    @expected = TMail::Mail.new
  end

  def test_signup
    @expected.subject = 'MyMailer#signup'
    @expected.body    = read_fixture('signup')
    @expected.date    = Time.now

    assert_equal @expected.encoded, MyMailer.create_signup(@expected.date).encoded
  end

  private
    def read_fixture(action)
      IO.readlines("#{FIXTURES_PATH}/my_mailer/#{action}")
    end
end

The setup method is mostly concerned with setting up a blank slate for the next test. However it is worth describing what each statement does


ActionMailer::Base.delivery_method = :test


ActionMailer::Base.perform_deliveries = true

Ensures the mail will be sent using the method specified by ActionMailer::Base.delivery_method, and finally


ActionMailer::Base.deliveries = []

sets the array of sent messages to an empty array so we can be sure that anything we find there was sent as part of our current test

Jamis Buck: Extension Libraries

Sometimes, you’ll write methods that you want multiple tasks to share. The methods themselves aren’t tasks, they are simply lower-level operations, like the run or put or delete methods that Capistrano itself provides.

Capistrano allows you to easily distribute and share libraries of these extension methods, as well as tasks. Simply put your extension methods in a module, register the module with Capistrano, and then package it up and ship it. People can then use your extension methods simply by requiring the file, the same as with task libraries.

Sample extension library [ruby]

require 'capistrano'

module MyReportingMethods
  def display(options={})
    ...
    run(...)
    ...
    put(...)
    ...
  end
end

Capistrano.plugin :report, MyReportingMethods

The last line is where your plugin is registered with Capistrano. You simply give it a name (:report, in this case) and point it at your new module.

Once a recipe file loads this extension, it can access your report’s display method via report.display(...), effectively namespacing your extension methods.

Using an extension library [ruby]

  require 'my_reporting_methods'

  task :show_general_report do
    report.display
  end

  task :show_app_report, :roles => :app do
    report.display
  end

Jamis Buck: Using a Task Library

Now, you (or your friend, or anybody else) can use that library simply by installing it. In your deploy.rb, you just require the file like you would any other ruby file:

Using a task library [ruby]

  require 'custom-tasks'

Doing cap show_tasks now ought to list your two custom tasks, along with all the standard ones.

Hieraki recent changes

rabble: Blogs

rabble: Blogs

Sascha Ebach: Translating Rails Apps

Using Gettext To Translate Your Rails Application

Introduction

Stand on the shoulders of Giants

What can Gettext do for you?

Preperation is everything—use UTF-8 everywhere

Edit your files with UTF-8 only

Feed your database with UTF-8

Installing Ruby-GetText

Create the “po” directory structure

Convert pofiles to mofiles

Tools of trade

Gettext

Ruby-GetText and rgettext

poEdit

Collecting messages

Translating and compiling with and without poEdit

Implementing Ruby-GetText into your rails app

Including Ruby-GetText

Selecting the scope of your textdomain

Choosing the right language on every request

Using the Locale in your templates

Have your own textdomain for plugin applications

Conclusion

Credits

Author

Appendix A: Downloads

Used files

Chris Carter: The 4 Hashes of the Apocolypse

Chris Carter: An Anatomy Lesson

The big three

Making the moves

Available at your disposal

Chris Carter: An Anatomy Lesson

The big three

Making the moves

Available at your disposal

Chris Carter: Fixtures in Action

Chris Carter: Hashes with Special Powers

rabble: Response-Related Assertions

assert_template ( expected_template, [msg] )

assert_response ( type_or_code, [msg] )

assert_redirected_to ( options={}, [msg] )

rabble: Response-Related Assertions

assert_template ( expected_template, [msg] )

assert_response ( type_or_code, [msg] )

assert_redirected_to ( options={}, [msg] )

rabble: The Assertion Lineup

Jamis Buck: Deploying

Jamis Buck: Deployment Recipe

Jamis Buck: Setup

Sam Joseph: Filtering emails in development

Sam Joseph: Functional Testing

Sam Joseph: Unit Testing

revenge of the fixtures

The basic test case

Sam Joseph: Unit Testing

revenge of the fixtures

The basic test case

Jamis Buck: Extension Libraries

Jamis Buck: Using a Task Library

assert_template `( expected_template, [msg] )`

assert_response `( type_or_code, [msg] )`

assert_redirected_to `( options={}, [msg] )`

assert_template `( expected_template, [msg] )`

assert_response `( type_or_code, [msg] )`

assert_redirected_to `( options={}, [msg] )`