These are the essential assertions you’ll be using in your test methods:

Writing custom assertions and helper methods can keep your tests readable, small, and DRY. The place to keep those custom assertions and helper methods is in test/test_helper.rb, loaded before any test is run.

Here’s an example of adding a custom assertion for testing the size of collections. Add this to test/test_helper.rb:

class ActiveSupport::TestCase
  def assert_size(collection, size, message = nil)
    message ||= "expected #{collection.inspect} to have #{size} elements but instead had #{collection.size}"
    assert_block message do
      collection.size == size
    end
  end
end

With that code in place, the assert_size method is now available in all our unit, functional, and integration tests:

require 'test_helper'
class ArrayTest < ActiveSupport::TestCase
  test "array length" do
    assert_size [1,2,3], 3
  end
  
  test "Article.recent_articles should only return 5 records" do
    assert_size Article.recent_articles, 5
  end
end

Preparing and populating model data in each test is difficult to refactor, prone to mistakes, and overall, a giant pain. Rails’ built-in answer is the concept of fixtures – files that hold model data in a human-readable format called YAML. When these fixtures are used in a test, out come ActiveRecord objects from the test database, just like if we had generated the objects manually.

Before each test is run, the test database is emptied, then loaded with data defined in each model’s respective fixture.

Each record is defined using a sensible name, and the attributes you wish to load into the database.

An example User model fixture (found in test/fixtures/users.yml) where two users, admin and bob, are defined looks like this:

admin:
  login: admin
  password: secret
  adminstrator: true

bob:
  login: bobby
  password: password

Note that any attributes not provides in the fixture will use the defaults defined in the database schema.

require 'test_helper'

class UserTest < ActiveSupport::TestCase
  
  test "adminstrators should be able to delete articles" do
    assert users(:admin).delete_article( articles(:ruby_wins) )
  end
  
  test "regular users should not be able to delete articles" do
    assert !users(:bob).delete_article( articles(:ruby_wins) )
  end
  
end

test "all users should have a login" do
  user = users(:bob)
  user.login = nil
  assert !user.valid?

  user.login = "validLoginName"
  assert user.valid?
end

bob:
  id: 2
  login: bobby
  password: password

ruby_wins:
  id: 3
  author_id: 2
  title: World's only remaining Java programmer finally learns Ruby

bob:
  login: bobby
  password: password

the_final_countdown:
  author: bob
  title: World's ultimate heroes all clash in the most epic battle ever.

ActiveRecord::Fixtures.identify("bob")                 #=> 902541635
ActiveRecord::Fixtures.identify("the_final_countdown") #=> 1020415498
ActiveRecord::Fixtures.identify("abcdefg")             #=> 824863398

Hidden away in functional tests, view testing centers around a select few assertions that check to see if your templates have the HTML or CSS you’re looking for:

As a general piece of advice with regard to testing your view code (to be taken with a grain of salt), it’s a good idea to assert the presence of only the really important; checking for the non-essentials (e.g. asserting an element’s colour is red) can slow development down when your visual style changes.

View helper tests look just like model unit tests, but inherit from ActionView::TestCase and live in test/unit/helpers.

Here’s a view helper:

module ArticlesHelper
  def author_byline(article)
    "This fine article penned by #{article.author.login}"
  end
end

and here’s its matching test:

require 'test_helper'

class ArticlesHelperTest < ActionView::TestCase
  def test_author_byline
    user = User.create(:login => 'Wilfred Owen')
    article = user.articles.create
    
    assert_equal 'This fine article penned by Wilfred Owen', author_byline(article)
  end
end

Since the Rails framework allows you to test anything and everything in your application, it shouldn't be surprising that you can also test your application's routes. Learning to test your routes will allow you to better understand how the routing system works. Additionally, writing tests to generate and verify routes is a way to design your application's routes without having to make HTTP requests to your application over and over again. For complete coverage of routing in your application you can review the Chapter 6, Routing section.

There are three helper methods provided by Rails for testing your routes. These helpers are available in your Rails functional tests. The following examples all assume that the following routes are defined in the application's config/routes.rb file:

controller :articles do
  get 'articles/:id', :to => :show
  put 'articles/:id', :to => :update
end

Just like the test helpers that come with Test::Unit, all of the routing helpers take a final argument named message that allows you to set a custom failure message when the assertion fails.

Unlike unit and functional tests, integration tests are not created automatically when you generate models and controllers. They are too tightly coupled to your application's individual workflow for Rails to be able to guess your needs. You can generate an integration test with the generate integration_test command:

$ rails generate integration_test Articles

A basic integration test looks a lot like a functional test, and uses the familar get, post, put, and delete HTTP methods to simulate the requests that would be created by a web browser. All the assertions you find in unit and functional tests are available for your testing needs, but Rails provides a few integration-specific helpers:

Integration tests look an awful lot like several functional tests put together. Here's a integration test that tests our entire article workflow, from sign-in, through creation, to deletion.

require 'test_helper'

class ArticlesTest < ActionController::IntegrationTest
  
  test "articles workflow" do
    alice = users(:alice)
    
    # login as alice
    post "/session", :user => {:login => alice.login,
                               :password => alice.password}
    follow_redirect!
    assert_response :success
    assert_equal "/articles", path
    
    # create an article
    post "/articles", :article => {:title => 'Brand new article'}
    assert_redirected_to "/articles"
    follow_redirect!
    assert_response :success
    
    # view the article
    article = alice.articles.first
    get "/articles/#{article.id}"
    assert_response :success
    
    # delete the article
    delete "/articles/#{article.id}"
    assert_redirected_to "/articles"
    follow_redirect!
    assert_response :success
    
    # expect 404 when trying to view a deleted article
    get "/articles/#{article.id}"
    assert_response :missing
  end
  
end

The interaction of multiple users with an application can get very complicated, and is often the source of hidden bugs. Testing for these bugs by juggling multiple browsers is clumsy and difficult. Thankfully, integration tests are much more flexible and can save us from these elusive bugs by allowing for multiple simultaneous sessions to be played with during the test.

Integration tests will automatically create a default session for you, but you can use the open_session method to create as many sessions as you need. Each session is extended with the full set of assertions and test helpers, so you can use helpers like assert_response and follow_redirect! and Rails will automatically use the appropriate response.

This example uses two sessions to prove that users may only delete their own posts:

require 'test_helper'

class ArticleSafetyTest < ActionController::IntegrationTest
  
  test "article safety" do
    # alice logs in
    alice = open_session
    alice.post "/session", :user => {
      :login => users(:alice).login,
      :password => users(:alice).password
    }
    alice.follow_redirect!
    alice.assert_response :success
    alice.assert_equal "/articles", alice.path
    
    # bob logs in
    bob = open_session
    bob.post "/session", :user => {
      :login => users(:bob).login,
      :password => users(:bob).password
    }
    bob.follow_redirect!
    bob.assert_response :success
    bob.assert_equal "/articles", bob.path
    
    # alice creates an article
    alice.post "/articles", :article => {
      :title => 'Brand new article'
    }
    article = alice.assigns(:article)
    alice.follow_redirect!
    alice.assert_response :success
    alice.assert_equal "/articles", alice.path
    
    # bob can't delete alice's article
    bob.delete "/articles/#{article.id}"
    bob.assert_response :not_found
    
    # alice can delete her article
    alice.delete "/articles/#{article.id}"
    alice.follow_redirect!
    alice.assert_response :success
    alice.assert_equal "/articles", alice.path
  end
  
end

Integration testing for complex interactions like those involving multiple users can get very verbose. Thankfully, we can decorate our sessions with custom helpers tailored to our application. With this technique, you can DRY up your tests while building a powerful and easy to read testing DSL for your app.

The first step is to define a module in test/test_helper.rb to encapsulate your reusable helpers and assertions. This example encapsulates three common actions in our app: logging in, viewing a specific article, and creating a new article:

module IntegrationHelper
  def login(name, password)
    user = users(name)
    post "/session", :user => {
      :login => name,
      :password => password
    }
    follow_redirect!
    assert_response :success
    assert_equal "/articles", path
  end
  
  def get_article(article)
    get "/articles/#{article.to_param}"
    assert_response :success
  end
  
  def post_article(attributes = {})
    post "/articles", :article => attributes
    article = assigns(:article)
    follow_redirect!
    assert_response :success
    assert_equal "/articles", path
    article
  end
end

The next step on our quest for DRY integration tests is create a helper so we can easily create new sessions. This helper loads the user from the users fixture, creates a new session (using the alternative block syntax), extends the session with our custom helpers, and finally logs in to the app, allowing us to log in new users with one simple, readable line of code:

def login_as(name)
  user = users(name)
  open_session do |session|
    session.extend IntegrationHelper
    session.login(user.login, user.password)
  end
end

With all the helpers finally in place, our multi-user integration tests are a thing of beauty—easy to read and even easier to write.

test "multi-user article posting" do
  # alice & bob log in
  alice = login_as(:alice)
  bob = login_as(:bob)
  
  # alice & bob create a articles
  alice_article = alice.post_article({
    :title => 'Alice is awesome'
  })
  bob_article = bob.post_article({
    :title => "Bob's the best"
  })
  
  # alice & bob can view each others articles
  alice.get_article(alice_article)
  alice.get_article(bob_article)
  
  bob.get_article(bob_article)
  bob.get_article(alice_article)
end

We’ve boiled down this complex, multi-user interaction into a concise story that tests the entire Rails stack—from router to database. These techniques allow you to build rock-solid apps without creating an impenetrable snarl of testing code.

This code posts a link to our twitter account every time we create a new article. Great marketing, but we can't junk up our Twitter stream every time we run our tests.

after_create :post_to_twitter
def post_to_twitter
  user = 'rubynews'
  pass = 'p@ssw*rd'
  msg  = "Checkout our new article, #{title} http://rubynews.host/#{stub}"

  Tweeter.update(user, pass, msg)
end

With Mocha, we can start to write a test that will intercept calls to Tweeter.update method, and prevent our code from actually contacting Twitter.

test "posts to twitter after create" do
  Tweeter.stubs(:update)  # do not actually run the update method
  Article.create(:title => 'Top 500 Ruby Gems')
end

Unfortunately, this code isn't actually testing anything. Mocha lets us define assertions in the form of expectations.

test "posts to twitter after create" do
  Tweeter.expects(:update)  # do not actually run the update method
  Article.create(:title => 'Top 500 Ruby Gems')
end

We can improve the test by defining the paramaters that Tweeter.update expects to be called with:

test "posts to twitter after create" do
  Tweeter.expects(:update).with('rubynews', 'p@ssw*rd', "Checkout our new article, Top 500 Ruby Gems http://rubynews.host/top500")
  Article.create(:title => 'Top 500 Ruby Gems', :stub => 'top500')
end

Sometimes you need to stub out entire objects, instead of individual methods. Consider this method on the Article model which looks for tweets that link to our article.

def related_tweets
  # find tweets that link to this article
  tweets = Tweeter.search("http://rubynews.host/#{stub}")

  # only show other users' tweets
  tweets.reject do |tweet|
    tweet.from_user == 'rubynews'
  end
end

When writing our test, we first need to stub out the search method, so that we don't actually contact twitter.

test "fetchs related tweets" do
  query   = 'http://rubynews.host/articles/top500'
  results = []
  Tweeter.expects(:search).with(query).returns(results)
  assert_equal results, article(:rubynews).related_tweets
end

This is a good start, but by returning an empty array, we're not actually testing the code that filters by username. Instead, we can return stub objects.

test "fetchs related tweets" do
  our_tweet        = stub(:from_user => 'rubynews')
  other_tweet      = stub(:from_user => 'dhh')
  raw_results      = [our_tweet, other_tweet]
  filtered_results = [other_tweet]
  Tweeter.expects(:search).returns(raw_results)
  assert_equal filtered_results, article(:rubynews).related_tweets
end

The stub method takes a hash, each key becomes a method, and each value is its return value. Mocha also lets you set up mocks. Mocks are just like stubs, except they set up an expectation on each method. Our code with mocks ends up looking like:

test "fetchs related tweets" do
  our_tweet        = mock(:from_user => 'rubynews')
  other_tweet      = mock(:from_user => 'dhh')
  raw_results      = [our_tweet, other_tweet]
  filtered_results = [other_tweet]
  Tweeter.expects(:search).returns(raw_results)
  assert_equal filtered_results, articles(:rubynews).related_tweets
end

The only difference between these two versions is that the this one has assertions that will fail if the username method is never called on the mocks.

To run all tests, run

$ rake test

Individual test suite files can also be run manually:

$ ruby -I test test/unit/a_model_test.rb

$ rake db:test:clone

Related rake tasks can be discovered with $ rake -T test:

$ rake -T test
rake db:test:clone            # Recreate the test database from the current environment's database schema
rake db:test:clone_structure  # Recreate the test databases from the development structure
rake db:test:load             # Recreate the test database from the current schema.rb
rake db:test:prepare          # Check for pending migrations and load the test schema
rake db:test:purge            # Empty the test database
rake test                     # Run all unit, functional and integration tests
rake test:benchmark           # Run tests for benchmarktest:prepare / Benchmark the performance tests
rake test:functionals         # Run tests for functionalstest:prepare / Run the functional tests in test/functional
rake test:integration         # Run tests for integrationtest:prepare / Run the integration tests in test/integration
rake test:plugins             # Run tests for pluginsenvironment / Run the plugin tests in vendor/plugins/*/**/test (or specify with PLUGIN=name)
rake test:profile             # Run tests for profiletest:prepare / Profile the performance tests
rake test:recent              # Run tests for recenttest:prepare / Test recent changes
rake test:uncommitted         # Run tests for uncommittedtest:prepare / Test changes since last checkin (only Subversion and Git)
rake test:units               # Run tests for unitstest:prepare / Run the unit tests in test/unit

Running tests in a continuous feedback loop where the tests re-run themselves upon modification of test or application code can be accomplished by using the autotest -f command, part of Ryan Davis’ zentest gem. This facilitates staying in that zen-like state of flow, where time flies around you, and you’re rarely stuck on a hard-to-pin-down bug, or wondering what next to do.

The testing environment configuration (which lives in config/environments/test.rb) makes things behave a little differently than development or production:

While it also uses its own database, the testing environment has each test run in its own transaction. This way, each test has a fresh version of the database and its loaded fixture data.

The default testing environment also sets config.action_mailer.delivery_method to :test, which changes the way ActionMailer behaves; email is instead delivered to ActionMailer::Base.deliveries (an Array). See more about this in the ActionMailer chapter.

The testing environment also disables caching and a few other little things. Be sure to skim through the well-documented config/environments/test.rb file for more details.