object_daddy 0.4.1

data/README.markdown

@@ -0,0 +1,326 @@
+Object Daddy
+============
+_Version 0.4.1 (April 28, 2009)_
+
+__Authors:__  [Rick Bradley](mailto:blogicx@rickbradley.com), [Yossef Mendelssohn](mailto:ymendel@pobox.com)
+
+__Copyright:__  Copyright (c) 2007, Flawed Logic, OG Consulting, Rick Bradley, Yossef Mendelssohn
+
+__License:__  MIT License.  See MIT-LICENSE file for more details.
+
+Object Daddy is a library (as well as a Ruby on Rails plugin) designed to
+assist in automating testing of large collections of objects, especially webs
+of ActiveRecord models. It is a descendent of the "Object Mother" pattern for
+creating objects for testing, and is related to the concept of an "object
+exemplar" or _stereotype_.
+
+**WARNING** This code is very much at an _alpha_ development stage. Usage, APIs,
+etc., are all subject to change.
+
+See [http://b.logi.cx/2007/11/26/object-daddy](http://b.logi.cx/2007/11/26/object-daddy) for inspiration, historical drama, and too much reading.
+
+## Installation
+
+
+## As Gem
+
+  sudo gem install object_daddy
+
+config/enviroments/test.rb
+
+  gem.config "object_daddy"
+
+
+## As Plugin
+
+Presuming your version of Rails has git plugin installation support:
+
+  script/plugin install git://github.com/flogic/object_daddy.git
+
+Otherwise, you can install object_daddy by hand:
+
+1. Unpack the object_daddy directory into vendor/plugins/ in your rails project.
+2. Run the object_daddy/install.rb Ruby script.
+
+
+## Testing
+
+Install the rspec gem and cd into the object_daddy directory. Type `spec
+spec/` and you should see all specs run successfully. If you have autotest
+from the ZenTest gem installed you can run autotest in that directory.
+
+## Using Object Daddy
+
+
+Object Daddy adds a `.generate` method to every ActiveRecord model which can be
+called to generate a valid instance object of that model class, for use in
+testing:
+
+    it "should have a comment for every forum the user posts to" do
+      @user = User.generate
+      @post = Post.generate
+      @post.comments << Comment.generate
+      @user.should have(1).comments
+    end
+
+This allows us to generate custom model objects without relying on fixtures,
+and without knowing, in our various widespread tests and specs, the details of
+creating a User, Post, Comment, etc. Not having to know this information means
+the information isn't coded into dozens (or hundreds) of tests, and won't need
+to be changed when the User (Post, Comment, ...) model is refactored later.
+
+Object Daddy will identify associated classes that need to be instantiated to
+make the main model valid. E.g., given the following models:
+
+    class User < ActiveRecord::Base
+      belongs_to :login
+      validates_presence_of :login
+    end
+
+    class Login < ActiveRecord::Base
+      has_one :user
+    end
+
+A call to `User.generate` will also make a call to `Login.generate` so that
+`User#login` is present, and therefore valid.
+
+If all models were able to be created in a valid form by the default Model.new
+call with no knowledge of the model itself, there'd be no need for Object
+Daddy. So, when we deal with models which have validity requirements,
+requiring fields which have format constraints, we need a means of expressing
+how to create those models -- how to satisfy those validity constraints.
+
+Object Daddy provides a `generator_for` method which allows the developer to
+specify, for a specific model attribute, how to make a valid value. Note that
+`validates_uniqueness_of` can require that, even if we make 100,000 instances
+of a model that unique attributes cannot have the same values.
+
+Object Daddy's `generator_for` method can take three main forms corresponding to
+the means of finding a value for the associated attribute: a block, a method
+call, or using a generator class.
+
+    class User < ActiveRecord::Base
+      validates_presence_of :email
+      validates_uniqueness_of :email
+      validates_format_of :email,
+      :with => /^[-a-z_+0-9.]+@(?:[-a-z_+0-9.]\.)+[a-z]+$/i
+      validates_presence_of :username
+      validates_format_of :username, :with => /^[a-z0-9_]{4,12}$/i
+
+      generator_for :email, :start => 'test@domain.com' do |prev|
+        user, domain = prev.split('@')
+        user.succ + '@' + domain
+      end
+
+      generator_for :username, :method => :next_user
+
+      generator_for :ssn, :class => SSNGenerator
+
+      def self.next_user
+        @last_username ||= 'testuser'
+        @last_username.succ
+      end
+    end
+
+    class SSNGenerator
+      def self.next
+        @last ||= '000-00-0000'
+        @last = ("%09d" % (@last.gsub('-', '').to_i + 1)).sub(/^(\d{3})(\d{2})(\d{4})$/, '\1-\2-\3')
+      end
+    end
+
+Note that the block method of invocation (as used with _:email_ above) takes an
+optional _:start_ argument, to specify the value of that attribute on the first
+run. The block will be called thereafter with the previous value of the
+attribute and will generate the next attribute value to be used.
+
+A simple default block is provided for any generator with a :start value.
+
+    class User < ActiveRecord::Base
+      generator_for :name, :start => 'Joe' do |prev|
+        prev.succ
+      end
+
+      generator_for :name, :start => 'Joe'  # equivalent to the above
+    end
+
+The _:method_ form takes a symbol naming a class method in the model class to be
+called to generate a new value for the attribute in question. If the method
+takes a single argument, it will act much like the block method of invocation,
+being called with the previous value and generating the next.
+
+The _:class_ form calls the .next class method on the named class to generate a
+new value for the attribute in question.
+
+The argument (previous value) to the block invocation form can be omitted if
+it's going to be ignored, and simple invocation forms are provided for literal
+values.
+
+    class User < ActiveRecord::Base
+      generator_for(:start_time) { Time.now }
+      generator_for :name, 'Joe'
+      generator_for :age => 25
+    end
+
+The developer would then simply call `User.generate` when testing.
+
+If some attribute values are known (or are being controlled during testing)
+then these can simply be passed in to `.generate`:
+
+    @bad_login = Login.generate(:expiry => 1.week.ago)
+    @expired_user = User.generate(:login => @bad_login)
+
+A `.generate!` method is also provided. The _generate/generate!_ pair of methods
+can be thought of as analogs to create/create!, one merely providing an instance
+that may or may not be valid and the other raising an exception if any
+problem comes up.
+
+Finally, a `.spawn` method is provided that only gives a new, unsaved object. Note
+that this is the only method of the three that is available if you happen to be
+using Object Daddy outside of Rails.
+
+## Exemplars
+
+In the examples given above we are using `generator_for` in the bodies of the
+models themselves. Given that Object Daddy is primarily geared towards
+annotating models with information useful for testing, we anticipate that
+`generator_for` should not normally be included inline in models. Rather, we
+will provide a place where model classes can be re-opened and `generator_for`
+calls (and support methods) can be written without polluting the model files
+with Object Daddy information.
+
+Object Daddy, when installed as a Rails plugin, will create
+*RAILS_ROOT/spec/exemplars/* as a place to hold __exemplar__ files for Rails model
+classes.  (We are seeking perhaps some better terminology)
+
+An __exemplar__ for the User model would then be found in
+*RAILS_ROOT/spec/exemplars/user_exemplar.rb* (when you are using a testing tool
+which works from *RAILS_ROOT/test*, Object Daddy will create
+*RAILS_ROOT/test/exemplars* and look for your exemplars in that directory
+instead). Exemplar files are completely optional, and no model need have
+exemplar files. The `.generate` method will still exist and be callable, and
+`generator_for` can be declared in the model files themselves. If an exemplar
+file is available when `.generate` is called on a model, the exemplar file will
+be loaded and used. An example *user_exemplar.rb* appears below:
+
+    require 'ssn_generator'
+
+    class User < ActiveRecord::Base
+      generator_for :email, :start => 'test@domain.com' do |prev|
+        user, domain = prev.split('@')
+        user.succ + '@' + domain
+      end
+
+      generator_for :username, :method => :next_user
+
+      generator_for :ssn, :class => SSNGenerator
+
+      def self.next_user
+        @last_username ||= 'testuser'
+        @last_username.succ
+      end
+    end
+
+## Blocks
+
+The `spawn`, `generate` and `generate!` methods can all accept a block, to which
+they'll yield the generated object. This provides a nice scoping mechanism in
+your code examples. Consider:
+
+    describe "admin user" do
+      it "should be authorized to create company profiles"
+        admin_user = User.generate!
+        admin_user.activate!
+        admin_user.add_role("admin")
+
+        admin_user.should be_authorized(:create, Company)
+      end
+    end
+
+This could be refactored to:
+
+    describe "admin user" do
+      it "should be authorized to create company profiles" do
+        admin_user = User.generate! do |user|
+          user.activate!
+          user.add_role("admin")
+        end
+
+        admin_user.should be_authorized(:create, Company)
+      end
+    end
+
+Or:
+
+    describe "admin user" do
+      it "should be authorized to create company profiles"
+        User.generate! do |user|
+          user.activate!
+          user.add_role("admin")
+        end.should be_authorized(:create, Company)
+      end
+    end
+
+Or even:
+
+    describe "admin user" do
+      def admin_user
+        @admin_user ||= User.generate! do |user|
+          user.activate!
+          user.add_role("admin")
+        end
+      end
+
+      it "should be authorized to create company profiles"
+        admin_user.should be_authorized(:create, Company)
+      end
+    end
+
+This last refactoring allows you to reuse the admin_user method across
+multiple code examples, balancing DRY with local data.
+
+## Object Daddy and Fixtures
+
+While Object Daddy is meant to obviate the hellish devilspawn that are test
+fixtures, Object Daddy should work alongside fixtures just fine. To each his
+own, I suppose.
+
+## Known Issues
+
+The simple invocation forms for `generator_for` when using literal values do not
+work if the literal value is a Hash. Don't do that.
+
+    class User < ActiveRecord::Base
+      generator_for :thing_hash, { 'some key' => 'some value' }
+      generator_for :other_hash => { 'other key' => 'other value' }
+    end
+
+I'm not sure why this would even ever come up, but seriously, don't.
+
+Required `belongs_to` associations are automatically generated when generating an instance,
+but only if necessary.
+
+    class Category < ActiveRecord::Base
+      has_many :items
+    end
+
+    class Item < ActiveRecord::Base
+      belongs_to :category
+      validates_presence_of :category
+    end
+
+`Item.generate` will generate a new category, but `some_category.items.generate` will not.
+Unless, of course, you are foolish enough to define a generator in the exemplar.
+
+    class Item
+      generator_for(:category) { Category.generate }
+    end
+
+Once again, don't do that.
+
+## Rails _surprises_
+
+Due to the way Rails handles associations, cascading generations (as a result of
+required associations) are always generated-and-saved, even if the original generation
+call was a mere `spawn` (`new`). This may come as a surprise, but it would probably be more
+of a surprise if `User.spawn.save` and `User.generate` weren't comparable.

data/VERSION.yml

@@ -0,0 +1,4 @@
+---
+:major: 0
+:minor: 4
+:patch: 1

data/init.rb

@@ -0,0 +1 @@
+require File.dirname(__FILE__) + "/rails/init"

data/install.rb

@@ -0,0 +1,28 @@
+require 'fileutils'
+
+def readme_contents
+  IO.read(File.join(File.dirname(__FILE__), 'README.markdown'))
+end
+
+rails_root = File.dirname(__FILE__) + '/../../../'
+
+if File.directory?(rails_root + 'spec')
+  unless File.directory?(rails_root + 'spec/exemplars')
+    puts "Creating directory [#{rails_root + 'spec/exemplars'}]"
+    FileUtils.mkdir(rails_root + 'spec/exemplars') 
+  end
+else
+  if File.directory?(rails_root + 'test')
+    unless File.directory?(rails_root + 'test/exemplars')
+      puts "Creating directory [#{rails_root + 'test/exemplars'}]"
+      FileUtils.mkdir(rails_root + 'test/exemplars')
+    end
+  else
+    puts "Creating directory [#{rails_root + 'spec'}]"    
+    FileUtils.mkdir(rails_root + 'spec')
+    puts "Creating directory [#{rails_root + 'spec/exemplars'}]"
+    FileUtils.mkdir(rails_root + 'spec/exemplars')
+  end
+end
+
+puts readme_contents

data/lib/object_daddy.rb

@@ -0,0 +1,239 @@
+module ObjectDaddy
+
+  def self.included(klass)
+    klass.extend ClassMethods
+    if defined? ActiveRecord and klass < ActiveRecord::Base
+      klass.extend RailsClassMethods
+
+      class << klass
+        alias_method :validates_presence_of_without_object_daddy, :validates_presence_of
+        alias_method :validates_presence_of, :validates_presence_of_with_object_daddy
+      end
+    end
+  end
+
+  module ClassMethods
+    attr_accessor :exemplars_generated, :exemplar_path, :generators
+    attr_reader :presence_validated_attributes
+    protected :exemplars_generated=
+
+    # :call-seq:
+    #   spawn()
+    #   spawn() do |obj| ... end
+    #   spawn(args)
+    #   spawn(args) do |obj| ... end
+    #
+    # Creates a valid instance of this class, using any known generators. The
+    # generated instance is yielded to a block if provided.
+    def spawn(args = {})
+      gather_exemplars
+      if @concrete_subclass_name
+        return block_given? \
+          ? const_get(@concrete_subclass_name).spawn(args) {|instance| yield instance} \
+          : const_get(@concrete_subclass_name).spawn(args)
+      end
+      generate_values(args)
+      instance = new(args)
+      yield instance if block_given?
+      instance
+    end
+
+    # register a generator for an attribute of this class
+    # generator_for :foo do |prev| ... end
+    # generator_for :foo do ... end
+    # generator_for :foo, value
+    # generator_for :foo => value
+    # generator_for :foo, :class => GeneratorClass
+    # generator_for :foo, :method => :method_name
+    def generator_for(handle, args = {}, &block)
+      if handle.is_a?(Hash)
+        raise ArgumentError, "only specify one attr => value pair at a time" unless handle.keys.length == 1
+        gen_data = handle
+        handle = gen_data.keys.first
+        args = gen_data[handle]
+      end
+
+      raise ArgumentError, "an attribute name must be specified" unless handle = handle.to_sym
+
+      unless args.is_a?(Hash)
+        unless block
+          retval = args
+          block = lambda { retval }  # lambda { args } results in returning the empty hash that args gets changed to
+        end
+        args = {}  # args is assumed to be a hash for the rest of the method
+      end
+
+      if args[:start]
+        block ||= lambda { |prev|  prev.succ }
+      end
+
+      if args[:method]
+        h = { :method => args[:method].to_sym }
+        h[:start] = args[:start] if args[:start]
+        record_generator_for(handle, h)
+      elsif args[:class]
+        raise ArgumentError, "generator class [#{args[:class].name}] does not have a :next method" unless args[:class].respond_to?(:next)
+        record_generator_for(handle, :class => args[:class])
+      elsif block
+        raise ArgumentError, "generator block must take an optional single argument" unless (-1..1).include?(block.arity)  # NOTE: lambda {} has an arity of -1, while lambda {||} has an arity of 0
+        h = { :block => block }
+        h[:start] = args[:start] if args[:start]
+        record_generator_for(handle, h)
+      else
+        raise ArgumentError, "a block, :class generator, :method generator, or value must be specified to generator_for"
+      end
+    end
+
+    def generates_subclass(subclass_name)
+      @concrete_subclass_name = subclass_name.to_s
+    end
+
+    def gather_exemplars
+      return if exemplars_generated
+      if superclass.respond_to?(:gather_exemplars)
+        superclass.gather_exemplars
+        self.generators = (superclass.generators || {}).dup
+      end
+
+      [*exemplar_path].each do |raw_path|
+        path = File.join(raw_path, "#{underscore(name)}_exemplar.rb")
+        load(path) if File.exists?(path)
+      end
+      self.exemplars_generated = true
+    end
+
+    def presence_validated_attributes
+      @presence_validated_attributes ||= {}
+      attrs = @presence_validated_attributes
+      if superclass.respond_to?(:presence_validated_attributes)
+        attrs = superclass.presence_validated_attributes.merge(attrs)
+      end
+      attrs
+    end
+
+  protected
+
+    # we define an underscore helper ourselves since the ActiveSupport isn't available if we're not using Rails
+    def underscore(string)
+      string.gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+    end
+
+    def record_generator_for(handle, generator)
+      self.generators ||= {}
+      raise ArgumentError, "a generator for attribute [:#{handle}] has already been specified" if (generators[handle] || {})[:source] == self
+      generators[handle] = { :generator => generator, :source => self }
+    end
+
+  private
+
+    def generate_values(args)
+      (generators || {}).each_pair do |handle, gen_data|
+        next if args.include?(handle) or args.include?(handle.to_s)
+        generator = gen_data[:generator]
+        if generator[:block]
+          process_generated_value(args, handle, generator, generator[:block])
+        elsif generator[:method]
+          method = method(generator[:method])
+          if method.arity == 1
+            process_generated_value(args, handle, generator, method)
+          else
+            args[handle] = method.call
+          end
+        elsif generator[:class]
+          args[handle] = generator[:class].next
+        end
+      end
+
+      generate_missing(args)
+    end
+
+    def process_generated_value(args, handle, generator, block)
+      if generator[:start]
+        value = generator[:start]
+        generator.delete(:start)
+      else
+        value = block.call(generator[:prev])
+      end
+      generator[:prev] = args[handle] = value
+    end
+
+    def generate_missing(args)
+      if presence_validated_attributes and !presence_validated_attributes.empty?
+        req = {}
+        (presence_validated_attributes.keys - args.keys).each {|a| req[a.to_s] = true } # find attributes required by validates_presence_of not already set
+
+        belongs_to_associations = reflect_on_all_associations(:belongs_to).to_a
+        missing = belongs_to_associations.select { |a|  req[a.name.to_s] or req[a.primary_key_name.to_s] }
+        if create_scope = scope(:create)
+          missing.reject! { |a|   create_scope.include?(a.primary_key_name) }
+        end
+        missing.reject! { |a|  [a.name, a.primary_key_name].any? { |n|  args.stringify_keys.include?(n.to_s) } }
+        missing.each {|a| args[a.name] = a.class_name.constantize.generate }
+      end
+    end
+  end
+
+  module RailsClassMethods
+    def exemplar_path
+      dir = File.directory?(File.join(RAILS_ROOT, 'spec')) ? 'spec' : 'test'
+      File.join(RAILS_ROOT, dir, 'exemplars')
+    end
+
+    def validates_presence_of_with_object_daddy(*attr_names)
+      @presence_validated_attributes ||= {}
+      new_attr = attr_names.dup
+      new_attr.pop if new_attr.last.is_a?(Hash)
+      new_attr.each {|a| @presence_validated_attributes[a] = true }
+      validates_presence_of_without_object_daddy(*attr_names)
+    end
+
+    # :call-seq:
+    #   generate()
+    #   generate() do |obj| ... end
+    #   generate(args)
+    #   generate(args) do |obj| ... end
+    #
+    # Creates and tries to save an instance of this class, using any known
+    # generators. The generated instance is yielded to a block if provided.
+    #
+    # This will not raise errors on a failed save. Use generate! if you
+    # want errors raised.
+    def generate(args = {})
+      spawn(args) do |instance|
+        instance.save
+        yield instance if block_given?
+      end
+    end
+
+    # :call-seq:
+    #   generate()
+    #   generate() do |obj| ... end
+    #   generate(args)
+    #   generate(args) do |obj| ... end
+    #
+    # Creates and tries to save! an instance of this class, using any known
+    # generators. The generated instance is yielded to a block if provided.
+    #
+    # This will raise errors on a failed save. Use generate if you do not want
+    # errors raised.
+    def generate!(args = {})
+      spawn(args) do |instance|
+        instance.save!
+        yield instance if block_given?
+      end
+    end
+  end
+end
+
+unless ActiveRecord::Base.respond_to? :inherited_with_object_daddy
+  class ActiveRecord::Base
+    def self.inherited_with_object_daddy(subclass)
+      self.inherited_without_object_daddy(subclass)
+      subclass.send(:include, ObjectDaddy) unless subclass < ObjectDaddy
+    end
+
+    class << self
+      alias_method_chain :inherited, :object_daddy
+    end
+  end
+end