Copyright (c) 2007 Tom Preston-Werner

=FixtureScenarios

This plugin allows you to create "scenarios" which are collections of fixtures
and ruby files that represent a context against which you can run tests.

==Disclaimer

This software is in Beta.
Send feedback to tom at rubyisawesome dot com or find me (mojombo) on irc.freenode.net.

==Installation

FixtureScenarios should work on both 1.1.6 and edge rails.
Currently you must install this plugin from the subversion repository

  script/plugin install http://fixture-scenarios.googlecode.com/svn/trunk/fixture_scenarios

==WARNING

Because this plugin clears out fixture data between your test classes, you may
see some of your tests fail after installation. If this occurs, look at your
tests to see if you didn't actually load a required fixture for that test
class. If you forgot to add it and your tests passed anyway (because of
fixture contamination), just add the missing fixture(s) and you'll be good
to go.

==The Basics

To create a scenario, simply create a subdirectory under test/fixtures in your
Rails app. The name of the subdirectory will be the name of the scenario.
Inside this new directory, you can place fixture files, and/or Ruby files.

  [RAILS_ROOT]
  +-test/
    +-fixtures/
      +-brand_new_user/
        +-users.yml
  
  # in users.yml
  borges:
    id: 1
    name: Jorge Luis Borges
    active: 1

To load the scenario for testing, you simply use the +scenario+ method instead
of the normal +fixtures+ method.

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

  class UserTest < Test::Unit::TestCase
    scenario :brand_new_user

    def test_should_be_active
      assert users(:borges).active?
    end
  end

All of the fixtures placed into your scenario directory will be loaded when
you invoke the +scenario+ method with your scenario name. In addition, any
Ruby files you place in the scenario directory will be run after the fixtures.
You can use a Ruby file to create non-database model instances, set up
relationships between fixtures (instead of creating fixtures for the join
tables), or replace fixtures entirely by creating your database items with
Ruby code.

In this example, +scenario+ will actually load all fixtures from the fixture
directory *and* your scenario directory. This is useful if you have some
fixtures (such as lookup data) that you'd like to have in most of your
scenarios. To prevent the loading of fixtures in the fixtures root directory,
use the <tt>:root</tt> option. This can be very useful if you still have tests
using regular fixtures.

  scenario :brand_new_user, :root => false
  
If you've just started FixtureScenarios on an existing project, adding
:root => false to every scenario call will become tedious, so you can set
the option globally in your test_helper.rb (inside the Test::Unit::TestCase
class) like so:

  self.scenarios_load_root_fixtures = false

To keep things DRY in your scenarios, you can extend or layer scenarios on top
of each other. Following with our example, to create an "experienced user"
scenario, we could create another subdirectory under the existing
"brand_new_user" that would contain fixture/Ruby files that add upon the
"brand new user" scenario.

  [RAILS_ROOT]
  +-test/
    +-fixtures/
      +-brand_new_user/
        +-users.yml
        +-experienced_user/
          +-articles.yml

Now when you load the +experienced_user+ scenario, it will load any
fixture/Ruby files in "fixtures", then in "brand_new_user", then in
"experienced_user"! Building off of your existing scenarios keeps data
redundancy to a minimum, and makes it easy to change data for multiple
scenarios simultaneously.

==Testing your scenarios

Scenarios represent your assumptions about a given context. If these
assumptions are wrong, your tests will be inaccurate. Your scenarios should be
unit tested along with the rest of your application. This plugin allows you to
place scenario tests in a "scenario" directory under your "test" directory.

  [RAILS_ROOT]
  +-test/
    +-scenario/
      +-brand_new_user_test.rb
      +-experienced_user_test.rb
  
You can run these tests with rake.

  rake test:scenarios  # run just scenario tests
  rake                 # run unit, functional, integration, and scenario tests

Scenario tests will protect you from accidentally changing your assumptions in
a dangerous or transparent way when modifying existing scenarios.