Both unit and functional tests in Rails use the Fixtures API, which interacts with the database. In fact, it takes quite a bit of hacking to make unit tests in Rails not involve the database. Given that normal Rails tests never test isolated units of Ruby code, they can’t possibly be (true) unit tests; they must all be functional tests, by traditional definitions of the term. Wait a minute—if they’re all functional tests, why is there a unit folder? Ah, you see the conflict.

I’m afraid there isn’t a particularly good defense of the chosen nomenclature. Tests that live in the unit folder are in fact functional tests of models that happen to be oriented toward testing of individual methods, in the traditional unit-test way. Tests that live in the functional folder are indeed functional tests of controllers that happen to be oriented toward testing of individual controller actions. We give both types full sections in this chapter.

The mocks folder is treated specially during test runs. Classes in it are loaded last, meaning that they can override behavior of other classes in your system. That ability is particularly useful when you depend on classes that do things that shouldn’t be done during a test run, such as

Using Ruby’s open classes, you can write your own mock versions of methods that you don’t want to actually execute during your test run. For instance, assume that you have code that submits transactions for processing via a PaymentGateway class. Your production code invokes the process method. Unless you mock it out, whenever you run a test, a transaction will be sent to the actual payment gateway, which is probably bad.

However, you can solve that problem if you monkeypatch^[1] PaymentGateway with your own implementation of process, which does not actually talk to the real payment gateway. You could add a class like the following to your mocks directory.

class PaymentGateway
  def process(transaction)
    # In ur gateway, mocking ur transactions!
  end
end

The concept is somewhat reminiscent of traditional test mocking, yet has nothing to do with it. (It’s actually a form of stubbing—you are stubbing out the real functionality of the class.) Now, if you were doing a mock payment gateway this way for real, you would probably give it some state, to be able to check later that process was actually called.

class PaymentGateway
  attr :processed_transaction

  def process(transaction)
    # In ur gateway, mocking your transactions!
    @processed_transaction = transaction
  end
end

You see, if you didn’t check to see if process was called, you would never know if your code is working correctly. I’m not going to go any further with this example, or with coverage of Rails mocks in this sense. As far as I’m concerned, you should delete the mocks directory. Nobody uses it. In fact, many of us consider this feature of Rails an abomination that should have never seen the light of day.^[2]

The Mocha library^[3] should be your choice for adding mocking to your Rails tests. It’s actually included inside Rails as a dependency of Rails’ own test suite. However, Mocha is a RubyGem, and you should get a copy of the latest version for yourself using the usual gem install magic:

sudo gem install mocha

Mocha provides a unified, simple, and readable syntax for both traditional mocking and for mocking with real objects. A traditional mock is an object that you can script with expectations about which of its methods will be called during a test. If those expectations are not met, the mock object causes the test to fail.

Mocha also gives you the ability to do stubbing, which is the act of overriding existing methods to return known values. It even lets you mock and stub methods on real (non-mock) classes and instances. For example, you can stub ActiveRecord instance methods like find or association accessors and reduce dependence on complicated fixture setups.

For example, here’s a real example of using Mocha to mock behavior that we really don’t want to actually trigger during a test run—that of the Google Geocoder service. Not only would it be slow, but we would never be able to run this test successfully unless we were online:

class SearchControllerTest < Test::Unit::TestCase

  def test_should_geolocate_zip_codes_to_return_cities_result
    res = mock('response')
    res.stubs(:lat => 40, :lng => 50)
    GoogleGeocoder.expects(:geocode).with('07601').returns(res)

    place = mock('place')
    Place.expects(:new).with(:lat => 40, :lng => 50).returns(place)

    hackensack = mock('city')
    City.expects(:near).with(place, 10.miles).returns([hackensack])
    post :index, :text => '07601'

    assert_include hackensack, assigns(:places)
  end
end

In case it isn’t obvious, this test checks to make sure that the search controller invokes the geolocation service to help it find cities near a supplied zip code.

The mock method creates a new mock response object. The actual type of the object doesn’t matter, thanks to duck typing. The stubs method tells the mock which methods should simply return specified values if invoked, using a nice hash syntax.

I’ll stop talking about Mocha now, so we don’t get totally derailed from the overall subject of the chapter, which is, of course, testing. However, throughout the chapter I’ve included some examples on how using Mocha makes your Rails testing tasks easier.

Rails integration tests were introduced in Rails 1.1 and are probably closest to the actual meaning of their name in the software engineering world. They engage the entire stack of Rails components and allow you to chain together multiple requests to test large-scale interactions of application code.

class AdvancedTest < ActionController::IntegrationTest
  fixtures :people, :forums

  def test_login_and_create_forum
    login_as :admin
    get '/forums'
    assert_response :success

    post '/forums', :forum => {:name => 'a new forum'}
    assert_response :redirect
    follow_redirect!

    assert_select 'div#topics div.title:last-of-type', 'a new forum'
  end
end

Integration tests are kind of like functional tests on steroids. You won’t need too many of them in your projects, and you won’t want too many of them either because they’re slow. However, they will prove their worth in helping you flush out hard-to-find interaction bugs. There’s a whole section on integration tests later in the chapter (“Rails Integration Tests”).

Is Rails testing nomenclature confusing? Yes, clearly. Is it going to be fixed anytime soon? Nope.^[4]

Are there options? Of course! It wouldn’t be Ruby otherwise. However, I warn you that going down these roads means leaving the Rails way, and your mileage may vary.

Here’s a quick rundown of your options as I see them:

The one option that you should never take is to ditch testing altogether. Delivering Rails applications without automated test coverage is irresponsible and unprofessional.

Because of the way that Test::Unit classes work, simply executing a test file from the command line with the Ruby interpreter will run all of its test methods. It is also possible to run a single test method, by supplying its name with an -n command-line option:

$ ruby test/unit/timesheet_test.rb -n
  test_only_authorized_user_may_be_associated_as_approver

Loaded suite test/unit/timesheet_test
Started
.
Finished in 1.093507 seconds.

1 tests, 2 assertions, 0 failures, 0 errors

Most of the time, we run the entire test suite for our application by simply typing rake test at the command prompt in our project directory. Even just rake will do, since test is the default task. Later on in the chapter we cover all of the test-related Rake tasks.

Fixtures can also be formatted as comma-separated values (known as CSV). In case you haven’t heard of it, CSV is an old, portable text file format that is best-known nowadays as the best way to get data in and out of Microsoft Excel in a cross-platform-compatible fashion.

Here’s the same (yet much harder to read) fixture as before, but formatted as CSV:

id, email, crypted_password, created_at
1, [email protected], , <%= 6.months.ago.to_s(:db) %>
2, [email protected], <%= Digest::SHA1.hexdigest("password") %>,
<%= 1.minute.ago.to_s(:db) %>

Ugh, that’s ugly. Depending on the nature of your sample data, managing it with a spreadsheet tool like Excel might make sense. However, YAML is by far a more popular choice, because it’s much more readable, and easier to edit by hand.

The fact that records in a YAML fixture file are keyed with meaningful names is another factor that makes YAML a better choice. To access a record from your fixture file, you need to specify use of the fixture in the class context of your test. Then from inside methods you invoke a method with the same name as your fixture file and pass the name of the fixture record as its parameter, for example: users(:quentin) or timesheets(:first). It’s a quick and easy way to access your sample data, and the fact that you can choose the names means that you can give them rich semantic meaning.

fixtures :users

def test_can_access_quentin_fixture
  assert(users(:quentin) != nil)
end

On the other hand, names for records in CSV fixtures are automatically generated, created by deriving the class name of the fixture file and adding an incrementing number to the end. In our example, the first fixture would be called :user_1 and the next would be called :user_2, and so on. There’s no semantic meaning in those names, other than knowing that we’re dealing with a user instance.

Before loading the records of a fixture into the test database, Rails runs its textual content through the ERb template parser. It means you can embed actual Ruby code in your fixture files using <% %> and <%= %> markup, just as you do in your view templates. That dynamic behavior can be leveraged to really streamline the work involved in using fixtures effectively.

The preceding examples have dynamic content. <%= Digest::SHA1.hexdigest ("password") %> saves us from having to actually do the encryption ourselves and manually copy in an unreadable and error-prone string like 00742970dc9e6319f8019fd54864d3ea740f04b1.

Another example is how the date values are populated, by letting Rails take care of formatting the dates the way the database expects them: <%= 5.days.ago.to_s(:db) %>

Use of dynamic content in fixtures is not limited to conversion and formatting of values, though. You can also use looping constructs to create lots of fixture data easily. The example given in the Rails documentation demonstrates the basic technique:

<% for i in 1..1000 %>
fix_<%= i %>:
  id: <%= i %>
  name: guy_<%= 1 %>
<% end %>

Don’t forget that you can put any valid Ruby inside those ERb tags, which includes defining new helper methods and including modules.

One of my biggest annoyances with fixture files used to be having to manually maintain the id numbers in proper sequence. Then I realized I can just add an auto_increment method to the fixture file (I shortened the fixture records themselves for brevity):

<%
  def auto_increment
    @id ||= 0; @id += 1
  end
%>
quentin:
  id: <%= auto_increment %>
  login: quentin
aaron:
  id: <%= auto_increment %>
  login: aaron

If you want to make methods such as auto_increment in the preceding example available to all of your fixture files, define them in a Ruby file called fixture_helpers.rb. Place it in your project’s /lib directory, and make sure they’re available by adding the line require 'fixture_helpers' at the top of test/test_helper.rb.

After spending much time carefully crafting sample data for testing an application, it’s not unusual to want to dump your fixture records into the development database so that you can use that sample data interactively via your browser or console.

The default Rails rake configuration includes a target that does exactly that. Invoke rake db:fixtures:load from the command line to import fixture records into the current environment. That rake target lets you pick a subset of fixtures to load, by adding the variable expression FIXTURE=table1,table2 at the end of the command line.

By the same token, if your application has complicated relationships or you’re just too lazy^[7] to manually craft your fixture files, you might be inclined to automatically generate your fixture files from data in the development database. Assuming you have a working application already, you would be able to just point and click your way to sample data. All you need is a way to get data out of the database and into the right YAML format.

For whatever reason, dumping data to fixtures is not a part of core Rails.^[8] Considering that Rails gives you a to_yaml method on ActiveRecord models and Hash objects, it wouldn’t be too hard to write your own Rake task. However, it’s not necessary to do so because of a well-proven plugin written by Geoff Grosenbach. It’s called ar_fixtures and you can install it with the following command:

$ script/plugin install http://topfunky.net/svn/plugins/ar_fixtures

Once the plugin is installed, dumping a fixture is a simple matter of invoking a new rake task called rake db:fixtures:dump. Unlike the built-in loading rake task, this one takes a MODEL parameter with the name of the ActiveRecord class that you want to dump data for:

$ rake db:fixtures:dump MODEL=BillingCode

No feedback is provided, so check the fixtures file to verify what happened:

--
billing_code_00001:
  code: TRAVEL
  client_id:
  id: 1
  description: Travel expenses of all sorts
billing_code_00002:
  code: DEVELOPMENT
  client_id:
  id: 2
  description: Coding, etc.

Frankly, I’m not too thrilled about the way that the data is dumped with this plugin, but it’s only because I’m picky about wanting my id column to appear first, and things like that. I also don’t like to have entries for nil columns. Nevertheless, this plugin might be a good starting point for your purposes.

By the way, you don’t need to worry about the -- characters at the top of the file. They just indicate the beginning of a YAML document and can be safely deleted.

The use_transactional_fixtures option, present along with explanatory documentation in the standard test/test_helper.rb file of your project, governs whether Rails will try to accelerate your tests by wrapping each test method in a transaction that’s rolled back on completion. The rollback speeds up execution of the test suite, since the fixture data doesn’t have to be reloaded into the database for each test. The default setting for this option is true.

Using transactional fixtures is important for more than just performance. Rolling back changes after each test method ensures that you don’t write test methods that are coupled to each other by depending on database changes that happened outside of their scope. Interlinked test methods are notoriously difficult to debug and a horrible practice to fall into.

The use_instantiated_fixtures setting, which is set by default to false, is another option present in the standard test_helper.rb file. Turning on this setting will make instance variables available automatically for each fixture record, at the cost of severely degraded performance of your tests. It dates back to the earliest versions of Rails, and as far as I can tell, has really fallen out of favor.

During Railsconf 2006, one of the speakers asked, “Who in the audience likes fixtures?”

I was standing in the back of the room, mind wandering a bit, and I’m the type of person who doesn’t hesitate to raise his hand in public situations. As such, I found myself in the awkward position of being one of the only people to answer affirmatively.

Why do so many experienced Rails people hate fixtures? There are various answers to that question—all of them multifaceted. Here are my interpretations of the most popular reasons to hate fixtures, followed by my own feelings on the Rails way to use fixtures.

<% fixtures :employees %>

packaging:
  id: 1
  name: Packaging
  manager_id: <%= employees(:bob)['id'] %>

I’ve proven to myself on my projects that when you use a mocking framework like Mocha, you can cut your usage of fixtures down to where they aren’t nearly as painful as we’ve described in the preceding section.

Sometimes you can get away with using no fixtures at all, and that’s great. Other times, they’re convenient. The key, I believe, is to keep the number of fixtures you have to maintain down to a handful of representative cases, and stub them together as needed.

Incidentally, there are situations where fixtures are downright crucial (unless you want to create a bunch of model objects from scratch and save them to the database inside your test, which I hate doing). The one situation that comes to mind immediately is testing usages of find_by_sql in your model. Since you’re writing SQL, you definitely want to run that against a real database and make sure that it works. There’s no way of unit-testing it purely unless you parse the SQL yourself!

The bottom line: You don’t need to hate fixtures; just try to be smart about how you use them.

The Test::Unit::Assertions module (part of Ruby itself) gives you a variety of basic assertion methods that you can use in all of your Rails tests. To preserve space, the following list combines assertions with not variants under the same heading. I also left out a couple that are not relevant for Rails programming.

assert @user.valid?, "user was not valid"


deny @user.valid?, "user was valid"

assert_block "Failed because couldn't do the thing" do
  # do some processing required to do_the_thing
  do_the_thing
end

assert_empty @collection

assert_equal "passed", @status

assert_in_delta(expected, actual, 0.01, message="exceeded tolerance")

assert_include item, @collection

assert_instance_of Time, @timestamp

assert_instance_of Enumerable, @my_collection

assert_match /d{5}(-d{4})?/, "78430-9594"

assert_not_nil User.find(:first)

assert_same "foo".intern, "foo".intern

assert_raise RuntimeError, LoadError do
  raise 'Boom!!!'
end

assert_respond_to @playlist, :shuffle

flunk "REDO FROM START"

Rails adds a number of assertions that supplement the ones provided by Test::Unit.

The only ones in the list that are general purpose are assert_difference and assert_no_difference. All are covered in the following sections, with code examples and as they apply to testing specific parts of Rails.

I like to make my tests as elegant and expressive as possible. The idea of limiting each test method to one assertion is usually attributed to TDD guru Dave Astels, and has been popularized in the Rails community by Jay Fields^[11] and others.

If you are following the one-assertion guideline, then rather than a single test method that looks like this...

def test_email_address_validation
  u = users(:sam)
  u.email = "sam"
  assert ! u.valid?
  u.email = "[email protected]"
  assert u.valid?
  u.email = "[email protected]"
  assert u.valid?
  u.email = "[email protected]"
  assert u.valid?
  u.email = "sam@@colgate.com"
  assert ! u.valid?
end

you would have instead written at least five test methods, each with a better description of the behavior being tested. For convenience, I would also move the assignment of a short variable for users(:sam) up to a setup method:

def setup
  @sam = users(:sam)
end

def test_email_validation_fails_with_simple_string_name
  @sam.email = "sam"
  assert not @sam.valid?  # prefer not over ! for readability
end

def
test_email_validation_should_succeed_for_valid_email_containing_dot
  @sam.email = "[email protected]"
  assert @sam.valid?
end

... # you get the picture, I hope

The main advantage to following the guideline is to increase maintainability of your tests, but there are also other important benefits, such as

Let’s talk some more about testing the domain model of your Rails app, its ActiveRecord models.

Whenever you use a generator to create an ActiveRecord model, Rails automatically creates a skeleton unit test in the test/unit directory of your project. It looks something like this:

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

class BillableWeekTest < Test::Unit::TestCase
  fixtures :billable_weeks

  # Replace this with your real tests.
  def test_truth
    assert true
  end
end

Traditionally, a unit test limits itself to testing one public method of an object and nothing more.^[12] When we’re testing an ActiveRecord model in Rails, we usually include multiple test methods for each public method, to make sure that we verify behavior thoroughly.

Listing 17.2 contains a couple of test methods from the TimesheetTest of our recurring sample application.

 1 class TimesheetTest < Test::Unit::TestCase
 2
 3   fixtures :users
 4
 5   def test_authorized_user_may_be_associated_as_approver
 6     sheet = Timesheet.create
 7     sheet.approver = users(:approver)
 8     assert sheet.save
 9   end
10
11   def test_non_authorized_user_cannot_be_associated_as_approver
12      sheet = Timesheet.create
13      begin
14        sheet.approver = users(:joe)
15        flunk "approver assignment should have failed"
16      rescue UnauthorizedApproverException
17        # expected
18      end
29    end
20  end

As we covered earlier in the chapter, we can leverage the fixtures system to have objects ready for testing. (Line 3 invokes fixtures :users.) You can use as many fixtures as necessary, and the names are always plural. I didn’t load the timesheet fixtures because I don’t need them. A basic, newly created Timesheet instance suits my needs just fine (lines 6 and 12).

If I wanted to use even more idiomatic Ruby in this test example, I would probably refactor lines 13–18 to use assert_raises.

The implementation that determines whether a user is an authorized approver or not is hidden from view in this test. That may or may not be a bad thing in your case. I’m of the opinion that it’s a good thing. This is after all a timesheet test, not a user or authorization test. All I wanted to verify when I wrote this test case was that one assignment succeeded, and the other didn’t. The logic for authorization is not relevant in this test case.

Functional tests follow certain conventions, which most new Rails developers are introduced to when they first open up a scaffolding-generated functional test. Let’s use a functional test from an open-source bulletin board package for Rails named Beast for our main examples.^[13]

The top line is similar to a unit test in that it requires the common test_helper file. Next, the controller under test is required:

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

Normally, any errors raised during controller execution are rescued so that the appropriate error page can be displayed to the user. But during testing, you want those errors to rise all the way to the top where the test framework can register that they happened. In a great example of how useful open classes are in Ruby, the solution for our functional tests is simply to override the rescue_action method of ActionController.

require 'forums_controller'
# Re-raise errors caught by the controller.
class ForumsController; def rescue_action raise e end; end

Semicolons, which are optional line delimiters in Ruby, are used to keep the line length of the file minimal.

Next up is the opening of the functional test class itself, which by naming convention, starts with the name of the controller it is testing. If the test uses fixtures, they are usually specified on the following line:

class ForumsControllerTest < Test::Unit::TestCase
  fixtures :forums, :posts, :users

Functional tests always have a setup method like the following one. It sets three required instance variables for the test, and will be run prior to each test method invocation:

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

You can use the @request and @response objects, but additional convenience accessors for session, flash, and cookies are also provided. You can access those structures at any time in your test method, whether to set values to them or make assertions about how their state changed due to the controller action execution.

Normally, you should have at least a couple of test methods per controller action, to verify handling of happy path and error conditions. The general workflow of a functional test method is to put any necessary preconditions into place, and then call a method on the test itself (such as GET, POST, PUT, DELETE, or HEAD) corresponding to the HTTP request desired. An xhr method is also provided, which lets you simulate an XMLHttpRequest interaction, as would occur if the browser made an Ajax request.

The first parameter to the request method is a symbol corresponding to the name of the action method to be tested, followed by a hash of parameters.

The following example tests that a GET request to /forums/edit/1 is successful.

def test_should_get_edit_form
  login_as :aaron
  get :edit, :id => 1
  assert_response :success
end

The following sorts of assertions are the most common for functional tests. You may come up with your own, but remember that controllers shouldn’t be doing much more than invoking business logic on your models, and setting up an environment for the view to render properly.

def test_that_users_are_assigned_properly

  # lame assertion
  assert_not_nil assigns(:users)

  # getting better
  assert_equal 3, assigns(:users).size

  # best, check the contents of users but get a sane error on failure
  assert_equal %w(Bobby Sammy Jonathan), assigns(:users).map(&:login)

end

def test_should_get_index_successfully
  get :index
  assert_response :success
end

XML_UTF8 = "application/xml; charset=utf-8"

def test_should_get_index_with_xml
  request.env['Content-Type'] = 'application/xml'
  get :index, :format => 'xml'
  assert_response :success
  assert_equal XML_UTF8, @response.headers['Content-Type']
end

def test_get_index_should_render_index_template
  get :index
  assert_template 'index'
end

def test_accessing_protected_content_redirects_to_login
  get :protected
  assert_redirected_to :controller => "session", :action => "new"
end

def test_accessing_protected_content_redirects_to_login
  post :create ... # bad attributes

  assert_equal "Problem saving. Check form and try again.",
flash[:error]
end

assert_difference 'Article.count' do
  post :create, :article => {...}
end

assert_difference 'Article.count', -1 do
  delete :destroy, :id => ...
end

assert_difference [ Report.count', 'AuditLog.entries.size' ], +2 do
  post :create, :article => {...}
end

assert_no_difference 'Article.count' do
  post :create, :article => {...}  # invalid_attributes
end

def test_create_should_assign_a_valid_model
  post :create ... # good attributes
  assert_valid assigns(:post)
end

The first (most common) form uses the CSS selector string to select elements from the response in the context of a functional test.

The second form, which I believe is rarely used by most developers, takes an explicit instance of HTML::Node as the element parameter, and selects all matching elements starting from (and including) that element and all its children in depth-first order.

Calling assert_select inside an assert_select block will automatically run the assertion for each element selected by the enclosing assertion, as in the following examples, which have the exact same behavior:

assert_select "ol > li" do |elements|
  elements.each do |element|
    assert_select element, "li"
  end
end

# use the shorter version

assert_select "ol > li" do
  assert_select "li"
end

The assert_select method understands the set of CSS selector formats listed in Table 17.1. Combine them to identify one or elements for assertion.

assert_select "html:root > head > title", "Login"

assert_select 'LI.sponsored ~ LI:not(.sponsored)'

assert_select 'DIV#header + DIV#content'

assert_select('SELECT OPTION:first-of-type','')

<SELECT id="filter">
  <OPTION>None</OPTION>
  <OPTION>Businesses</OPTION>
  <OPTION>People</OPTION>
</SELECT>

assert_select('SELECT#filter option:nth-of-type(1)',
'None')
assert_select('SELECT#filter option:nth-of-type(2)',
'Businesses')
assert_select('SELECT#filter option:nth-of-type(3)',
'People')

assert_select('HEAD SCRIPT[src]:only-of-type')

Sometimes you want to use a substitution value, instead of matching for the existence or count of the CSS selector string defined. In that case, you can use the ? character as a placeholder. Works with class names (.?, classname), identifier attributes (#?, id), and regular attributes ([attr=?], string, or regexp).

assert_select "form[action=?]", url_for(:action=>"login") do
  assert_select "input[type=text][name=username]"
  assert_select "input[type=password][name=password]"
end

The equality parameter is optional and can be one of the values listed in Table 17.2. The default value is true, which means that at least one element was found matching the CSS selector. If you wish to supply only one criterion for the matched elements, use the singular form. Otherwise, pass the criteria as a hash.

Variants of assert_select_rjs are used in functional tests to check RJS-style manipulation of the view by your controllers.

# Check that RJS inserts or updates a list with four items.
assert_select_rjs 'my_list' do
  assert_select "ol > li", 4
end

Rounding out the assert_select code are methods for checking e-mail and encoded HTML, as well a the css_select method, which is useful in conjunction with the version of the assert_select that takes an HTML node as its first parameter.

Rails provides a set of assertions for use in functional tests that allow you to check that your routing file is configured as you expect it to be.

assert_generates("/items", :controller => "items",
                 :action => "index")

assert_generates("/items/list", :controller => "items",
                 :action => "list")

assert_generates("/items/list/1", :controller => "items",
                 :action => "list", :id => "1")

# check the default action
assert_recognizes({:controller => 'items', :action => 'index'},
'items')

# check a specific action
assert_recognizes({:controller => 'items', :action => 'list'},
'items/list')

# check an action with a parameter
assert_recognizes({:controller => 'items', :action => 'list',
 :id => '1'}, 'items/list/1')

# assert that POSTing to /items will call create on ItemsController
assert_recognizes({:controller => 'items', :action => 'create'},
                  {:path => 'items', :method => :post})

# assert that a path of '/items/list/1?view=print' returns correct
options
assert_recognizes({:controller => 'items', :action => 'list',
                   :id => '1', :view => 'print'},
                 'items/list/1', { :view => "print" })

Integration tests are kept as files in the test/integration directory. They are executed via the rake target test:integration, or just like other Rails tests, by invoking the file directly with the Ruby interpreter.

You don’t have to write the skeleton code for an integration test yourself, since a generator is provided. Give the generator an integration test name as its argument in CamelCase or under_score format.

$ script/generate integration_test user_groups
      exists  test/integration/
      create  test/integration/ user_groups_test.rb

The generator will create an integration test template ready for editing, such as the following:

require "#{File.dirname(__FILE__)}/../test_helper"

  class UserGroupsTest < ActionController::IntegrationTest
    # fixtures :your, :models

    # Replace this with your real tests.
    def test_truth
      assert true
    end
  end

end

So far the process is very similar to how we write tests for models and controllers, but in order to proceed, we have to make some decisions on how we want to implement the feature to be tested. In this sense, writing the integration test prior to implementation of a feature serves as a design and specification tool. Before going any further with our example, let’s take a quick look at the API methods available for coding our integration tests.

The get and post methods take a string path as their first argument and request parameters as the second argument, as a hash. To use the familiar controller/action hash for the first parameter instead of a literal URL string, use the url_for method.

The follow_redirect! method instructs your test to follow any redirect initiated by the last request. The status method returns the HTTP status code of the last request. When asserting a redirect, the redirect? method asserts that the status code of the last request is equal to 300.

ActionController::Assertions::ResponseAssertions is a module containing the assertions that we use in our integration tests. Remember that all assertion methods in Rails have an optional message parameter displayed when the assertion fails during a test run.

An integration Session instance represents a set of requests and responses performed sequentially by some virtual user. Because you can instantiate multiple sessions and run them side by side, you can also mimic (to some limited extent) multiple simultaneous users interacting with your system.

Typically, you will instantiate a new session using IntegrationTest# open_session, rather than instantiating Integration::Session directly.

As a Rails developer working on a given user story or feature, having an automated acceptance test keeping me focused on the task at hand helps keep my productivity at optimal levels. The same principles of test-driven development (TDD) apply, just at a higher conceptual level than unit tests. It’s so easy to do most stuff in Rails that you might find it hard to limit yourself to working on a particular task at a time, and that’s a dangerous habit to get into.

Also, experience has shown that most Rails applications (and Web 2.0 apps in general) are data and UI-heavy. They simply don’t have a lot of business logic driving a critical need for extensive unit tests. However, you can’t just leave parts of your application without test coverage—in an interpreted language like Ruby, that’s a recipe for disaster.

That’s where automated acceptance tests come in: Encode the acceptance criteria for a given user story or feature prior to implementing it. Requirements not clear? Seek clarity. Not sure how your application’s models and controllers need to be designed? Go for it. Make some initial decisions and use those as the basis for your test.

Prior to working on the implementation, your acceptance test will fail near its beginning. As you code the implementation, run the acceptance test over and over again and watch the red bars turn into green bars. Once the whole test is green, you’re done! In the process you’ve created an automated regression suite that yields a multitude of benefits down the road.

Luckily, since so many Rails developers are fans of Agile, there are strong options available that let you quickly and easily create acceptance test suites for your own Rails projects.

This chapter covers the most significant options available, starting with an open-source product called Selenium on Rails, continuing with a look at the acceptance-testing capabilities built into Rails itself, and finishing off with descriptions of other useful acceptance-testing tools for Rails.

A Selenium script consists of a series of commands that manipulate and verify the state of the web browser. There are three kinds of Selenium commands: actions, accessors, and assertions. In the beginning, you will mostly be using actions and assertions. Most commands take two parameters: target and value.

Some commands wait for a condition to become true, which allows Selenium to test page transitions and Ajax functionality. Such commands will succeed immediately if the condition is already true, but they will fail and halt the test if a timeout value is exceeded before the condition does become true.

Selenium on Rails^[21] is the name of the Selenium product crafted specifically for Rails developers and is distributed as a Rails plugin. It has been designed to work seamlessly with the Rails testing environment and fixtures.

It’s easy to install Selenium on Rails and get started.

If your installation and setup succeeded, you see the Selenium Test Runner in your browser. You should also know that Selenium tests can be run from the command line and integrated into an automated suite of tests, but for demonstration purposes we will use the built-in web interface to execute our tests.

setup
open '/'
assert_title 'Ruby on Rails: Welcome aboard'

Selenium on Rails scripts are written in Ruby, using an API that the authors have nicknamed RSelenese. It is a direct port of the Selenium command language, except that commands are Ruby-fied—lowercase and underscore-delimited rather than CamelCase. The Selenium on Rails engine looks for RSelenese tests in the test/selenium directory tree in files ending with the .rsel extension.

Selenium on Rails also understands HTML-formatted scripts, and will execute any that it finds in files with an .sel extension. However, in practice you are better off keeping as much of your application written in Ruby as possible, and tests are not necessarily an exception to that rule. Also, since RSelenese is just plain Ruby, you can use normal language constructs such as conditionals and loops for extra expressive power whenever needed.

The example shows use of an iterator in RSelenese to successively open 10 pages:

(1..10).each do |num|

  open :controller => 'user', :action => 'list', :page => num
end

#_login.rsel
open '/login'
type 'name', 'john'
type 'password', 'password'
click 'submit'

include_partial 'login'

#_login.rsel with params
open '/login'
type 'name', name
type 'password', password
click 'submit'

include_partial 'login', :name => 'jane', :password => 'foo'