README

Rails Scenarios Plugin

Who hasn‘t experienced the pain of dozens of YAML files filled with hundreds of inter-related data structures? When do you look at People of an Organization and not have to look at the organization_id, open the organizations.yml file, and search for ‘id: X’?

In a nutshell, scenarios are a drop in replacement for YAML fixtures. Instead of encouraging you to create a mindless amount of raw data in the form of YAML, scenarios encourage you to create code that populates your tables with the appropriate records.

How is it different from other solutions? A few things:

 * It continues to provide a fundamental, fast insertion method using attributes
   written directly to a table. This is the
   Scenarios::TableMethods#create_record method.

 * It allows you to create records using validations if you prefer, or if it's
   important to have all your callbacks be invoked. See
   Scenarios::TableMethods#create_model. Both create_record and create_model
   allow you to name your instances for retrieval by the instance and id reader
   methods (more below).

 * Nothing stops you from simply invoking YouModel.create!, etc. We'll still
   keep track of the tables the scenario modifies and clean things up afterward.

 * It allows you to create re-usable scenarios as classes. These classes are
   like any other class - they may include modules, subclass, and be composed of
   other scenarios. See Scenarios::Base.uses. This also means that you can load
   any scenario into any Rails environment. That's what the 'rake
   db:scenario:load' task is good for (more below). Very handy for re-using all
   that test support code to create populated demos!

Quick Start

Since Scenarios is a Rails plugin at this time, you should get it installed, using the appropriate method (script/plugin, svn, piston) into your vendor/plugins directory. Once you have this, in your spec_helper.rb or test_helper.rb, add the following line after the spec requires:

  require 'scenarios'

The Scenarios you write should be placed in the spec/scenarios directory of your Rails project if you‘re using RSpec, or the test/scenarios directory of your Rails project if you‘re using Test::Unit. Scenario file names always end in "_scenario.rb" and classes end in "Scenario".

A simple scenario looks like this:

  # in spec/scenarios/users_scenario.rb or test/scenarios/users_scenario.rb
  class UsersScenario < Scenario::Base
    def load
      create_record :user, :john, :name => 'John', :password => 'doodaht'
      create_record :user, :cindy, :name => 'Cindy', :password => 'whoot!'
    end
  end

In the example above, I‘m using the create_record instance method to create two users: John and Cindy. Notice the calls to create_record. There are three parameters. The first is the singular name of the table to insert the record into, the second is the symbolic name of the record (more on that later), and the third is a hash of the attributes of the record.

To use the UsersScenario in a description, you should declare it using the scenario method. Here it is within a spec file (RSpec):

  # in spec/models/user_spec.rb
  describe User do
    scenario :users

    it "should allow me to do something with John" do
      user = users(:john)
      user.password.should == "doodaht"
    end
  end

and here it is within a standard Test::Unit test:

  # in test/unit/user_test.rb
  class UserTest < Test::Unit::TestCase

    scenario :users

    def test_do_something
      user = users(:john)
      assert_equal "doodaht", user.password
    end
  end

Notice that it is easy to load an instance of a model object using its symbolic name with a reader method, similar to that of Rails’ fixtures. In the example above, I loaded John with the reader method users and the symbolic name :john. (Remember that in the Users scenario I declared that John should be accessible through the symbolic name :john.)

I could also have retrieved an array of user fixtures by passing in multiple symbolic names to the reader method:

  # in spec/models/user_spec.rb
  describe User do
    scenario :users

    it "should allow me to get all admins" do
      admins = users(:john, :ryan)
      User.admins.should eql(admins)
    end
  end

Composition

In real life your scenarios will probably grow quite complicated. The scenarios plugin allows you to deal with this complexity through composition.

Here‘s a simple example:

  # in spec/scenarios/posts_scenario.rb or test/scenarios/posts_scenario.rb
  class PostsScenario < Scenario::Base
    def load
      create_record :post, :first, :title => "First Post"
      create_record :post, :second, :title => "Second Post"
    end
  end

  # in spec/scenarios/comments_scenario.rb or test/scenarios/comments_scenario.rb
  class CommentsScenario < Scenario::Base
    uses :posts

    def load
      create_record :comment, :first, :body => "Nice post!", :post_id => post_id(:first)
      create_record :comment, :second, :body => "I like it.", :post_id => post_id(:first)
      create_record :comment, :third, :body => "I thoroughly disagree.", :post_id => post_id(:second)
    end
  end

In the example above, the CommentsScenario declares that it depends on the Posts scenario with the uses class method. This means that if you load the CommentsScenario, the PostsScenario will be loaded first and the CommentsScenario will have access to all the data loaded by the PostsScenario in its own load method. Note that inside the load method I‘m using another form of reader methed which simply gives you the id for a symbolic name (in this case: post_id). This is most useful for making associations, as done here with comments and posts.

Helper Methods

Another way of simplifying your scenarios and specs/tests is through helper methods. The Scenarios plugin provides a handy way to declare helper methods that are accessible from inside the scenario and also from inside related RSpec/Test::Unit examples:

  # in spec/scenarios/users_scenario.rb or test/scenarios/users_scenario.rb
  class UsersScenario < Scenario::Base
    def load
      create_user :name => "John"
    end

    helpers do
      def create_user(attributes={})
        create_record :user, attributes[:name].downcase.intern, attributes
      end
      def login_as(user)
        @request.session[:user_id] = user.id
      end
    end
  end

Helper methods declared inside the helpers block are mixed into the scenario when it is instantiated and mixed into examples that declare that they are using the scenario. Also, in the case where one scenario uses another, the using scenario will have the helper methods of the used scenario.

  # in spec/controllers/projects_controller_spec.rb
  describe "Projects screen" do
    scenario :users

    it "should show active projects" do
      login_as(users(:john))
      get :projects
      @response.should have_tag('#active_projects')
    end
  end

  # in test/functional/projects_controller_test.rb
  class PeopleControllerTest < Test::Unit::TestCase
    scenario :users

    def test_index
      login_as(users(:john))
      get :projects
      assert_tag('#active_projects')
    end
  end

Notice that within my specs/tests I have access to the login_as helper method declared inside the helpers block of the UsersScenario. Scenario helpers are a great way to share helper methods between specs/tests that use a specific scenario.

Built-in Scenario

There is a scenario named ‘blank’ that comes with the plugin. This scenario is useful when you want to express, and guarantee, that the database is empty. It works by using your db/schema.rb, so if the table isn‘t created in there, it won‘t be cleaned up.

Scenario.load_paths is an array of the locations to look for scenario definitions. The built-in scenarios directory is consulted last, so if you‘d like to re-define, for instance, the ‘blank’ scenario, simply create ‘blank_scenario.rb’ in your spec/scenarios or test/scenarios directory.

Load Rake Task

The Scenarios plugin provides a single Rake task, db:scenario:load, which you may use in a fashion similar to Rails fixtures’ db:fixtures:load.

  rake db:scenario:load SCENARIO=comments

When invoked, this task will populate the development database with the named scenario.

If you do not specify SCENARIO, the task will expect to find a default scenario (a file ‘default_scenario.rb’ having DefaultScenario defined in it). It is our practice to have it such that this scenario uses a number of our other scenarios, thereby:

• encouraging us to use test data that looks good in the running development application
• allowing us to troubleshoot failing tests in the running development application

More Information

For more information, be sure to look through the documentation over at RubyForge:

• faithfulcode.rubyforge.org/docs/scenarios

You might also enjoy taking a look at the specs for the plugin and the example scenarios:

• faithfulcode.rubyforge.org/svn/plugins/trunk/scenarios/spec/scenarios_spec.rb
• faithfulcode.rubyforge.org/svn/plugins/trunk/scenarios/spec/scenarios

Browse the complete source code:

• faithfulcode.rubyforge.org/svn/plugins/trunk/scenarios

Running Tests

You should be able to simply run rake. Notice in testing/environment.rb the revisions under which this project will work. If you intend to test against HEAD, you will need to delete the directory testing/tmp/trunk/HEAD. At some point, it would be nice to have the script track the revision of HEAD that we have, and update the directory automatically.

License

The Scenarios plugin is released under the MIT-License and is Copyright (c) 2007, Adam Williams and John W. Long. Special thanks to Chris Redinger for his part in helping us get this plugin ready for the public.