@@ -1,31 +1,41 @@ -= factory_girl +h1. factory_girl - written by Joe Ferris <jferris@thoughtbot.com> - thanks to Tammer Saleh, Dan Croak, and Jon Yurek of thoughtbot, inc. - Copyright 2008 Joe Ferris and thoughtbot, inc. +Written by "Joe Ferris":mailto:jferris@thoughtbot.com. -== Defining factories +Thanks to Tammer Saleh, Dan Croak, and Jon Yurek of thoughtbot, inc. - # This will guess the User class - Factory.define :user do |u| - u.first_name 'John' - u.last_name 'Doe' - u.admin false - end +Copyright 2008 Joe Ferris and thoughtbot, inc. + +h2. Download + +Github: "Page":http://github.com/thoughtbot/factory_girl/tree/master "Clone":git://github.com/thoughtbot/factory_girl.git + +Gem: <pre>gem install thoughtbot-factory_girl --source http://gems.github.com</pre> + +h2. Defining factories + +<pre><code># This will guess the User class +Factory.define :user do |u| + u.first_name 'John' + u.last_name 'Doe' + u.admin false +end + +# This will use the User class (Admin would have been guessed) +Factory.define :admin, :class => User do |u| + u.first_name 'Admin' + u.last_name 'User' + u.admin true +end</code></pre> - # This will use the User class (Admin would have been guessed) - Factory.define :admin, :class => User do |u| - u.first_name 'Admin' - u.last_name 'User' - u.admin true - end It is recommended that you create a test/factories.rb file and define your factories there. This file can be included from test_helper or directly from your test files. Don't forget: - require 'factory_girl' +<pre><code>require 'factory_girl'</code></pre> + -== Lazy Attributes +h2. Lazy Attributes Most attributes can be added using static values that are evaluated when the factory is defined, but some attributes (such as associations and other @@ -33,73 +43,83 @@ attributes that must be dynamically generated) will need values assigned each time an instance is generated. These "lazy" attributes can be added by passing a block instead of a parameter: - Factory.define :user do |u| - # ... - u.activation_code { User.generate_activation_code } - end +<pre><code>Factory.define :user do |u| + # ... + u.activation_code { User.generate_activation_code } +end</code></pre> -== Dependent Attributes + +h2. Dependent Attributes Some attributes may need to be generated based on the values of other attributes. This can be done by calling the attribute name on Factory::AttributeProxy, which is yielded to lazy attribute blocks: - Factory.define :user do |u| - u.first_name 'Joe' - u.last_name 'Blow' - u.email {|a| "#{a.first_name}.#{a.last_name}@example.com".downcase } - end +<pre><code>Factory.define :user do |u| + u.first_name 'Joe' + u.last_name 'Blow' + u.email {|a| "#{a.first_name}.#{a.last_name}@example.com".downcase } +end + +Factory(:user, :last_name => 'Doe').email +# => "joe.doe@example.com"</code></pre> - Factory(:user, :last_name => 'Doe').email - # => "joe.doe@example.com" -== Associations +h2. Associations Associated instances can be generated by using the association method when defining a lazy attribute: - Factory.define :post do |p| - # ... - p.author {|author| author.association(:user, :last_name => 'Writely') } - end +<pre><code>Factory.define :post do |p| + # ... + p.author {|author| author.association(:user, :last_name => 'Writely') } +end</code></pre> + When using the association method, the same build strategy (build, create, or attributes_for) will be used for all generated instances: - # Builds and saves a User and a Post - post = Factory(:post) - post.new_record? # => false - post.author.new_record # => false +<pre><code># Builds and saves a User and a Post +post = Factory(:post) +post.new_record? # => false +post.author.new_record # => false + +# Builds but does not save a User and a Post +Factory.build(:post) +post.new_record? # => true +post.author.new_record # => true</code></pre> - # Builds but does not save a User and a Post - Factory.build(:post) - post.new_record? # => true - post.author.new_record # => true -== Sequences +h2. Sequences Unique values in a specific format (for example, e-mail addresses) can be generated using sequences. Sequences are defined by calling Factory.sequence, and values in a sequence are generated by calling Factory.next: - # Defines a new sequence - Factory.sequence :email do |n| - "person#{n}@example.com" - end +<pre><code># Defines a new sequence +Factory.sequence :email do |n| + "person#{n}@example.com" +end + +Factory.next :email +# => "person1@example.com" + +Factory.next :email +# => "person2@example.com"</code></pre> + - Factory.next :email - # => "person1@example.com" +h2. Using factories - Factory.next :email - # => "person2@example.com" +<pre><code># Build and save a User instance +Factory(:user) -== Using factories +# Build a User instance and override the first_name property +Factory.build(:user, :first_name => 'Joe') - # Build and save a User instance - Factory(:user) +# Return an attributes Hash that can be used to build a User instance +attrs = Factory.attributes_for(:user)</code></pre> - # Build a User instance and override the first_name property - Factory.build(:user, :first_name => 'Joe') +h2. More Information - # Return an attributes Hash that can be used to build a User instance - attrs = Factory.attributes_for(:user) +"Our blog":http://giantrobots.thoughtbot.com +"factory_girl rdoc":http://dev.thoughtbot.com/factory_girl README.textile 8354b8ddd68ba9fe351e4c01194b8be162263448 Joe Ferris jferris@thoughtbot.com http://github.com/teem/factory_girl/commit/3cde84a1a68ea865bce8766a1a142afa80c343c0 3cde84a1a68ea865bce8766a1a142afa80c343c0 2008-06-06T08:46:39-07:00 2008-06-06T08:46:39-07:00 Converted the README to textile 658981cc4fb312fd0baa446d1af304d0815532fa Joe Ferris jferris@thoughtbot.com