= Blueprints

Another replacement for factories and fixtures that focuses on being DRY and making developers type as little as possible.

== Usage

Blueprints look like this:

    blueprint :apple do
      Fruit.create! :species => 'apple'
    end

    blueprint :orange do
      Fruit.create! :species => 'orange'
    end

    blueprint :fruitbowl => [:apple, :orange] do
      FruitBowl.create! :fruit => [@apple,@orange]
    end

    blueprint :kitchen => :fruitbowl do
      Kitchen.create! :fruitbowl => @fruitbowl
    end

...and you use them in specs like:

    describe Fruit, "apple" do
      before do
        build :apple
      end
  
      it "should be an apple" do
        @apple.species.should == 'apple'
      end
    end

    describe FruitBowl, "with and apple and an orange" do
      before do
        build :fruitbowl
      end

      it "should have 2 fruits" do
        @fruitbowl.should have(2).fruit
      end
    end

Result of 'blueprint' block is assigned to an instance variable with the same name. You can also assign your own instance variables
inside 'blueprint' block and they will be accessible in tests that build this blueprint.

Instead of SomeModel.create! you can also use SomeModel.blueprint, which does the same thing but also bypasses attr_protected
and attr_accessible restrictions (which is what you usually want in tests).

There's also a shorthand for these type of scenarios:

    blueprint :something do
      @something = SomeModel.blueprint :field => 'value'
    end

You can just type:

    SomeModel.blueprint :something, :field => 'value'

All blueprints are run only once, no matter how many times they were called, meaning that you don't need to worry about
duplicating data.

Blueprints searches for blueprints files in this particular order in Rails (Merb) root:
* blueprints.rb
* blueprints/*.rb
* blueprint.rb
* blueprint/*.rb
* spec/blueprints.rb
* spec/blueprints/*.rb
* spec/blueprint.rb
* spec/blueprint/*.rb
* test/blueprints.rb
* test/blueprints/*.rb
* test/blueprint.rb
* test/blueprint/*.rb
You can pass :root option to override framework root and :filename option to pass custom filename pattern 

== Setup

The easiest way to install this gem for Ruby on Rails is just add this line to config/environment.rb (or config/environments/test.rb):

    config.gem 'blueprints', :source => 'http://gemcutter.org'

If you’re not using rails, then you can install it through command line

    gem sources -a http://gemcutter.org
    sudo gem install blueprints

Lastly you could use it as plugin:

    ruby script/plugin install git://github.com/sinsiliux/blueprints.git

Blueprints is activated by calling enable_blueprints. For specifics on how to call that in your testing framework see a little lower.
enable_blueprints supports these parameters:
* :root - custom framework root if automatic detection fails for some reason (eg. not rails/merb project)
* :filename - custom files pattern with blueprints plans
* :prebuild - list of blueprints plans that should be preloaded (available in all tests, never reloaded so they're much faster)
* :delete_policy - set custom delete policy when deleting everything from tables (before test suite or when calling demolish). Can be :truncate or :delete, defaults to :delete

=== RSpec

Add the following to spec_helper.rb

    Spec::Runner.configure do |config|
      ...
  
      config.enable_blueprints :filename => 'scenarios.rb', :prebuild => :preloaded_scenario
    end

=== Test::Unit

Add the following lines to test_helper.rb

    class ActiveSupport::TestCase
      ...

      enable_blueprints
    end

== Advanced Usage

Its just ruby, right? So go nuts:

    1.upto(9) do |i|
      plan("user_#{i}") do
        user = User.create! :name => "user#{i}"
        instance_variable_set("@user_#{i}",user)
      end
    end

== Transactions

Blueprints is transactional, meaning that after every test transaction is dropped and database is reset to
starting point. Starting point is empty database + any scenarios that you specify in enable_blueprints.

== TODO

* Add plan namespaces for better organisation.
* Add ability to revert one plan.
* Add preloading plans for whole block of tests.
* Fix rake tasks

== Credits

Andrius Chamentauskas <sinsiliux@gmail.com>

The code is based on hornsby scenario plugin by Lachie Cox, which is based on Err's code found in this post: http://errtheblog.com/post/7708

== License

MIT, see LICENCE