gregwebs/nested_scenarios forked from josevalim/nested_scenarios

NestedScenarios
License: MIT
Version: 0.2.2
Description
-----------
This plugin is based on FixtureScenarios and FixtureScenarioBuilder.
It includes both worlds in just one plugin with some fixes, new features
and Rails 2.2 and 2.3 support (check what's new session bellow).
You can check them at:
  NestedScenarios
    Info: https://josevalim.blogspot.com/
    Git : https://github.com/josevalim/nested_scenarios
  FixtureScenariosBuilder
    Info: https://errtheblog.com/post/7708
    SVN : svn://errtheblog.com/svn/plugins/fixture_scenarios_builder
  FixtureScenarios
    Info: https://code.google.com/p/fixture-scenarios/
    SVN : https://fixture-scenarios.googlecode.com/svn/trunk/fixture_scenarios
Install
-------
Install Nested Scenarios is very easy. If you are using Rails 2.3.0, just do:
   gem sources -a https://gems.github.com
   sudo gem install josevalim-nested_scenarios
If you want it as plugin, just do:
   script/plugin install git://github.com/josevalim/nested_scenarios.git
If you are running on Rails 2.2.x, you should use Nested Scenarios v0.1.1:
    cd myapp
    git clone git://github.com/josevalim/nested_scenarios.git
    cd vendor/plugins/nested_scenarios
    git checkout v0.1.1
    rm -rf ./.git
Why?
----
You may, from time to time, wish to build your fixtures entirely in Ruby.
Doing so has its advantages, such as automatically created join tables
and default attributes. YAML files, however, bring with them some real
nice features in Rails which are difficult to abandon: transactional fixtures, 
table_name(:key) helpers and auto-clearing between tests. This plugin allow to
get the best of both worlds.
What's new?
-----------
FixtureScenario is totally rewritten: it's lighter, smaller and faster.
FixtureScenarioBuilder was changed to expose some methods as API and it does
not try to guess anymore when you should rebuild your scenarios. You have to
call it explicitly using rake db:scenario:build.
Finally Rails 2.2 support was also added.
Usage
-----
Using the +scenario+ method within <tt>scenarios.rb</tt> file,
NestedScenarios can create your YAML fixtures automatically at run time.
Any file inside the +fixture_path+ called scenario.rb or scenarios.rb
is loaded to generating scenarios:
  [RAILS_ROOT]
  +-test/
    +-fixtures/
      +-scenarios.rb
Or: 
  [RAILS_ROOT]
  +-spec/
    +-fixtures/
      +-models/
        +-scenarios.rb
      +-controllers/
        +-scenarios.rb
      +-helpers/
        +-scenarios.rb
Now build your scenarios in those files, wrapping scenarios in the 
+scenario+ method and providing it with the name of your scenario.
A brief example of a complete <tt>scenarios.rb</tt> file:
  scenario :banned_users do
    %w( Tom Chris Kevin ).each_with_index do |user, index|
      User.create(:name => user, :banned => index.odd?)
    end
  end
This will create a file for us:
  [RAILS_ROOT]
  +-test/
    +-fixtures/
      +-banned_users/
        +-users.yml
Assuming that banned is a boolean field, our generated <tt>users.yml</tt>
file will look something like this:
  chris: 
    name: Chris
    id: "2"
    banned: "1"
    updated_at: 2007-05-09 09:08:04
    created_at: 2007-05-09 09:08:04
  kevin: 
    name: Kevin
    id: "3"
    banned: "0"
    updated_at: 2007-05-09 09:08:04
    created_at: 2007-05-09 09:08:04
  tom: 
    name: Tom
    id: "1"
    banned: "0"
    updated_at: 2007-05-09 09:08:04
    created_at: 2007-05-09 09:08:04
Notice how the keys correspond to the user names. You can register fields that
can be used as fixtures names by:
  NestedScenarios.record_name_fields += [ "nickname" ]
You can also assign your records to instance variables, then call +names_from_ivars!+
at the conclusion of your +scenario+ block.
  scenario :foo do
    @small_red_widget = Widget.create(:size => 'small', :color => 'red')
    @big_blue_widget  = Widget.create(:size => 'big',   :color => 'blue')
    names_from_ivars!
  end
The above produces the following YAML:
  small_red_widget:
    size: small
    color: red
    updated_at: 2007-12-27 10:09:05
    created_at: 2007-12-27 10:09:05
  big_blue_widget:
    size: big
    color: blue
    updated_at: 2007-12-27 10:19:23
    created_at: 2007-12-27 10:19:23
To build the scenario you have to run:
  rake db:scenario:build
NestedScenarios also allows you to nest scenarios:
  scenario :models => { :users => :banned } do
    User.create(:name => 'Kevin', :banned => true)
  end
This will create an YAML in the following dir:
  [RAILS_ROOT]
  +-test/
    +-fixtures/
      +-models/
        +-users/
          +-banned/
            +-users.yml
Finally, you can choose which scenario to use in your tests by:
  scenario :users
Or, in the case of nested scenarios:
  scenario :models => { :users => :banned }
If no scenario is sent after all, the default behaviour is adopted.
Fixtures path
-------------
If you have fixtures in your fixtures path root and you want those fixtures
to also be loaded, you can configure:
class ActiveSupport::TestCase
  ...
  self.load_root_fixtures = true
  ...
end
You can disable such behaviour in your tests also, by doing:
  scenario :models => { :users => :banned }, :root => false
You just have to remember if you have a scenario with fixtures for a specified
table, it will overwrite the fixtures in your root path for the same table.
Contributors
------------
* Joe Moore (https://github.com/joemoore)
Bugs and Feedback
-----------------
If you discover any bugs, please send an e-mail to jose.valim@gmail.com
If you just want to give some positive feedback or drop a line, that's fine too! =)
Copyright (c) 2009 José Valim
https://blog.plataformatec.com.br/