lawrencepit-machinery 0.5 → 0.5.1

data/README.markdown

@@ -3,19 +3,18 @@ Machinery
 
 *Machinery to create object graphs.*
 
-Machinery helps to create object graphs for use in tests without needing fixtures.
-These object graphs are easily re-usable in Test::Unit, RSpec, Cucumber and
-in rake tasks to populate a database.
+Machinery helps to create object graphs for use in tests without needing
+fixtures, using pure ruby style. These object graphs are easily re-usable
+in Test::Unit, RSpec, Cucumber and in rake tasks to populate a database.
 
-Why write stuff like:
-
-    users(:admin).should be_nil
-
-when you can just as well write:
-
-    @user_admin.should be_nil
+Secondly, even if you don't need object graphs, Machinery can speed up
+your tests significantly because you can set up any model objects in
+a before(:all) instead of a before(:each), and at the end of the tests
+all activerecord objects created in the before(:all) will be cleaned up
+automatically.
 
-Use less magic. Less code. Makes software softer.
+Machinery currently only works with ActiveRecord.
+A DataMapper abstraction should be too easy.
 
 
 Usage
@@ -23,26 +22,28 @@ Usage
 
 In /spec/scenarios.rb
 
-    scenario :earth_ships do
-      @titanic = Ship.create!(:name => "Titanic")
-      @pirates = Ship.create!(:name => "Pirate")
-    end
+    Machinery.define do
+      scenario :earth_ships do
+        @titanic = Ship.create!(:name => "Titanic")
+        @pirate  = Ship.create!(:name => "Pirate")
+      end
 
-    scenario :space_ships do
-      @apollo = Ship.create!(:name => "Apollo")
-      @uss_enterprise = Ship.create!(:name => "USS Enterprise")
-    end
+      scenario :space_ships do
+        @apollo = Ship.create!(:name => "Apollo")
+        @uss_enterprise = Ship.create!(:name => "USS Enterprise")
+      end
 
-    scenario :all_ships do
-      scenarios :earth_ships, :space_ships
-      @sunken_ship = Ship.create!(:name => "Sunk")
+      scenario :all_ships do
+        scenarios :earth_ships, :space_ships
+        @sunken_ship = Ship.create!(:name => "Sunk")
+      end
     end
 
 
 In /spec/spec_helper.rb
 
     require 'machinery'
-    Machinery.load(File.dirname(__FILE__) + '/scenarios.rb')
+    require File.join(File.dirname(__FILE__) + 'scenarios')
 
 
 In /spec/models/ship_spec.rb
@@ -50,8 +51,8 @@ In /spec/models/ship_spec.rb
     describe Ship do
       scenarios :all_ships
 
-      it "should create a pirates ship" do
-        @pirates.should_not be_nil
+      it "should create a pirate ship" do
+        @pirate.should_not be_nil
       end
 
       it "should have 5 ships" do
@@ -60,6 +61,31 @@ In /spec/models/ship_spec.rb
     end
 
 
+Explain
+-------
+
+When you use +scenario+ with a block you are defining a scenario. Any instance variables you declare within a scenario will be available in your test.
+
+When you use +scenario+ without a block then you indicate that the block for the scenario you previously defined should be executed. Note that you can re-use scenarios within scenarios.
+
+When you declare to use a scenario within an rspec +ExampleGroup+ (as in the example above) then the instances will be created for you exactly once. They will automatically be removed from the database after all the tests have run. Any instance variables declared within a scenario will be cloned before each test. If you make sure you use +use_transactional_fixtures+ then this means:
+- speedy tests, because instances are created exactly once for all tests
+- you can mess around with the instance variables any way you like within a test method as before each test they will always be in exactly the same state.
+
+
+Magic?
+------
+
+Why write stuff like:
+
+    users(:admin).should be_nil
+
+when you can just as well write:
+
+    @user_admin.should be_nil
+
+Use less magic. Less code. Makes software softer.
+
 
 Installation
 ------------
@@ -122,9 +148,9 @@ for inspiration.
 
 After using model_stubbing on a relatively large project for over a year I decided
 a simpler solution was needed. Object graphs need to be easily re-usable by specs,
-unit tests, cucumber stories and ad-hoc database loading.
+unit tests, cucumber stories and ad-hoc database loading. And tests need to be speedy.
 
-Machinery works especially great in combination with
+Machinery works especially pleasurable in combination with
 [Machinist](http://github.com/notahat/machinist) or
 [FactoryGirl](http://github.com/thoughtbot/factory_girl).
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: lawrencepit-machinery
 version: !ruby/object:Gem::Version 
-  version: "0.5"
+  version: 0.5.1
 platform: ruby
 authors: 
 - Lawrence Pit