rahoulb-object-factory 0.1.0

data/README.rdoc

@@ -0,0 +1,40 @@
+= Object-factory
+
+A ruby gem designed to make it simple to create test objects within your test framework, so you don't need to use nasty fixtures.  
+
+If you don't use the a_saved method then it should work with any type of model, if you do use a_saved then it will work with any model that has a save method (that returns false on failure - so ActiveRecord and DataMapper should be OK).  
+
+== Install
+
+  gem install rahoulb-object-factory --source http://gems.github.com/
+  
+== Usage
+
+See the wiki page at http://github.com/rahoulb/object-factory/wikis/home for the latest docs.  
+
+However, it works something like this: 
+
+  Object.factory.when_creating_a Person, :auto_generate => :employee_code
+ 
+  @person = a Person, :first_name => 'John', :last_name => 'Smith', :employee_code => '12345'
+  puts @person.employee_code # will show 12345
+  
+And your options are: 
+
+* :auto_generate => [:field1, :field2]: generates a unique string value for the given field name or array of field names
+* :auto_confirm => :password: generates a unique string value for the given field name or array of field names and also sets field_name_confirmation to the same value
+* :generate_email_address => :email: generates a randomised email address for the given field name or array of field names
+* :set => { :field3 => 'value3', :field4 => 'value4' }: sets the given fields to the supplied static values
+* :generate => { :field5 => lambda { Date.today } }: sets the given fields to the supplied dynamic values
+
+== Released under the MIT Licence
+
+Copyright (c) 2008 Brightbox Systems Ltd 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+* The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+See http://www.brightbox.co.uk/ for contact details.  

data/Rakefile

@@ -0,0 +1,17 @@
+require 'rubygems'
+require 'rake'
+require 'echoe'
+
+Echoe.new('object-factory', '0.1.0') do | config | 
+  config.description = 'A simple object factory to help you build valid objects in your tests'
+  config.url = 'http://github.com/rahoub/object-factory'
+  config.author = 'Brightbox Systems Ltd'
+  config.email = 'hello@brightbox.co.uk'
+  config.ignore_pattern = ['tmp/*', 'script/*']
+  config.dependencies = ['rahoulb-rujitsu']
+  config.development_dependencies = []
+end
+
+Dir["#{File.dirname(__FILE__)}/tasks/*.rake"].sort.each do | rake_file | 
+  load rake_file
+end

data/lib/object_factory.rb

@@ -0,0 +1,167 @@
+require 'rubygems'
+require 'rujitsu'
+
+class Object
+  # return an instance of an Object::Factory
+  def self.factory
+    @@object_factory ||= Factory.new
+  end
+  
+  # Factory allows test suites to build new instances of objects, specifying some simple constraints on certain fields
+  # If a new instance is created via the factory then that instance can have specialist values automatically applied to given fields, meaning that it should be possible for test cases to build valid objects without having to specify a full valid field-set
+  # The factory should not be created directly, but instead accessed through the Object#factory method.  
+  # Expected usage: 
+  #   Object.factory.configure Person, :auto_generate => [:email, :telephone], :auto_confirm => :password
+  #   instance = a Person
+  # instance will have a unique value for :email and :telephone and will ensure that :password and :password_confirmation have the same value.  
+  class Factory
+    attr_accessor :generator
+    
+    def initialize
+      reset
+    end
+
+    # Set this factory back to its pristine state, with no objects configured
+    def reset
+      @confirmed_fields = {}
+      @generators = {}
+    end
+  
+    # Create a new instance of the given class with the given parameters and apply the auto-generated fields, according to the configured rules
+    def create_a klass, parameters = {}
+      instance = klass.new parameters
+      
+      generate_confirmations_for instance, parameters
+      generate_values_for instance, parameters
+      
+      return instance
+    end
+    
+    # Create a new instance of the given class with the given parameters, auto-generate the field values and then call save!
+    def create_and_save_a klass, parameters = {}
+      instance = create_a klass, parameters
+      raise CannotSaveError unless instance.save
+      return instance
+    end
+    
+    # Set up the required auto-generated fields for the given class.  
+    #   Object.factory.when_creating_a MyClass, :auto_generate => [:field1, :field2], :auto_confirm => :password, :generate_email_address => :email_address, :set => { :field3 => 'value3', :field4 => 'value4' }, :generator => { :field5 => lambda {Date.today}, :field6 => lambda {Time.now} }
+    # Options are: 
+    # * :auto_generate specifies a field name or array of field names that are to have unique string values assigned to them
+    # * :auto_confirm specifies a field name or array of field names that are to be set to a unique value; with the same value being assigned to field_name_confirmation
+    # * :generate_email_address specifies a field name or array of field names that are set to be randomised email addresses
+    # * :set specifies a Hash of field names and fixed values
+    # * :generate specifies a Hash of field names and lambdas that are used to generate a dynamic value
+    def when_creating_a klass, options = {}
+      need_to_generate_values_for klass, options[:auto_generate] unless options[:auto_generate].nil?
+      need_to_confirm_values_for klass, options[:auto_confirm] unless options[:auto_confirm].nil? 
+      need_to_generate_email_addresses_for klass, options[:generate_email_address] unless options[:generate_email_address].nil? 
+      need_to_set_values_for klass, options[:set] unless options[:set].nil? 
+      need_to_set_generators_for klass, options[:generate] unless options[:generate].nil?
+    end
+    
+    alias :when_creating_an :when_creating_a
+    alias :create_and_save_an :create_and_save_a
+
+    # An Object::Factory::ValueGenerator that is used to actually build the unique values used to populate the required fields
+    def generator
+      @generator ||= ValueGenerator.new
+    end
+    
+    # A simple class that generates unique values
+    class ValueGenerator
+      def initialize
+        @counter = 0
+      end
+      
+      def unique_integer
+        @counter += 1
+      end
+      
+      def value_for klass, field
+        "#{klass.name.to_s}-#{field.to_s}-#{unique_integer}"
+      end
+    end
+    
+    #�Error raised when create_and_save_a cannot save the object
+    class CannotSaveError < RuntimeError; end
+    
+    private
+      
+    def symbol_for object
+      klass = object.is_a?(Class) ? object : object.class
+      return klass.name.to_sym
+    end
+    
+    def need_to_generate_values_for klass, fields
+      fields = [fields] unless fields.respond_to?(:each)
+      fields.each do | field | 
+        add_generator_for klass, field, lambda { generator.value_for(klass, field) }
+      end
+    end
+    
+    def need_to_confirm_values_for klass, fields
+      fields = [fields] unless fields.respond_to?(:each)
+      @confirmed_fields[symbol_for(klass)] = fields
+    end
+    
+    def need_to_generate_email_addresses_for klass, fields
+      fields = [fields] unless fields.respond_to?(:each)
+      fields.each do | field |
+        add_generator_for klass, field, lambda { 6.random_letters + '@' +  10.random_letters + '.com' }
+      end
+    end
+    
+    def need_to_set_values_for klass, fields_and_values
+      fields_and_values.each do | field, value | 
+        add_generator_for klass, field, lambda { value }
+      end
+    end
+
+    def add_generator_for klass, field, generator
+      @generators[symbol_for(klass)] ||= {}
+      @generators[symbol_for(klass)][field] = generator
+    end
+    
+    def need_to_set_generators_for klass, fields_and_generators
+      fields_and_generators.each do | field, generator |
+        add_generator_for klass, field, generator
+      end
+    end
+    
+    def generate_confirmations_for instance, parameters
+      field_names = @confirmed_fields[symbol_for(instance)]
+      return if field_names.nil? 
+      field_names.each do | field_name |
+        confirmation_field_name = "#{field_name}_confirmation"
+        value = generator.value_for(instance.class, field_name)
+        instance.send("#{field_name.to_s}=".to_sym, value) unless parameters.has_key?(field_name.to_sym)
+        instance.send("#{confirmation_field_name.to_s}=".to_sym, value) unless parameters.has_key?(confirmation_field_name.to_sym)
+      end
+    end
+    
+    def generate_values_for instance, parameters
+      fields_and_generators = @generators[symbol_for(instance)]
+      return if fields_and_generators.nil?
+      fields_and_generators.each do | field_name, proc | 
+        value = proc.call
+        instance.send("#{field_name.to_sym}=".to_sym, value) unless parameters.has_key?(field_name.to_sym)
+      end
+    end
+  end
+end
+
+# Short-cut method for Object::Factory#create_a
+# Also aliased as an, for class names that start with a vowel.  
+#   instance = a Thingy
+#   another_instance = an OtherThingy
+def a klass, parameters = {}
+  Object.factory.create_a klass, parameters
+end
+
+alias an a
+
+# Short-cut method for Object::Factory#create_and_save_a
+def a_saved klass, parameters = {}
+  Object.factory.create_and_save_a klass, parameters
+end

data/object-factory.gemspec

@@ -0,0 +1,34 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{object-factory}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Brightbox Systems Ltd"]
+  s.date = %q{2008-11-24}
+  s.description = %q{A simple object factory to help you build valid objects in your tests}
+  s.email = %q{hello@brightbox.co.uk}
+  s.extra_rdoc_files = ["lib/object_factory.rb", "README.rdoc", "tasks/rspec.rake"]
+  s.files = ["lib/object_factory.rb", "Manifest", "object-factory.gemspec", "Rakefile", "README.rdoc", "spec/object_spec.rb", "spec/spec.opts", "tasks/rspec.rake"]
+  s.has_rdoc = true
+  s.homepage = %q{http://github.com/rahoub/object-factory}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Object-factory", "--main", "README.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{object-factory}
+  s.rubygems_version = %q{1.3.1}
+  s.summary = %q{A simple object factory to help you build valid objects in your tests}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<rahoulb-rujitsu>, [">= 0"])
+    else
+      s.add_dependency(%q<rahoulb-rujitsu>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<rahoulb-rujitsu>, [">= 0"])
+  end
+end

data/spec/object_spec.rb

@@ -0,0 +1,271 @@
+require File.expand_path(File.dirname(__FILE__) + '/../lib/object_factory.rb')
+
+class TestClass
+  attr_accessor :field, :another_field, :password, :password_confirmation, :other, :other_confirmation
+  def initialize parameters = nil
+    self.field = parameters[:field]
+    self.another_field = parameters[:another_field]
+    self.password = parameters[:password]
+    self.password_confirmation = parameters[:password_confirmation]
+  end
+end
+
+class AnotherTestClass
+
+end
+
+describe Object, "with RSpec/Rails extensions" do
+  describe "accessing the factory" do
+    it "should return an object factory" do
+      Object.factory.class.should == Object::Factory
+    end
+    
+    it "should use a single instance" do
+      @first_factory = Object.factory
+      @second_factory = Object.factory
+      
+      @first_factory.should == @second_factory
+    end
+  end
+end
+
+describe Object::Factory::ValueGenerator do
+  it "should generate a unique string value for a given class and field" do
+    @generator = Object::Factory::ValueGenerator.new
+
+    @value = @generator.value_for TestClass, :field
+    @value.should match(/TestClass\-field\-(\d+)/)
+  end
+  
+  it "should generate a unique integer value" do
+    @generator = Object::Factory::ValueGenerator.new
+  
+    @first_value = @generator.unique_integer
+    @second_value = @generator.unique_integer
+    
+    @first_value.should_not == @second_value
+  end
+  
+end
+
+describe Object::Factory, "creating simple instances" do
+
+  before :each do 
+    Object.factory.reset 
+  end
+
+  it "should create an instance of the given class with no provided parameters" do
+    @test_instance = mock('Test Instance')
+    TestClass.should_receive(:new).with({}).and_return(@test_instance)
+    
+    @created_instance = Object.factory.create_a(TestClass)
+    @created_instance.should == @test_instance
+  end
+  
+  it "should create an instance of the given class with the given parameters" do
+    @test_instance = mock('Test Instance')
+    TestClass.should_receive(:new).with({:some => :values}).and_return(@test_instance)
+    
+    @created_instance = Object.factory.create_a(TestClass, :some => :values)
+    @created_instance.should == @test_instance
+  end
+  
+  it "should allow 'a' as a short-cut to creating objects" do
+    @test_instance = mock('Test Instance')
+    TestClass.should_receive(:new).with({}).and_return(@test_instance)
+
+    @created_instance = a TestClass
+    @created_instance.should == @test_instance
+  end
+  
+  it "should allow 'an' as a short-cut to creating objects" do
+    @test_instance = mock('Test Instance')
+    AnotherTestClass.should_receive(:new).with({}).and_return(@test_instance)
+
+    @created_instance = an AnotherTestClass
+    @created_instance.should == @test_instance
+  end
+  
+  it "should auto-save the created object" do
+    @test_instance = mock('Test Instance')
+    TestClass.should_receive(:new).with({:some => :values}).and_return(@test_instance)
+    @test_instance.should_receive(:save).and_return(true)
+    
+    @created_instance = Object.factory.create_and_save_a(TestClass, :some => :values)
+  end
+  
+  it "should raise an exception if the auto-saved object cannot be saved" do
+    @test_instance = mock('Test Instance')
+    TestClass.should_receive(:new).with({:some => :values}).and_return(@test_instance)
+    @test_instance.should_receive(:save).and_return(false)
+    
+    lambda { 
+      Object.factory.create_and_save_a(TestClass, :some => :values)
+    }.should raise_error(Object::Factory::CannotSaveError)
+  end
+
+  it "should allow 'a_saved' as a short-cut to creating and saving an object" do
+    @test_instance = mock('Test Instance')
+    TestClass.should_receive(:new).with({:some => :values}).and_return(@test_instance)
+    @test_instance.should_receive(:save).and_return(true)
+    
+    @created_instance = a_saved(TestClass, :some => :values)
+  end
+end
+  
+describe Object::Factory, "creating instances with generated values" do
+  
+  before :each do 
+    Object.factory.reset 
+  end
+
+  it "should auto-generate a unique value for a configured field" do
+    Object.factory.generator.should_receive(:value_for).with(TestClass, :field).and_return("TestClass-field-1")
+
+    Object.factory.when_creating_a TestClass, :auto_generate => :field
+    @instance = Object.factory.create_a TestClass
+    @instance.field.should == 'TestClass-field-1'
+  end
+  
+  it "should auto-generate unique values for multiple configured fields" do
+    Object.factory.generator.should_receive(:value_for).with(TestClass, :field).and_return("TestClass-field-1")
+    Object.factory.generator.should_receive(:value_for).with(TestClass, :another_field).and_return("TestClass-another_field-1")
+
+    Object.factory.when_creating_a TestClass, :auto_generate => [:field, :another_field]
+
+    @instance = Object.factory.create_a TestClass
+    @instance.field.should match(/TestClass-field-(\d+)/)
+    @instance.another_field.should match(/TestClass-another_field-(\d+)/)
+  end
+  
+  it "should allow you to override generated values" do
+    Object.factory.when_creating_a TestClass, :auto_generate => :field
+
+    @instance = Object.factory.create_a TestClass, :field => 'My Override Value'
+    @instance.field.should == 'My Override Value'
+  end
+
+  it "should allow you to override generated values with nils" do
+    Object.factory.when_creating_a TestClass, :auto_generate => :field
+
+    @instance = Object.factory.create_a TestClass, :field => nil
+    @instance.field.should be_nil
+  end
+end
+
+describe Object::Factory, "creating instances with confirmed values" do
+
+  before :each do 
+    Object.factory.reset 
+  end
+
+  it "should auto-generate a unique value for a configured field and its confirmation field" do
+    Object.factory.generator.should_receive(:value_for).with(TestClass, :password).and_return("TestClass-password-1")
+
+    Object.factory.when_creating_a TestClass, :auto_confirm => :password
+
+    @instance = Object.factory.create_a TestClass
+    @instance.password.should == 'TestClass-password-1'
+    @instance.password_confirmation.should == @instance.password
+  end
+
+  it "should auto-generate unique values for multiple configured fields and confirmation fields" do
+    Object.factory.generator.should_receive(:value_for).with(TestClass, :password).and_return("TestClass-password-1")
+    Object.factory.generator.should_receive(:value_for).with(TestClass, :other).and_return("TestClass-other-1")
+
+    Object.factory.when_creating_a TestClass, :auto_confirm => [:password, :other]
+
+    @instance = Object.factory.create_a TestClass
+    @instance.password.should match(/TestClass-password-(\d+)/)
+    @instance.password_confirmation.should == @instance.password
+    @instance.other.should match(/TestClass-other-(\d+)/)
+    @instance.other_confirmation.should == @instance.other
+  end
+  
+  it "should allow you to override confirmed original values" do
+    Object.factory.when_creating_a TestClass, :auto_confirm => :password
+
+    @instance = Object.factory.create_a TestClass, :password => 'My Override Value'
+    @instance.password.should == 'My Override Value'
+    @instance.password_confirmation.should_not == @instance.password
+  end
+
+  it "should allow you to override confirmed confirmation fields" do
+    Object.factory.when_creating_a TestClass, :auto_confirm => :password
+
+    @instance = Object.factory.create_a TestClass, :password_confirmation => 'My Override Value'
+    @instance.password_confirmation.should == 'My Override Value'
+    @instance.password_confirmation.should_not == @instance.password
+  end
+
+  it "should allow you to override confirmed values with nils" do
+    Object.factory.when_creating_a TestClass, :auto_confirm => :password
+
+    @instance = Object.factory.create_a TestClass, :password => nil
+    @instance.password.should be_nil
+    @instance.password_confirmation.should_not == @instance.password
+  end
+
+  it "should allow you to override confirmed confirmation fields with nils" do
+    Object.factory.when_creating_a TestClass, :auto_confirm => :password
+
+    @instance = Object.factory.create_a TestClass, :password_confirmation => nil
+    @instance.password_confirmation.should be_nil
+    @instance.password_confirmation.should_not == @instance.password
+  end
+end
+
+describe Object::Factory, "setting static values" do
+  before :each do 
+    Object.factory.reset 
+  end
+
+  it "should set a static value for a configured field" do
+    Object.factory.when_creating_a TestClass, :set => { :field => 'hello' }
+    @instance = Object.factory.create_a TestClass
+    @instance.field.should == 'hello'
+  end
+  
+  it "should set static values for multiple configured fields" do
+    Object.factory.when_creating_a TestClass, :set => { :field => 'hello', :another_field => 'world' }
+
+    @instance = Object.factory.create_a TestClass
+    @instance.field.should == 'hello'
+    @instance.another_field.should == 'world'
+  end
+end
+
+describe Object::Factory, "generating email addresses" do
+  before :each do
+    Object.factory.reset
+  end
+  
+  it "should generate a random email address for a configured field" do
+    Object.factory.when_creating_a TestClass, :generate_email_address => :field
+    
+    @instance = Object.factory.create_a TestClass
+    @instance.field.should match(/(.*)@(.*)\.com/)
+  end
+
+  it "should generate random email addresses for multiple configured fields" do
+    Object.factory.when_creating_a TestClass, :generate_email_address => [:field, :another_field]
+    
+    @instance = Object.factory.create_a TestClass
+    @instance.field.should match(/(.*)@(.*)\.com/)
+    @instance.another_field.should match(/(.*)@(.*)\.com/)
+  end
+end
+
+describe Object::Factory, "using lambdas to generate values" do
+  before :each do
+    Object.factory.reset
+  end
+  
+  it "should set a lambda-generator for configured fields" do
+    Object.factory.when_creating_a TestClass, :generate => { :field => lambda { "poop" }, :another_field => lambda { Date.today.to_s } }
+    
+    @instance = Object.factory.create_a TestClass
+    @instance.field.should == 'poop'
+    @instance.another_field.should == Date.today.to_s
+  end
+end

data/spec/spec.opts

@@ -0,0 +1,4 @@
+--colour
+--format progress
+--loadby mtime
+--reverse

data/tasks/rspec.rake

@@ -0,0 +1,24 @@
+# Borrowed from http://github.com/rsim/ruby-plsql/tree/master/tasks/rspec.rake
+# Github++
+begin
+  require "spec"
+rescue LoadError
+  require "rubygems"
+  require "spec"
+end
+
+begin
+  require "spec/rake/spectask"
+rescue LoadError
+  puts <<-EOS
+To use rspec for testing you must install rspec gem:
+  [sudo] gem install rspec
+EOS
+  exit(0)
+end
+
+desc "Run the specs under spec/*"
+Spec::Rake::SpecTask.new do |t|
+  t.spec_opts = ["--options", "spec/spec.opts"]
+  t.spec_files = FileList["spec/*_spec.rb"]
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification 
+name: rahoulb-object-factory
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Brightbox Systems Ltd
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-11-24 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rahoulb-rujitsu
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: A simple object factory to help you build valid objects in your tests
+email: hello@brightbox.co.uk
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- lib/object_factory.rb
+- README.rdoc
+- tasks/rspec.rake
+files: 
+- lib/object_factory.rb
+- Manifest
+- object-factory.gemspec
+- Rakefile
+- README.rdoc
+- spec/object_spec.rb
+- spec/spec.opts
+- tasks/rspec.rake
+has_rdoc: true
+homepage: http://github.com/rahoub/object-factory
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Object-factory
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "1.2"
+  version: 
+requirements: []
+
+rubyforge_project: object-factory
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: A simple object factory to help you build valid objects in your tests
+test_files: []
+