vitalish-factory_girl 1.2.5 → 1.2.6

data/VERSION

@@ -0,0 +1 @@
+1.2.6

data/lib/factory_girl/aliases.rb

@@ -1,14 +1,42 @@
-module FactoryGirl
+class Factory
 
   class << self
     attr_accessor :aliases #:nodoc:
   end
   self.aliases = [
-    [/(.+)_id/, '\1'],
+    [/(.*)_id/, '\1'],
     [/(.*)/, '\1_id']
   ]
 
-  def self.aliases_for(attribute) #:nodoc:
+  # Defines a new alias for attributes.
+  #
+  # Arguments:
+  # * pattern: +Regexp+
+  #   A pattern that will be matched against attributes when looking for
+  #   aliases. Contents captured in the pattern can be used in the alias.
+  # * replace: +String+
+  #   The alias that results from the matched pattern. Captured strings can
+  #   be substituded like with +String#sub+.
+  #
+  # Example:
+  #   
+  #   Factory.alias /(.*)_confirmation/, '\1'
+  #
+  # factory_girl starts with aliases for foreign keys, so that a :user
+  # association can be overridden by a :user_id parameter:
+  #
+  #   Factory.define :post do |p|
+  #     p.association :user
+  #   end
+  #
+  #   # The user association will not be built in this example. The user_id
+  #   # will be used instead.
+  #   Factory(:post, :user_id => 1)
+  def self.alias (pattern, replace)
+    self.aliases << [pattern, replace]
+  end
+
+  def self.aliases_for (attribute) #:nodoc:
     aliases.collect do |params|
       pattern, replace = *params
       if pattern.match(attribute.to_s)
@@ -18,4 +46,5 @@ module FactoryGirl
       end
     end.compact << attribute
   end
+
 end

data/lib/factory_girl/attribute/association.rb

@@ -1,4 +1,4 @@
-module FactoryGirl
+class Factory
   class Attribute #:nodoc:
 
     class Association < Attribute  #:nodoc:

data/lib/factory_girl/attribute/callback.rb

@@ -1,4 +1,4 @@
-module FactoryGirl
+class Factory
   class Attribute #:nodoc:
 
     class Callback < Attribute  #:nodoc:

data/lib/factory_girl/attribute/dynamic.rb

@@ -1,4 +1,4 @@
-module FactoryGirl
+class Factory
   class Attribute #:nodoc:
 
     class Dynamic < Attribute  #:nodoc:
@@ -8,8 +8,8 @@ module FactoryGirl
       end
 
       def add_to(proxy)
-        value = @block.arity == 1 ? @block.call(proxy) : proxy.instance_eval(&@block)
-        if FactoryGirl::Sequence === value
+        value = @block.arity.zero? ? @block.call : @block.call(proxy)
+        if Factory::Sequence === value
           raise SequenceAbuseError
         end
         proxy.set(name, value)

data/lib/factory_girl/attribute/static.rb

@@ -1,4 +1,4 @@
-module FactoryGirl
+class Factory
   class Attribute #:nodoc:
 
     class Static < Attribute  #:nodoc:

data/lib/factory_girl/attribute.rb

@@ -1,4 +1,4 @@
-module FactoryGirl
+class Factory
 
   # Raised when defining an invalid attribute:
   # * Defining an attribute which has a name ending in "="
@@ -6,7 +6,7 @@ module FactoryGirl
   # * Defining an attribute twice in the same factory
   class AttributeDefinitionError < RuntimeError
   end
-
+  
   class Attribute #:nodoc:
 
     attr_reader :name
@@ -16,7 +16,7 @@ module FactoryGirl
 
       if @name.to_s =~ /=$/
         attribute_name = $`
-        raise AttributeDefinitionError,
+        raise AttributeDefinitionError, 
           "factory_girl uses 'f.#{attribute_name} value' syntax " +
           "rather than 'f.#{attribute_name} = value'"
       end

data/lib/factory_girl/factory.rb

@@ -1,215 +1,405 @@
-module FactoryGirl
+class Factory
+
+  # Raised when a factory is defined that attempts to instantiate itself.
+  class AssociationDefinitionError < RuntimeError
+  end
+  
+  # Raised when a callback is defined that has an invalid name
+  class InvalidCallbackNameError < RuntimeError
+  end
+  
   class << self
     attr_accessor :factories #:nodoc:
+
+    # An Array of strings specifying locations that should be searched for
+    # factory definitions. By default, factory_girl will attempt to require
+    # "factories," "test/factories," and "spec/factories." Only the first
+    # existing file will be loaded.
+    attr_accessor :definition_file_paths
   end
 
   self.factories = {}
+  self.definition_file_paths = %w(factories test/factories spec/factories)
+
+  attr_reader :factory_name #:nodoc:
+  attr_reader :attributes #:nodoc:
+
+  # Defines a new factory that can be used by the build strategies (create and
+  # build) to build new objects.
+  #
+  # Arguments:
+  # * name: +Symbol+ or +String+
+  #   A unique name used to identify this factory.
+  # * options: +Hash+
+  #
+  # Options:
+  # * class: +Symbol+, +Class+, or +String+
+  #   The class that will be used when generating instances for this factory. If not specified, the class will be guessed from the factory name.
+  # * parent: +Symbol+
+  #   The parent factory. If specified, the attributes from the parent
+  #   factory will be copied to the current one with an ability to override
+  #   them.
+  # * default_strategy: +Symbol+
+  #   The strategy that will be used by the Factory shortcut method.
+  #   Defaults to :create.
+  #
+  # Yields: +Factory+
+  # The newly created factory.
+  def self.define (name, options = {})
+    instance = Factory.new(name, options)
+    yield(instance)
+    if parent = options.delete(:parent)
+      instance.inherit_from(Factory.factory_by_name(parent))
+    end    
+    self.factories[instance.factory_name] = instance
+  end
+  
+  def class_name #:nodoc:
+    @options[:class] || factory_name
+  end
 
-  def self.factory_by_name(name)
-    factories[name.to_sym] or raise ArgumentError.new("No such factory: #{name.to_s}")
+  def build_class #:nodoc:
+    @build_class ||= class_for(class_name)
+  end
+  
+  def default_strategy #:nodoc:
+    @options[:default_strategy] || :create
   end
 
-  def self.register_factory(factory, options = {})
-    if options[:as]
-      name = options[:as]
-    else
-      name = factory.name
-      factory.aliases.each do |alias_name|
-        register_factory(factory, :as => alias_name)
+  def initialize (name, options = {}) #:nodoc:
+    assert_valid_options(options)
+    @factory_name = factory_name_for(name)
+    @options      = options      
+    @attributes   = []
+    @params       = []
+  end
+  
+  def inherit_from(parent) #:nodoc:
+    @options[:class] ||= parent.class_name
+    parent.attributes.each do |attribute|
+      unless attribute_defined?(attribute.name)
+        @attributes << attribute.clone
       end
     end
+  end
 
-    if self.factories[name]
-      raise DuplicateDefinitionError, "Factory already defined: #{name}"
+  # Adds an attribute that should be assigned on generated instances for this
+  # factory.
+  #
+  # This method should be called with either a value or block, but not both. If
+  # called with a block, the attribute will be generated "lazily," whenever an
+  # instance is generated. Lazy attribute blocks will not be called if that
+  # attribute is overriden for a specific instance.
+  #
+  # When defining lazy attributes, an instance of Factory::Proxy will
+  # be yielded, allowing associations to be built using the correct build
+  # strategy.
+  #
+  # Arguments:
+  # * name: +Symbol+ or +String+
+  #   The name of this attribute. This will be assigned using :"#{name}=" for
+  #   generated instances.
+  # * value: +Object+
+  #   If no block is given, this value will be used for this attribute.
+  def add_attribute (name, value = nil, &block)
+    if block_given?
+      if value
+        raise AttributeDefinitionError, "Both value and block given"
+      else
+        attribute = Attribute::Dynamic.new(name, block)
+      end
+    else
+      attribute = Attribute::Static.new(name, value)
     end
 
-    self.factories[name] = factory
-  end
-
-  # Raised when a factory is defined that attempts to instantiate itself.
-  class AssociationDefinitionError < RuntimeError
-  end
+    if attribute_defined?(attribute.name)
+      raise AttributeDefinitionError, "Attribute already defined: #{name}"
+    end
 
-  # Raised when a callback is defined that has an invalid name
-  class InvalidCallbackNameError < RuntimeError
+    @attributes << attribute
   end
 
-  # Raised when a factory is defined with the same name as a previously-defined factory.
-  class DuplicateDefinitionError < RuntimeError
+  # Calls add_attribute using the missing method name as the name of the
+  # attribute, so that:
+  #
+  #   Factory.define :user do |f|
+  #     f.name 'Billy Idol'
+  #   end
+  #
+  # and:
+  #
+  #   Factory.define :user do |f|
+  #     f.add_attribute :name, 'Billy Idol'
+  #   end
+  #
+  # are equivilent. 
+  def method_missing (name, *args, &block)
+    add_attribute(name, *args, &block)
   end
 
-  class Factory
-    attr_reader :name #:nodoc:
-    attr_reader :attributes #:nodoc:
-
-    def factory_name
-      puts "WARNING: factory.factory_name is deprecated. Use factory.name instead."
-      name
-    end
-
-    def class_name #:nodoc:
-      @options[:class] || name
+  # Adds an attribute that builds an association. The associated instance will
+  # be built using the same build strategy as the parent instance.
+  #
+  # Example:
+  #   Factory.define :user do |f|
+  #     f.name 'Joey'
+  #   end
+  #
+  #   Factory.define :post do |f|
+  #     f.association :author, :factory => :user
+  #   end
+  #
+  # Arguments:
+  # * name: +Symbol+
+  #   The name of this attribute.
+  # * options: +Hash+
+  #
+  # Options:
+  # * factory: +Symbol+ or +String+
+  #    The name of the factory to use when building the associated instance.
+  #    If no name is given, the name of the attribute is assumed to be the
+  #    name of the factory. For example, a "user" association will by
+  #    default use the "user" factory.
+  def association (name, options = {})
+    factory_name = options.delete(:factory) || name
+    if factory_name_for(factory_name) == self.factory_name
+      raise AssociationDefinitionError, "Self-referencing association '#{name}' in factory '#{self.factory_name}'"
     end
+    @attributes << Attribute::Association.new(name, factory_name, options)
+  end
 
-    def build_class #:nodoc:
-      @build_class ||= class_for(class_name)
+  # Adds an attribute that will have unique values generated by a sequence with
+  # a specified format.
+  #
+  # The result of:
+  #   Factory.define :user do |f|
+  #    f.sequence(:email) { |n| "person#{n}@example.com" }
+  #   end
+  #
+  # Is equal to:
+  #   Factory.sequence(:email) { |n| "person#{n}@example.com" }
+  #
+  #   Factory.define :user do |f|
+  #    f.email { Factory.next(:email) }
+  #   end
+  #
+  # Except that no globally available sequence will be defined.
+  def sequence (name, &block)
+    s = Sequence.new(&block)
+    add_attribute(name) { s.next }
+  end
+  
+  def param(name)
+    @params << name
+  end
+  
+  def after_build(&block)
+    callback(:after_build, &block)
+  end
+  
+  def after_create(&block)
+    callback(:after_create, &block)
+  end
+  
+  def after_stub(&block)
+    callback(:after_stub, &block)
+  end
+  
+  def callback(name, &block)
+    unless [:after_build, :after_create, :after_stub].include?(name.to_sym)
+      raise InvalidCallbackNameError, "#{name} is not a valid callback name. Valid callback names are :after_build, :after_create, and :after_stub"
     end
+    @attributes << Attribute::Callback.new(name.to_sym, block)
+  end
+  
+  # Generates and returns a Hash of attributes from this factory. Attributes
+  # can be individually overridden by passing in a Hash of attribute => value
+  # pairs.
+  #
+  # Arguments:
+  # * name: +Symbol+ or +String+
+  #   The name of the factory that should be used.
+  # * overrides: +Hash+
+  #   Attributes to overwrite for this set.
+  #
+  # Returns: +Hash+
+  # A set of attributes that can be used to build an instance of the class
+  # this factory generates. 
+  def self.attributes_for (name, overrides = {})
+    factory_by_name(name).run(Proxy::AttributesFor, overrides)
+  end
 
-    def default_strategy #:nodoc:
-      @options[:default_strategy] || :create
-    end
+  # Generates and returns an instance from this factory. Attributes can be
+  # individually overridden by passing in a Hash of attribute => value pairs.
+  #
+  # Arguments:
+  # * name: +Symbol+ or +String+
+  #   The name of the factory that should be used.
+  # * overrides: +Hash+
+  #   Attributes to overwrite for this instance.
+  #
+  # Returns: +Object+
+  # An instance of the class this factory generates, with generated attributes
+  # assigned.
+  def self.build (name, overrides = {})
+    factory_by_name(name).run(Proxy::Build, overrides)
+  end
 
-    def initialize(name, options = {}) #:nodoc:
-      assert_valid_options(options)
-      @name       = factory_name_for(name)
-      @options    = options
-      @attributes = []
-    end
+  # Generates, saves, and returns an instance from this factory. Attributes can
+  # be individually overridden by passing in a Hash of attribute => value
+  # pairs.
+  #
+  # Instances are saved using the +save!+ method, so ActiveRecord models will
+  # raise ActiveRecord::RecordInvalid exceptions for invalid attribute sets.
+  #
+  # Arguments:
+  # * name: +Symbol+ or +String+
+  #   The name of the factory that should be used.
+  # * overrides: +Hash+
+  #   Attributes to overwrite for this instance.
+  #
+  # Returns: +Object+
+  # A saved instance of the class this factory generates, with generated
+  # attributes assigned.
+  def self.create (name, overrides = {})
+    factory_by_name(name).run(Proxy::Create, overrides)
+  end
+  
+  # Generates and returns an object with all attributes from this factory
+  # stubbed out. Attributes can be individually overridden by passing in a Hash
+  # of attribute => value pairs.
+  #
+  # Arguments:
+  # * name: +Symbol+ or +String+
+  #   The name of the factory that should be used.
+  # * overrides: +Hash+
+  #   Attributes to overwrite for this instance.
+  #
+  # Returns: +Object+
+  # An object with generated attributes stubbed out.
+  def self.stub (name, overrides = {})
+    factory_by_name(name).run(Proxy::Stub, overrides)
+  end
+  
+  # Executes the default strategy for the given factory. This is usually create,
+  # but it can be overridden for each factory.
+  #
+  # Arguments:
+  # * name: +Symbol+ or +String+
+  #   The name of the factory that should be used.
+  # * overrides: +Hash+
+  #   Attributes to overwrite for this instance.
+  #
+  # Returns: +Object+
+  # The result of the default strategy.
+  def self.default_strategy (name, overrides = {})  
+    self.send(factory_by_name(name).default_strategy, name, overrides)
+  end
 
-    def inherit_from(parent) #:nodoc:
-      @options[:class]            ||= parent.class_name
-      @options[:default_strategy] ||= parent.default_strategy
+  def self.find_definitions #:nodoc:
+    definition_file_paths.each do |path|
+      require("#{path}.rb") if File.exists?("#{path}.rb")
 
-      new_attributes = []
-      parent.attributes.each do |attribute|
-        unless attribute_defined?(attribute.name)
-          new_attributes << attribute.clone
+      if File.directory? path
+        Dir[File.join(path, '*.rb')].each do |file|
+          require file
         end
       end
-      @attributes.unshift *new_attributes
-    end
-
-    def define_attribute(attribute)
-      name = attribute.name
-      # TODO: move these checks into Attribute
-      if attribute_defined?(name)
-        raise AttributeDefinitionError, "Attribute already defined: #{name}"
-      end
-      if attribute.respond_to?(:factory) && attribute.factory == self.name
-        raise AssociationDefinitionError, "Self-referencing association '#{name}' in factory '#{self.name}'"
-      end
-      @attributes << attribute
     end
+  end
 
-    def add_callback(name, &block)
-      unless [:after_build, :after_create, :after_stub].include?(name.to_sym)
-        raise InvalidCallbackNameError, "#{name} is not a valid callback name. Valid callback names are :after_build, :after_create, and :after_stub"
-      end
-      @attributes << Attribute::Callback.new(name.to_sym, block)
+  def run (proxy_class, overrides) #:nodoc:
+    proxy = proxy_class.new(build_class)
+    overrides = symbolize_keys(overrides)
+    overrides = overrides.delete_if do |attr, val|
+      attr_is_param = @params.include?(attr)
+      proxy.set_param(attr,val) if attr_is_param
+      attr_is_param
     end
-
-    def run (proxy_class, overrides) #:nodoc:
-      proxy = proxy_class.new(build_class)
-      overrides = symbolize_keys(overrides)
-      overrides.each {|attr, val| proxy.set(attr, val) }
-      passed_keys = overrides.keys.collect {|k| FactoryGirl.aliases_for(k) }.flatten
-      @attributes.each do |attribute|
-        unless passed_keys.include?(attribute.name)
-          attribute.add_to(proxy)
-        end
+    overrides.each {|attr, val| proxy.set(attr, val) }
+    passed_keys = overrides.keys.collect {|k| Factory.aliases_for(k) }.flatten
+    @attributes.each do |attribute|
+      unless passed_keys.include?(attribute.name)
+        attribute.add_to(proxy)
       end
-      proxy.result
     end
+    proxy.result
+  end
 
-    def human_name(*args, &block)
-      name.to_s.gsub('_', ' ')
-    end
+  def self.factory_by_name (name)
+    factories[name.to_sym] or raise ArgumentError.new("No such factory: #{name.to_s}")
+  end
 
-    def associations
-      attributes.select {|attribute| attribute.is_a?(Attribute::Association) }
+  def human_name(*args, &block)
+    if args.size == 0 && block.nil?
+      factory_name.to_s.gsub('_', ' ')
+    else
+      add_attribute(:human_name, *args, &block)
     end
+  end
 
-    # Alternate names for this factory.
-    #
-    # Example:
-    #
-    #   factory :user, :aliases => [:author] do
-    #     # ...
-    #   end
-    #
-    #   Factory(:author).class
-    #   # => User
-    #
-    # Because an attribute defined without a value or block will build an
-    # association with the same name, this allows associations to be defined
-    # without factories, such as:
-    #
-    #   factory :user, :aliases => [:author] do
-    #     # ...
-    #   end
-    #
-    #   factory :post do
-    #     author
-    #   end
-    #
-    #   Factory(:post).author.class
-    #   # => User
-    def aliases
-      @options[:aliases] || []
-    end
+  def associations
+    attributes.select {|attribute| attribute.is_a?(Attribute::Association) }
+  end
 
-    private
+  private
 
-    def class_for (class_or_to_s)
-      if class_or_to_s.respond_to?(:to_sym)
-        class_name = variable_name_to_class_name(class_or_to_s)
-        class_name.split('::').inject(Object) do |object, string|
-          object.const_get(string)
-        end
-      else
-        class_or_to_s
-      end
+  def class_for (class_or_to_s)
+    if class_or_to_s.respond_to?(:to_sym)
+      Object.const_get(variable_name_to_class_name(class_or_to_s))
+    else
+      class_or_to_s
     end
+  end
 
-    def factory_name_for(class_or_to_s)
-      if class_or_to_s.respond_to?(:to_sym)
-        class_or_to_s.to_sym
-      else
-        class_name_to_variable_name(class_or_to_s).to_sym
-      end
+  def factory_name_for (class_or_to_s)
+    if class_or_to_s.respond_to?(:to_sym)
+      class_or_to_s.to_sym
+    else
+      class_name_to_variable_name(class_or_to_s).to_sym
     end
+  end
 
-    def attribute_defined? (name)
-      !@attributes.detect {|attr| attr.name == name && !attr.is_a?(Attribute::Callback) }.nil?
-    end
+  def attribute_defined? (name)
+    !@attributes.detect {|attr| attr.name == name && !attr.is_a?(Factory::Attribute::Callback) }.nil?
+  end
 
-    def assert_valid_options(options)
-      invalid_keys = options.keys - [:class, :parent, :default_strategy, :aliases]
-      unless invalid_keys == []
-        raise ArgumentError, "Unknown arguments: #{invalid_keys.inspect}"
-      end
-      assert_valid_strategy(options[:default_strategy]) if options[:default_strategy]
+  def assert_valid_options(options)
+    invalid_keys = options.keys - [:class, :parent, :default_strategy] 
+    unless invalid_keys == []
+      raise ArgumentError, "Unknown arguments: #{invalid_keys.inspect}"
     end
-
-    def assert_valid_strategy(strategy)
-      unless Proxy.const_defined? variable_name_to_class_name(strategy)
-        raise ArgumentError, "Unknown strategy: #{strategy}"
-      end
+    assert_valid_strategy(options[:default_strategy]) if options[:default_strategy]
+  end
+  
+  def assert_valid_strategy(strategy)
+    unless Factory::Proxy.const_defined? variable_name_to_class_name(strategy)
+      raise ArgumentError, "Unknown strategy: #{strategy}"
     end
+  end
 
-    # Based on ActiveSupport's underscore inflector
-    def class_name_to_variable_name(name)
-      name.to_s.gsub(/::/, '/').
-        gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
-        gsub(/([a-z\d])([A-Z])/,'\1_\2').
-        tr("-", "_").
-        downcase
-    end
+  # Based on ActiveSupport's underscore inflector
+  def class_name_to_variable_name(name)
+    name.to_s.gsub(/::/, '/').
+      gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+      gsub(/([a-z\d])([A-Z])/,'\1_\2').
+      tr("-", "_").
+      downcase
+  end
 
-    # Based on ActiveSupport's camelize inflector
-    def variable_name_to_class_name(name)
-      name.to_s.
-        gsub(/\/(.?)/) { "::#{$1.upcase}" }.
-        gsub(/(?:^|_)(.)/) { $1.upcase }
-    end
+  # Based on ActiveSupport's camelize inflector
+  def variable_name_to_class_name(name)
+    name.to_s.
+      gsub(/\/(.?)/) { "::#{$1.upcase}" }.
+      gsub(/(?:^|_)(.)/) { $1.upcase }
+  end
 
-    # From ActiveSupport
-    def symbolize_keys(hash)
-      hash.inject({}) do |options, (key, value)|
-        options[(key.to_sym rescue key) || key] = value
-        options
-      end
+  # From ActiveSupport
+  def symbolize_keys(hash)
+    hash.inject({}) do |options, (key, value)|
+      options[(key.to_sym rescue key) || key] = value
+      options
     end
-
   end
+
 end