Added create|build_list for easy generation of multiple factories at …

…once

Closes thoughtbot#110

GETTING_STARTED.md

@@ -238,6 +238,19 @@ Calling FactoryGirl.create will invoke both after_build and after_create callbac
 
 Also, like standard attributes, child factories will inherit (and can also define) callbacks from their parent factory.
 
+Building or Creating Multiple Records
+-------------------------------------
+
+Sometimes, you'll want to create or build multiple instances of a factory at once.
+
+    built_users   = FactoryGirl.build_list(:user, 25)
+    created_users = FactoryGirl.create_list(:user, 25)
+
+These methods will build or create a specific amount of factories and return them as an array.
+To set the attributes for each of the factories, you can pass in a hash as you normally would.
+
+    twenty_year_olds = FactoryGirl.build_list(:user, 25, :date_of_birth => 20.years.ago)
+
 Alternate Syntaxes
 ------------------
 

lib/factory_girl/syntax/methods.rb

@@ -70,6 +70,42 @@ def build_stubbed(name, overrides = {})
         FactoryGirl.factory_by_name(name).run(Proxy::Stub, overrides)
       end
 
+      # Builds and returns multiple instances from this factory as an array. Attributes can be
+      # individually overridden by passing in a Hash of attribute => value pairs.
+      #
+      # Arguments:
+      # * name: +Symbol+ or +String+
+      #   The name of the factory to be used.
+      # * amount: +Integer+
+      #   number of instances to be built.
+      # * overrides: +Hash+
+      #   Attributes to overwrite for each instance.
+      #
+      # Returns: +Array+
+      # An array of instances of the class this factory generates, with generated attributes
+      # assigned.
+      def build_list(name, amount, overrides = {})
+        amount.times.map { build(name, overrides) }
+      end
+
+      # Creates and returns multiple instances from this factory as an array. Attributes can be
+      # individually overridden by passing in a Hash of attribute => value pairs.
+      #
+      # Arguments:
+      # * name: +Symbol+ or +String+
+      #   The name of the factory to be used.
+      # * amount: +Integer+
+      #   number of instances to be created.
+      # * overrides: +Hash+
+      #   Attributes to overwrite for each instance.
+      #
+      # Returns: +Array+
+      # An array of instances of the class this factory generates, with generated attributes
+      # assigned.
+      def create_list(name, amount, overrides = {})
+        amount.times.map { create(name, overrides) }
+      end
+
       # Generates and returns the next value in a sequence.
       #
       # Arguments:

spec/acceptance/build_list_spec.rb

@@ -0,0 +1,42 @@
+require 'spec_helper'
+require 'acceptance/acceptance_helper'
+
+describe "build multiple instances" do
+  before do
+    define_model('Post', :title => :string)
+
+    FactoryGirl.define do
+      factory(:post) do |post|
+        post.title "Through the Looking Glass"
+      end
+    end
+  end
+
+  context "without default attributes" do
+    subject { FactoryGirl.build_list(:post, 20) }
+
+    its(:length) { should == 20 }
+
+    it "builds (but doesn't save) all the posts" do
+      subject.each do |record|
+        record.should be_new_record
+      end
+    end
+
+    it "uses the default factory values" do
+      subject.each do |record|
+        record.title.should == "Through the Looking Glass"
+      end
+    end
+  end
+
+  context "with default attributes" do
+    subject { FactoryGirl.build_list(:post, 20, :title => "The Hunting of the Snark") }
+
+    it "overrides the default values" do
+      subject.each do |record|
+        record.title.should == "The Hunting of the Snark"
+      end
+    end
+  end
+end

spec/acceptance/create_list_spec.rb

@@ -0,0 +1,42 @@
+require 'spec_helper'
+require 'acceptance/acceptance_helper'
+
+describe "create multiple instances" do
+  before do
+    define_model('Post', :title => :string)
+
+    FactoryGirl.define do
+      factory(:post) do |post|
+        post.title "Through the Looking Glass"
+      end
+    end
+  end
+
+  context "without default attributes" do
+    subject { FactoryGirl.create_list(:post, 20) }
+
+    its(:length) { should == 20 }
+
+    it "creates all the posts" do
+      subject.each do |record|
+        record.should_not be_new_record
+      end
+    end
+
+    it "uses the default factory values" do
+      subject.each do |record|
+        record.title.should == "Through the Looking Glass"
+      end
+    end
+  end
+
+  context "with default attributes" do
+    subject { FactoryGirl.create_list(:post, 20, :title => "The Hunting of the Snark") }
+
+    it "overrides the default values" do
+      subject.each do |record|
+        record.title.should == "The Hunting of the Snark"
+      end
+    end
+  end
+end