blueprints 0.3.4 → 0.4.0

data/.gitignore

@@ -1,4 +1,5 @@
 .idea
 *.gem
+html
 spec/active_record/fixtures/database.yml
 debug.log

data/Rakefile

@@ -9,7 +9,13 @@ begin
     gemspec.homepage = "http://github.com/sinsiliux/blueprints"
     gemspec.authors = ["Andrius Chamentauskas"]
   end
-  Jeweler::GemcutterTasks.new  
+  Jeweler::GemcutterTasks.new
 rescue LoadError
   puts "Jeweler not available. Install it with: sudo gem install jeweler"
 end
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rd|
+  rd.main = "README.rdoc"
+  rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+end

data/VERSION

@@ -1 +1 @@
-0.3.4
+0.4.0

data/blueprints.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{blueprints}
-  s.version = "0.3.4"
+  s.version = "0.4.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Andrius Chamentauskas"]
-  s.date = %q{2009-12-10}
+  s.date = %q{2009-12-25}
   s.description = %q{Another replacement for factories and fixtures. The library that lazy typists will love}
   s.email = %q{sinsiliux@gmail.com}
   s.extra_rdoc_files = [
@@ -27,6 +27,7 @@ Gem::Specification.new do |s|
      "install.rb",
      "lib/blueprints.rb",
      "lib/blueprints/buildable.rb",
+     "lib/blueprints/context.rb",
      "lib/blueprints/database_backends/abstract.rb",
      "lib/blueprints/database_backends/active_record.rb",
      "lib/blueprints/database_backends/none.rb",

data/lib/blueprints.rb

@@ -1,6 +1,6 @@
 require 'activesupport'
 files = %w{
-buildable namespace root_namespace plan file_context helper errors
+context buildable namespace root_namespace plan file_context helper errors
 database_backends/abstract database_backends/active_record database_backends/none
 }
 files << if defined? Spec or $0 =~ /script.spec$/
@@ -18,24 +18,37 @@ module Blueprints
     end
   end.flatten
 
+  # Returns a list of supported ORMs. For now it supports ActiveRecord and None.
   def self.supported_orms
     (DatabaseBackends.constants - ['Abstract']).collect {|class_name| class_name.underscore.to_sym }
   end
 
+  # Returns root of project blueprints is used in. Automatically detected for rails and merb. Can be overwritten by using
+  # <tt>:root</tt> options when loading blueprints. If root can't be determined, returns nil which means that current
+  # directory is asumed as root.
   def self.framework_root
     @@framework_root ||= RAILS_ROOT rescue Rails.root rescue Merb.root rescue nil
   end
 
+  # Setups variables from global context and starts transaction. Should be called before every test case.
   def self.setup(current_context)
     Namespace.root.setup
     Namespace.root.copy_ivars(current_context)
     @@orm.start_transaction
   end
 
+  # Rollbacks transaction returning everything to state before test. Should be called after every test case.
   def self.teardown
     @@orm.rollback_transaction
   end
 
+  # Sets up configuration, clears database, runs scenarios that have to be prebuilt. Should be run before all test cases and before <tt>setup</tt>.
+  # Accepts following options:
+  # * <tt>:delete_policy</tt> - allows changing how tables in database should be cleared. By default simply uses delete statement. Supports :delete and :truncate options.
+  # * <tt>:filename</tt> - Allows passing custom filename pattern in case blueprints are held in place other than spec/blueprint, test/blueprint, blueprint.
+  # * <tt>:prebuild</tt> - Allows passing scenarios that should be prebuilt and available in all tests. Works similarly to fixtures.
+  # * <tt>:root</tt> - Allows passing custom root folder to use in case of non rails and non merb project.
+  # * <tt>:orm</tt> - Allows specifying what orm should be used. Default to <tt>:active_record</tt>, also allows <tt>:none</tt>
   def self.load(options = {})
     options.assert_valid_keys(:delete_policy, :filename, :prebuild, :root, :orm)
     options.symbolize_keys!
@@ -52,6 +65,14 @@ module Blueprints
     Namespace.root.prebuild(options[:prebuild])
   end
 
+  # Clears all tables in database. Also accepts a list of tables in case not all tables should be cleared.
+  def self.delete_tables(*tables)
+    @@orm.delete_tables(@@delete_policy, *tables)
+  end
+
+  protected
+
+  # Loads blueprints file and creates blueprints from data it contains. Is run by setup method
   def self.load_scenarios_files(*patterns)
     patterns.flatten!
     patterns.collect! {|pattern| File.join(framework_root, pattern)} if framework_root
@@ -65,8 +86,4 @@ module Blueprints
 
     raise "Plans file not found! Put plans in #{patterns.join(' or ')} or pass custom filename pattern with :filename option"
   end
-
-  def self.delete_tables(*tables)
-    @@orm.delete_tables(@@delete_policy, *tables)
-  end
 end

data/lib/blueprints/buildable.rb

@@ -10,10 +10,12 @@ module Blueprints
       Namespace.root.add_child(self) if Namespace.root
     end
 
+    # Defines blueprint dependencies. Used internally, but can be used externally too.
     def depends_on(*scenarios)
       @parents = (@parents || []) + scenarios.map{|s| s.to_sym}
     end
 
+    # Builds dependencies of blueprint and then blueprint itself. 
     def build
       namespace = self
       namespace.build_parent_plans while namespace = namespace.namespace
@@ -51,4 +53,4 @@ module Blueprints
       end
     end
   end
-end
+end

data/lib/blueprints/context.rb

@@ -0,0 +1,6 @@
+module Blueprints
+  # Class that blueprint blocks are evaluated against. Allows you to access options that were passed to build method.
+  class Context
+    attr_accessor :options
+  end
+end

data/lib/blueprints/database_backends/abstract.rb

@@ -1,14 +1,18 @@
 module Blueprints
   module DatabaseBackends
     class Abstract
+      # Method to start transaction. Needs to be implemented in child class.
       def start_transaction
         raise NotImplementedError
       end
 
+      # Method to revert transaction. Needs to be implemented in child class.
       def revert_transaction
         raise NotImplementedError
       end
 
+      # Method to clear tables. Should accept delete policy and list of tables to delete. If list of tables is empty, should
+      # delete all tables. Needs to be implemented in child class.
       def delete_tables(delete_policy, *args)
         raise NotImplementedError
       end

data/lib/blueprints/database_backends/active_record.rb

@@ -3,21 +3,26 @@ module Blueprints
     class ActiveRecord
       DELETE_POLICIES = {:delete => "DELETE FROM %s", :truncate => "TRUNCATE %s"}
 
+      # Extends active record with blueprint method
       def initialize
-        ::ActiveRecord::Base.extend(ActiveRecordExtensions)
+        ::ActiveRecord::Base.send(:include, ActiveRecordExtensions::Instance)
+        ::ActiveRecord::Base.extend(ActiveRecordExtensions::Class)
       end
 
+      # Starts new transaction and marks it as unjoinable so that test case could use transactions too.
       def start_transaction
         ::ActiveRecord::Base.connection.increment_open_transactions
         ::ActiveRecord::Base.connection.transaction_joinable = false
         ::ActiveRecord::Base.connection.begin_db_transaction
       end
 
+      # Rollbacks transaction
       def rollback_transaction
         ::ActiveRecord::Base.connection.rollback_db_transaction
         ::ActiveRecord::Base.connection.decrement_open_transactions
       end
 
+      # Clears all tables using delete policy specified. Also accepts list of tables to delete.
       def delete_tables(delete_policy, *args)
         delete_policy ||= :delete
         raise ArgumentError, "Unknown delete policy #{delete_policy}" unless DELETE_POLICIES.keys.include?(delete_policy)
@@ -25,30 +30,52 @@ module Blueprints
         args.each { |t| ::ActiveRecord::Base.connection.delete(DELETE_POLICIES[delete_policy] % t) }
       end
 
+      # Returns all tables without skipped ones.
       def tables
         ::ActiveRecord::Base.connection.tables - skip_tables
       end
 
+      # Returns tables that should never be cleared (those that contain migrations information).
       def skip_tables
         %w( schema_info schema_migrations )
       end
 
+      # Extensions for active record class
       module ActiveRecordExtensions
-        def blueprint(*args)
-          options = args.extract_options!
-          if args.present?
-            klass = self
-            Blueprints::Plan.new(*args) do
-              klass.blueprint options
-            end
-          else
-            returning(self.new) do |object|
-              options.each do |attr, value|
-                value = Blueprints::Namespace.root.context.instance_variable_get(value) if value.is_a? Symbol and value.to_s =~ /^@.+$/
-                object.send("#{attr}=", value)
+        module Class
+          # Two forms of this method can be used. First one is typically used inside blueprint block. Essentially it does
+          # same as <tt>create!</tt>, except it does bypass attr_protected and attr_accessible. It accepts only a hash or attributes,
+          # same as <tt>create!</tt> does.
+          #   blueprint :post => :user do
+          #     @user.posts.blueprint(:title => 'first post', :text => 'My first post')
+          #   end
+          # The second form is used when you want to define new blueprint. It takes first argument as name of blueprint
+          # and second one as hash of attributes. As you cannot use instance variables outside of blueprint block, you need
+          # to prefix them with colon. So the example above could be rewritten like this:
+          #   Post.blueprint(:post, :title => 'first post', :text => 'My first post', :user => :@user).depends_on(:user)
+          # or like this:
+          #   Post.blueprint({:post => :user}, :title => 'first post', :text => 'My first post', :user => :@user)
+          def blueprint(*args)
+            attributes = args.extract_options!
+            if args.present?
+              klass = self
+              Blueprints::Plan.new(*args) do
+                klass.blueprint attributes.merge(options)
               end
-              object.save!
+            else
+              returning(self.new) { |object| object.blueprint(attributes) }
+            end
+          end
+        end
+
+        module Instance
+          # Updates attributes of object and calls save!. Bypasses attr_protected ant attr_accessible.
+          def blueprint(attributes)
+            attributes.each do |attr, value|
+              value = Blueprints::Namespace.root.context.instance_variable_get(value) if value.is_a? Symbol and value.to_s =~ /^@.+$/
+              send("#{attr}=", value)
             end
+            save!
           end
         end
       end

data/lib/blueprints/database_backends/none.rb

@@ -1,12 +1,16 @@
 module Blueprints
   module DatabaseBackends
+    # Database backend when no orm is actually used. Can be adapted to work with any kind of data.
     class None
+      # Dummy method
       def start_transaction
       end
 
+      # Dummy method
       def revert_transaction
       end
 
+      # Dummy method
       def delete_tables(delete_policy, *args)
       end
     end

data/lib/blueprints/errors.rb

@@ -1,4 +1,5 @@
 module Blueprints
+  # Is raised when blueprint or namespace is not found.
   class PlanNotFoundError < NameError
     def initialize(*args)
       @plans = args
@@ -8,4 +9,4 @@ module Blueprints
       "Plan/namespace not found '#{@plans.join(',')}'"
     end
   end
-end
+end

data/lib/blueprints/extensions/rspec.rb

@@ -1,6 +1,9 @@
-module Spec
-  module Runner
+module Spec #:nodoc:
+  module Runner #:nodoc:
     class Configuration
+      # Enables blueprints in rspec. Is automatically added if <tt>Spec</tt> is defined at loading time or <tt>script/spec</tt>
+      # is used. You might need to require it manually in certain case (eg. running specs from metrics).
+      # Accepts options hash. For supported options please check Blueprints.load.
       def enable_blueprints(options = {})
         Blueprints.load(options)
 
@@ -14,4 +17,4 @@ module Spec
       end
     end
   end
-end
+end

data/lib/blueprints/extensions/test_unit.rb

@@ -1,12 +1,16 @@
-module Test
-  module Unit
+module Test #:nodoc:
+  module Unit #:nodoc:
     class TestCase
+      # Runs tests with blueprints support
       def run_with_blueprints(result, &progress_block)
         Blueprints.setup(self)
         run_without_blueprints(result, &progress_block)
         Blueprints.teardown
       end
 
+      # Enables blueprints in test/unit. Is automatically added if <tt>Spec</tt> is not defined at loading time.
+      # You might need to require it manually in certain case (eg. using both rspec and test/unit).
+      # Accepts options hash. For supported options please check Blueprints.load.
       def self.enable_blueprints(options = {})
         include Blueprints::Helper
         Blueprints.load(options)
@@ -14,4 +18,4 @@ module Test
       end
     end
   end
-end
+end

data/lib/blueprints/file_context.rb

@@ -1,9 +1,12 @@
 module Blueprints
+  # Module that blueprints file is executed against. Defined <tt>blueprint</tt> and <tt>namespace</tt> methods.
   module FileContext
+    # Creates a new plan by name and block passed
     def self.blueprint(plan, &block)
       Plan.new(plan, &block)
     end
 
+    # Creates new namespace by name, and evaluates block against it.
     def self.namespace(name)
       old_namespace = Namespace.root
       namespace = Namespace.new(name)
@@ -13,4 +16,4 @@ module Blueprints
       Namespace.root = old_namespace
     end
   end
-end
+end

data/lib/blueprints/helper.rb

@@ -1,5 +1,13 @@
 module Blueprints
+  # A helper module that should be included in test framework. Adds methods <tt>build</tt> and <tt>demolish</tt>
   module Helper
+    # Builds one or more blueprints by their names. You can pass names as symbols or strings. You can also pass additional
+    # options hash which will be available by calling <tt>options</tt> in blueprint block. Returns result of blueprint block.
+    #   # build :apple and orange blueprints
+    #   build :apple, :orange
+    #
+    #   # build :apple scenario with additional options
+    #   build :apple, :color => 'red'
     def build_plan(*names)
       result = Namespace.root.build(*names).last
       Namespace.root.copy_ivars(self)
@@ -8,6 +16,10 @@ module Blueprints
 
     alias :build :build_plan
 
+    # Clears all tables in database. You can pass table names to clear only those tables. You can also pass <tt>:undo</tt> option
+    # to remove scenarios from built scenarios cache.
+    #
+    # TODO: add sample usage
     def demolish(*args)
       options = args.extract_options!
       Blueprints.delete_tables(*args)
@@ -23,4 +35,4 @@ module Blueprints
       end
     end
   end
-end
+end

data/lib/blueprints/namespace.rb

@@ -1,4 +1,6 @@
 module Blueprints
+  # Namespace class, inherits from <tt>Buildable</tt>. Allows adding and finding child blueprints/namespaces and building
+  # all it's children.
   class Namespace < Buildable
     cattr_accessor :root
     delegate :empty?, :size, :to => :@children
@@ -28,4 +30,4 @@ module Blueprints
       Namespace.root.add_variable(path, @children.collect {|p| p.last.build }.uniq)
     end
   end
-end
+end

data/lib/blueprints/plan.rb

@@ -1,14 +1,17 @@
 module Blueprints
+  # Class for actual blueprints. Allows building itself by executing block passed against current context.
   class Plan < Buildable
+    # Initializes blueprint by name and block
     def initialize(name, &block)
       super(name)
       @block = block
     end
 
+    # Builds plan and adds it to executed plan hash. Setups instance variable with same name as plan if it is not defined yet.
     def build_plan
       surface_errors do
         if @block
-          @result = Namespace.root.context.module_eval(&@block)
+          @result = Namespace.root.context.instance_eval(&@block)
           Namespace.root.add_variable(path, @result)
         end
       end unless Namespace.root.executed_plans.include?(path)
@@ -25,4 +28,4 @@ module Blueprints
       raise error
     end
   end
-end
+end

data/lib/blueprints/root_namespace.rb

@@ -1,40 +1,50 @@
 module Blueprints
+  # Defines a root namespace that is used when no other namespace is. Apart from functionality in namespace it also allows
+  # building blueprints/namespaces by name. Is also used for copying instance variables between blueprints/contexts/global
+  # context.
   class RootNamespace < Namespace
     attr_reader :context, :plans
     attr_accessor :executed_plans
-    
+
     def initialize
       @executed_plans = Set.new
       @global_executed_plans = Set.new
-      @global_context = Module.new
 
       super ''
     end
 
+    # Loads all instance variables from global context to current one.
     def setup
-      @context = YAML.load(@global_context)
+      @context = Blueprints::Context.new
+      YAML.load(@global_variables).each { |name, value| @context.instance_variable_set(name, value) }
       @executed_plans = @global_executed_plans.clone
     end
 
+    # Copies all instance variables from current context to another one.
     def copy_ivars(to)
       @context.instance_variables.each do |iv|
         to.instance_variable_set(iv, @context.instance_variable_get(iv))
       end
     end
 
+    # Sets up global context and executes prebuilt blueprints against it.
     def prebuild(plans)
-      @context = @global_context
+      @context = Blueprints::Context.new
       @global_scenarios = build(*plans) if plans
       @global_executed_plans = @executed_plans
-      @global_context = YAML.dump(@global_context)
+
+      @global_variables = YAML.dump(@context.instance_variables.each_with_object({}) {|iv, hash| hash[iv] = @context.instance_variable_get(iv) })
     end
 
+    # Builds blueprints that are passed against current context.
     def build(*names)
+      @context.options = names.extract_options!
       names.map {|name| self[name].build}
     end
 
+    # Sets instance variable in current context to passed value.
     def add_variable(name, value)
-      name = "@#{name}" unless name.to_s[0, 1] == "@" 
+      name = "@#{name}" unless name.to_s[0, 1] == "@"
       @context.instance_variable_set(name, value) unless @context.instance_variable_get(name)
     end
 

data/spec/active_record/blueprint.rb

@@ -50,4 +50,8 @@ namespace :pitted => :pine do
   namespace :red => :orange do
     Fruit.blueprint(:apple, :species => 'pitted red apple')
   end
-end
+end
+
+blueprint :apple_with_params do
+  Fruit.create! options.merge(:species => 'apple')
+end

data/spec/active_record/blueprints_spec.rb

@@ -7,7 +7,7 @@ describe Blueprints do
     end
 
     it "should support required ORMS" do
-      Blueprints.supported_orms.should == [:active_record, :none]
+      Blueprints.supported_orms.should =~ [:active_record, :none]
     end
   end
 
@@ -221,7 +221,7 @@ describe Blueprints do
       Blueprints::Namespace.root.expects(:empty?).returns(true)
       lambda {
         Blueprints.load(:orm => :unknown)
-      }.should raise_error(ArgumentError, "Unsupported ORM unknown. Blueprints supports only active_record, none")
+      }.should raise_error(ArgumentError, "Unsupported ORM unknown. Blueprints supports only #{Blueprints.supported_orms.join(', ')}")
     end
   end
 
@@ -246,6 +246,18 @@ describe Blueprints do
       @acorn.should_not be_nil
       @acorn.tree.should == @oak
     end
+
+    it "should allow updating object using blueprint method" do
+      build :oak
+      @oak.blueprint(:size => 'updated')
+      @oak.reload.size.should == 'updated'
+    end
+
+    it "should automatically merge passed options" do
+      build :oak, :size => 'optional'
+      @oak.name.should == 'Oak'
+      @oak.size.should == 'optional'
+    end
   end
 
   describe "with pitted namespace" do
@@ -294,5 +306,19 @@ describe Blueprints do
       end
     end
   end
+
+  describe 'extra parameters' do
+    it "should allow passing extra parameters when building" do
+      build :apple_with_params, :average_diameter => 14
+      @apple_with_params.average_diameter.should == 14
+      @apple_with_params.species.should == 'apple'
+    end
+
+    it "should allow set options to empty hash if no parameters are passed" do
+      build :apple_with_params
+      @apple_with_params.average_diameter.should == nil
+      @apple_with_params.species.should == 'apple'
+    end
+  end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: blueprints
 version: !ruby/object:Gem::Version 
-  version: 0.3.4
+  version: 0.4.0
 platform: ruby
 authors: 
 - Andrius Chamentauskas
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-12-10 00:00:00 +02:00
+date: 2009-12-25 00:00:00 +02:00
 default_executable: 
 dependencies: []
 
@@ -33,6 +33,7 @@ files:
 - install.rb
 - lib/blueprints.rb
 - lib/blueprints/buildable.rb
+- lib/blueprints/context.rb
 - lib/blueprints/database_backends/abstract.rb
 - lib/blueprints/database_backends/active_record.rb
 - lib/blueprints/database_backends/none.rb