factory_grabber 1.0.3

data/CHANGELOG

@@ -0,0 +1,14 @@
+
+Version 1.0.3
+	- Added support for virtual attributes
+
+Version 1.0.1
+	- Re-wrote README as Markdown
+
+Version 1.0.1 released Tuesday 15th September [Gavin Morrice]
+	- Removed the NumberMethods. Instead of dynamically creating a method for each number, ghost methods are 'created' using method_missing.
+	- Updated README
+	- Updated Rdoc
+	- Added support for 'a' and 'an': Grab.an_author
+	
+Version 1.0.0 released Sunday 13th September [Gavin Morrice]

data/Manifest

@@ -0,0 +1,14 @@
+CHANGELOG
+Manifest
+README.md
+Rakefile
+init.rb
+lib/dbfile
+lib/factory_grabber.rb
+lib/spec/database_setup.rb
+lib/spec/dbfile
+lib/spec/factories.rb
+lib/spec/grab_spec.rb
+lib/spec/performance_test.rb
+lib/spec/spec_helper.rb
+lib/spec/user.rb

data/README.md

@@ -0,0 +1,159 @@
+Factory Grabber
+==============
+
+Factory grabber speeds up your tests by grabbing the nearest appropriate database records to suit your needs.
+
+The idea is simple: most of the time, when using factories, you don't really care about the specific attributes, you just need a database record to play with. factory_grabber will _'grab'_ a matching record from the database if available or create any extra records if required. Less inserts to the database means faster tests.
+
+At the moment, only "factory_girl":http://github.com/thoughtbot/factory_girl by thoughtbot is supported. If you'd like to see more factories supported please let me know (gavin@handyrailstips.com)
+
+To install:
+===========
+
+
+As a gem:
+---------
+
+		sudo gem install git://github.com/GavinM/factory_grabber.git
+
+		# environment.rb
+		config.gem "thoughtbot-factory_girl", :lib => "factory_girl"
+		config.gem "factory_grbber", :version => ">=1.0.2", :lib => false
+
+As a plugin:
+------------
+		script/plugin install git://github.com/GavinM/factory_grabber.git
+		
+		
+Important:
+----------
+		
+To benefit from this gem, set use_transactional_fixtures=() to false in *spec_helper.rb*
+		
+    Spec::Runner.configure do |config|
+      config.use_transactional_fixtures = false
+			config.use_instantiated_fixtures  = false
+		  config.fixture_path = RAILS_ROOT + '/spec/fixtures/'
+    end
+
+Example Usage
+=============
+
+First, add the following line to *spec_helper.rb* or *test_helper.rb*:
+
+		require "factory_grabber"
+
+Then, in your tests/specs:
+		
+		# to grab 1 comment:
+		@comment = Grab.a_comment
+
+		# to grab 1 article:
+		@article = Grab.an_article
+
+		#to grab 4 users named "John Smith":
+		@users = Grab.four_users(:first_name => "John", :last_name => "Smith")
+
+		#to grab 73 users with standard factory attributes:
+		@users = Grab.seventy_three_users
+
+Practical examples:
+===================
+
+In a controller spec...
+		describe "GET /posts/1" do
+
+		  integrate_views
+
+		  before do
+				# will create a record with these attributes if required, if not it will find the existing record
+		  	@post = Grab.one_post :title => "This is my first post", :body => "This is the post body"
+		  end
+  
+		  def	do_get
+		  	get :show, :id => @post
+		  end
+  
+		  it "should show the post title" do
+		  	do_get
+		  	response.should include_text(/This is my first post/)
+		  end
+
+			it "should show the post body" do
+				do_get
+				response.should include_text(/This is the post body/)
+			end
+  
+		end
+
+
+		describe "GET /posts?page=1" do
+	
+			# testing pagination
+
+			integrate_views
+	
+			before do
+				# ensures there are at least eleven Post records
+				# if there are less than eleven, new posts are created
+				# if there are eleven or more no posts are created
+				Grab.eleven_posts
+			end
+	
+			def	do_get
+				get :index, :page => 1
+			end
+	
+			it "should find the latest 10 posts" do
+				do_get
+				assigns[:posts].should == Post.find(:all, :order => "created_at DESC", :limit => 10)
+			end
+
+		end
+
+At the moment, all numbers between one and ninety_nine are supported. The general syntax for Grab methods is:
+
+		Grab.[number_in_words]_[factory_name]
+
+Performance gains
+==================
+
+Here's a quick example of the possible performance gains:
+<pre>
+Rehearsal --------------------------------------------------------------
+Create 50 new factories      0.130000   0.200000   0.330000 (  6.785332)
+Grab 50 separate factories   0.320000   0.020000   0.340000 (  0.332814)
+Grab 50 factories at once    0.010000   0.000000   0.010000 (  0.012414)
+----------------------------------------------------- total: 0.680000sec
+
+                                 user     system      total        real
+Create 50 new factories      0.100000   0.200000   0.300000 (  6.354282)
+Grab 50 separate factories   0.300000   0.000000   0.300000 (  0.310373)
+Grab 50 factories at once    0.020000   0.000000   0.020000 (  0.011400)
+</pre>
+
+(These results can be produced for your own environment by running the file "performance_test.rb" in factory_grabber/lib/spec/performance_test.rb)
+
+Known Issues
+============
+
+At the moment, existing factories are found calling the model name. If your factory names do not match the name of the models then new factories will be created each time.
+eg.
+
+		Factory(:admin_user, :class => :user) do |f|
+		  f.username("admin_user")
+			f.admin(true)
+			# ... etc ...
+		end
+
+		Grab.an_admin_user # => will not find records from the database.
+
+Feedback
+========
+
+This project is still an infant - if the Ruby community find it useful I plan on adding a lot more. Please send any ideas/feedback to gavin@handyrailstips.com
+
+
+Free to upload, edit, share, fork etc.<br />
+[Gavin Morrice](http://gavinmorrice.com)<br />
+[www.handyrailstips.com](:http://handyrailstips.com/tips/20)

data/Rakefile

@@ -0,0 +1,14 @@
+require "rubygems"
+require "rake"
+require "echoe"
+
+Echoe.new("factory_grabber", "1.0.3") do |p|
+  p.description              = "Grab or create factories for faster Functional/Integration testing"
+  p.url                      = "http://github.com/gavinM/factory_grabber"
+  p.author                   = "Gavin Morrice"
+  p.email                    = "gavin@handyrailstips.com"
+  p.ignore_pattern           = ["tmp/*", "script/*", "dbfile"]
+  p.development_dependencies = []
+end
+
+Dir["#{File.dirname(__FILE__)}/tasks/*.rake"].sort.each { |ext| load ext }

data/factory_grabber.gemspec

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{factory_grabber}
+  s.version = "1.0.3"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Gavin Morrice"]
+  s.date = %q{2009-09-17}
+  s.description = %q{Grab or create factories for faster Functional/Integration testing}
+  s.email = %q{gavin@handyrailstips.com}
+  s.extra_rdoc_files = ["CHANGELOG", "README.md", "lib/dbfile", "lib/factory_grabber.rb", "lib/spec/database_setup.rb", "lib/spec/dbfile", "lib/spec/factories.rb", "lib/spec/grab_spec.rb", "lib/spec/performance_test.rb", "lib/spec/spec_helper.rb", "lib/spec/user.rb"]
+  s.files = ["CHANGELOG", "Manifest", "README.md", "Rakefile", "init.rb", "lib/dbfile", "lib/factory_grabber.rb", "lib/spec/database_setup.rb", "lib/spec/dbfile", "lib/spec/factories.rb", "lib/spec/grab_spec.rb", "lib/spec/performance_test.rb", "lib/spec/spec_helper.rb", "lib/spec/user.rb", "factory_grabber.gemspec"]
+  s.homepage = %q{http://github.com/gavinM/factory_grabber}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Factory_grabber", "--main", "README.md"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{factory_grabber}
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Grab or create factories for faster Functional/Integration testing}
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end

data/init.rb

@@ -0,0 +1 @@
+require "factory_grabber"

data/lib/factory_grabber.rb

@@ -0,0 +1,176 @@
+# load active support if not in Rails
+require "activesupport" unless defined?(ActiveSupport::Inflector)
+require "factory_girl"
+module FactoryGrabber
+  
+  class NotANumberError < NoMethodError;end
+  
+  module Grab
+    
+    # numbers 1 to 9
+    UNITS =  {
+      "one"       => 1, 
+      "two"       => 2, 
+      "three"     => 3, 
+      "four"      => 4, 
+      "five"      => 5, 
+      "six"       => 6, 
+      "seven"     => 7,
+      "eight"     => 8,
+      "nine"      => 9}
+
+    # numbers 10 to 19
+    TEENS = {
+      "ten"       => 10,
+      "eleven"    => 11,
+      "twelve"    => 12,
+      "thirteen"  => 13,
+      "fourteen"  => 14,
+      "fifteen"   => 15,
+      "sixteen"   => 16,
+      "seventeen" => 17,
+      "eighteen"  => 18,
+      "nineteen"  => 19}
+
+    # tens from 20 to 90
+    TENS = {
+      "twenty"  => 20,
+      "thirty"  => 30,
+      "forty"   => 40,
+      "fifty"   => 50,
+      "sixty"   => 60,
+      "seventy" => 70,
+      "eighty"  => 80,
+      "ninety"  => 90}
+
+    # define an empty hash
+    ALL_NUMBERS = {}
+
+    # add each number between 1 and 19 to ALL_NUMBERS
+    UNITS.merge(TEENS).each { |name, value| ALL_NUMBERS[name] = value }
+
+    TENS.each do |name, value|
+      # add each ten from 20 to 90 to ALL_NUMBERS
+      ALL_NUMBERS[name] = value
+      # add each remaining number to ALL_NUMBERS
+      UNITS.each { |unit_name, unit_value| ALL_NUMBERS["#{name}_#{unit_name}"] = value + unit_value }
+    end
+
+
+    # remove unnecessary methods from Grab class 
+    instance_methods.each do |m| 
+      undef_method m unless m.to_s =~ /method_missing|respond_to?|^__/ 
+    end
+
+    # add singleton class methods
+    class << self
+
+      # methods called to Grab are not really methods, they're ghost methods. 
+      # If method_missing cannot identify the number and the factory to be created it will pass
+      # this up the chain to Object. @name is the method name called (symbol) and options is the hash of
+      # options passed to the method.
+      def method_missing(name, options = {})
+        @options = options
+        @parts_in_name = name.to_s.split("_")
+        
+        # replace 'a' or 'an' with 'one'
+        if @parts_in_name.first == "a" || @parts_in_name.first == "an"
+          @parts_in_name.delete_at(0)
+          @parts_in_name.unshift("one")
+        end
+        # rejoins the name with 'a' and 'an' replaced with 'one'
+        @name = @parts_in_name.join("_")
+        
+        # check the options if there are any
+        unless @options.empty?
+          check_options_against_database
+        end
+
+        # results to be returned
+        @results = []
+        
+        if @should_create_new
+          number.times { @results << create_factory }
+        else 
+          # create new records if there is not a sufficient amount in the database
+          required_records ? required_records.times { create_factory } : nil
+        
+          # find and return the desired records
+          @results = klass_name_constant.all(:conditions => @options, :limit => number)
+        end
+        # return a single record if only one exists
+        @results.size == 1 ? @results.first : @results
+      end
+
+      private
+      
+      # checks the database columns to ensure options are all database columns
+      # if they are not (in the case of virtual attributes) a new factory should be created
+      def check_options_against_database
+        # extract the keys from the options hash as strings
+        option_keys = @options.stringify_keys.keys
+        # fetch the names of the Class's database table columns
+        klass_columns = klass_name_constant.columns.collect { |c| c.name }
+        # @should create new will be true if there are any option keys that are not in db table
+        @should_create_new = !!option_keys.detect { |opt| !klass_columns.include?(opt) }
+      end
+
+      # returns the number part of the method name eg. nineteen
+      def number_name
+        @number_name = if UNITS.include?(@parts_in_name.first) || TEENS.include?(@parts_in_name.first)
+          @parts_in_name.first
+        elsif TENS.include?(@parts_in_name.first)
+          UNITS.include?(@parts_in_name[1]) ? @parts_in_name[0..1].join("_") : @parts_in_name.first
+        end
+      end
+      
+      # returns the number as an integer
+      def number
+        @number = ALL_NUMBERS[number_name]
+        raise NotANumberError, "#{@name} contains an invalid number" unless @number
+        @number
+      end
+      
+      # returns the klass name of the 
+      def klass_name
+        @name.to_s.scan(/#{number_name}_(.+)/)
+        ActiveSupport::Inflector.singularize($1)
+      end
+      
+      # returns the name of the factory as a symbol.
+      # Eg. Grab.four_hippos (would return :hippo)
+      def klass_name_symbol
+        klass_name.to_sym
+      end
+
+      # returns the name of the factory as a Constant.
+      # Eg. Grab.four_hippos (would return :hippo)      
+      def klass_name_constant
+        klass_name.classify.constantize
+      end
+      
+      # TODO rewrite this to accept various factory gems
+      def create_factory
+        Factory(klass_name_symbol, @options)
+      end
+
+      # returns the number of records required minus the number of records available. If there are enough
+      # records already it will return nil (so we can call <tt>required_records ? do_this : do_that</tt> )
+      def required_records
+        result = (number - number_of_existing_records)
+        result > 0 ? result : nil
+      end
+
+      # finds the number appropriate records already in the database.
+      # if klass_name_constant is not a recognised class then this returns 0
+      def number_of_existing_records
+        return 0 unless defined?(klass_name_constant)
+        klass_name_constant.all(:conditions => @options).count
+      end
+
+    end
+
+  end
+
+end
+include FactoryGrabber

data/lib/spec/database_setup.rb

@@ -0,0 +1,9 @@
+require 'active_record'
+ActiveRecord::Base.establish_connection :adapter => "sqlite3", :database => "dbfile"
+
+ActiveRecord::Base.connection.create_table :users, :force => true do |t| 
+  t.string :first_name
+  t.string :last_name
+  t.string :email
+  t.boolean :admin
+end

data/lib/spec/factories.rb

@@ -0,0 +1,9 @@
+require "factory_girl"
+
+Factory.define(:user) do |f|
+  f.sequence(:first_name) { |n| "first#{n}" }
+  f.sequence(:last_name)  { |n| "last#{n}" }
+  f.sequence(:email)      { |n| "email#{n}@email.com" }
+  f.admin(false)
+  f.password "password"
+end

data/lib/spec/grab_spec.rb

@@ -0,0 +1,170 @@
+require File.dirname(__FILE__) + "/spec_helper"
+
+describe Grab do
+  
+  describe "Grabbing 'a' or 'an' record" do
+    
+    it "should return one record if number is 'a'" do
+      @user = Grab.a_user
+      @user.is_a?(User).should be_true
+    end
+    
+    it "should return one record if number is 'an'" do
+      @user = Grab.an_user
+      @user.is_a?(User).should be_true
+    end
+
+  end
+  
+  describe "Grabbing various number combinations" do
+    
+    it "should return the record if number is one" do
+      @user = Grab.one_user
+      @user.is_a?(User).should be_true
+    end
+    
+    it "should grab the correct number of records each time" do
+      # random number between 1 and 99
+      # running these specs hundreds of times (which I have) means that each number will be tested
+      random_number = (rand * 99).ceil
+      # return the number name eg. sixty_one
+      random_name = Grab::ALL_NUMBERS.invert[random_number]
+      @users = Grab.send("#{random_name}_users")
+      @users.size.should == random_number
+    end
+  
+  end
+  
+  describe "Grabbing existing records" do
+    
+    before do
+      Factory :user unless User.all.any?
+    end
+    
+    it "should not create a new record if there is one present" do
+      lambda { Grab.one_user }.should_not change { User.count }
+    end
+    
+  end
+  
+  describe "Grabbing non-existing records" do
+  
+    before do
+      User.destroy_all
+    end
+    
+    it "should create a new record" do
+      lambda { Grab.one_user }.should change { User.count }.by(1)
+    end
+  
+  end
+  
+  describe "Grabbing a mixture of existing and non-existing records" do
+    
+    before do
+      User.destroy_all
+      2.times { Factory :user }
+    end
+    
+    it "should only create one extra record" do
+      lambda { Grab.three_users }.should change { User.count }.by(1)
+    end
+    
+  end
+  
+  describe "Grabbing factories with virtual attributes" do
+    # Attributes such as password can be set when creating factories but may not have a corresponding
+    # column on the database (ie. they are virtual attributes)
+    # In such cases, to ensure the record has the desired attributes, a new factory should be created
+    it "should create a new factory if attributes are not all in the database" do
+      Factory(:user, :password => "password")
+      lambda { @user = Grab.one_user(:password => "password") }.should change { User.count }.by(1)
+      @user.is_a?(User).should be_true
+    end
+    
+  end
+  
+  describe :number_name do
+    
+    it "should return the correct number if it's a unit" do
+      Grab.one_user
+      Grab.send(:number_name).should == 'one'
+    end
+    
+    it "should return the correct number if it's a teen'" do
+      Grab.eleven_users
+      Grab.send(:number_name).should == 'eleven'
+    end
+    
+    it "should return the correct number if it's a double-digit" do
+      Grab.twenty_one_users
+      Grab.send(:number_name).should == 'twenty_one'
+    end
+    
+    it "should return the correct number if it's a ten" do
+      Grab.twenty_users
+      Grab.send(:number_name).should == 'twenty'
+    end
+    
+  end
+  
+  describe :number do
+    
+    it "should return the correct number if it's a unit" do
+      Grab.four_users
+      Grab.send(:number).should == 4
+    end
+    
+    it "should return the correct number if it's a teen'" do
+      Grab.twelve_users
+      Grab.send(:number).should == 12
+    end
+    
+    it "should return the correct number if it's a double-digit" do
+      Grab.twenty_one_users
+      Grab.send(:number).should == 21
+    end
+    
+    it "should return the correct number if it's a ten" do
+      Grab.twenty_users
+      Grab.send(:number).should == 20
+    end
+    
+  end
+  
+  describe :klass_name do
+    
+    it "should return the name of the factory class as a constant if available" do
+      Grab.one_user
+      Grab.send(:klass_name).should == "user"
+    end
+    
+  end
+    
+  describe :klass_name_constant do
+    
+    it "should return the class name as a constant" do
+      Grab.one_user
+      Grab.send(:klass_name_constant).should == User
+    end
+    
+  end
+  
+  describe :required_records do
+    
+    before do
+    end
+    
+    it "should return nil if no records are required" do
+      count = User.count
+      if count < 4
+        (4 - count).times { Factory(:user) }
+      end
+      Grab.three_users
+      Grab.send(:required_records).should be_nil
+    end
+  
+    
+  end
+  
+end

data/lib/spec/performance_test.rb

@@ -0,0 +1,22 @@
+require File.dirname(__FILE__) + "/spec_helper"
+require "benchmark"
+
+# runs a quick benchmark to compare the two
+Benchmark.bmbm do |test|
+  test.report("Create 50 new factories") do
+    50.times { Factory :user, :first_name => "John", :admin => false }
+  end
+  
+  until User.count >= 50
+    Factory :user, :last_name => "Smith", :admin => true
+  end
+  
+  test.report("Grab 50 separate factories") do
+    50.times { Grab.one_user :last_name => "Smith", :admin => true }
+  end
+  
+  test.report("Grab 50 factories at once") do
+    Grab.fifty_users :last_name => "Smith", :admin => true
+  end
+  
+end

data/lib/spec/spec_helper.rb

@@ -0,0 +1,7 @@
+require "rubygems"
+  
+["database_setup", "user", "factories", "../factory_grabber"].each do |file|
+  require "#{File.dirname(__FILE__)}/#{file}"
+end
+
+include FactoryGrabber

data/lib/spec/user.rb

@@ -0,0 +1,4 @@
+class User < ActiveRecord::Base
+  
+  attr_accessor :password
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification 
+name: factory_grabber
+version: !ruby/object:Gem::Version 
+  version: 1.0.3
+platform: ruby
+authors: 
+- Gavin Morrice
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-09-17 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: Grab or create factories for faster Functional/Integration testing
+email: gavin@handyrailstips.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- CHANGELOG
+- README.md
+- lib/dbfile
+- lib/factory_grabber.rb
+- lib/spec/database_setup.rb
+- lib/spec/dbfile
+- lib/spec/factories.rb
+- lib/spec/grab_spec.rb
+- lib/spec/performance_test.rb
+- lib/spec/spec_helper.rb
+- lib/spec/user.rb
+files: 
+- CHANGELOG
+- Manifest
+- README.md
+- Rakefile
+- init.rb
+- lib/dbfile
+- lib/factory_grabber.rb
+- lib/spec/database_setup.rb
+- lib/spec/dbfile
+- lib/spec/factories.rb
+- lib/spec/grab_spec.rb
+- lib/spec/performance_test.rb
+- lib/spec/spec_helper.rb
+- lib/spec/user.rb
+- factory_grabber.gemspec
+has_rdoc: true
+homepage: http://github.com/gavinM/factory_grabber
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Factory_grabber
+- --main
+- README.md
+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: factory_grabber
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Grab or create factories for faster Functional/Integration testing
+test_files: []
+