File: README — Documentation for josevalim-nested

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: http://josevalim.blogspot.com/
  Git : http://github.com/josevalim/nested_scenarios

FixtureScenariosBuilder
  Info: http://errtheblog.com/post/7708
  SVN : svn://errtheblog.com/svn/plugins/fixture_scenarios_builder

FixtureScenarios
  Info: http://code.google.com/p/fixture-scenarios/
  SVN : http://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 http://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 scenarios.rb 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 scenarios.rb 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 users.yml 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:

NestedScenarios.load_root_fixtures = true

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.

Bugs and Feedback

If you discover any bugs, please send an e-mail to [email protected] If you just want to give some positive feedback or drop a line, that’s fine too! =)