= FixtureReplacement (version 3.0.1)

== What is FixtureReplacement

FixtureReplacement is a Rails[http://rubyonrails.org/] plugin that provides a simple way to
quickly populate your test database with model objects without having to manage multiple,
brittle fixture files. You can easily set up complex object graphs (with models which
reference other models) and add new objects on the fly.

Not only can FixtureReplacement make your test data easier to maintain, it can also help
to make your tests and specs much more readable and intention-revealing by allowing you
to omit extraneous details and focus only on the attributes that are important for a
particular behaviour. It works well with both RSpec[http://rspec.rubyforge.org/] and
Test::Unit[http://www.ruby-doc.org/stdlib/libdoc/test/unit/rdoc/classes/Test/Unit.html].

== What's new since 2.0:

* default_* is gone in favor of new_*.
* Cyclic dependencies are no longer an issue.  The "overrides hash" (the hash passed to new_* or create_*) can now be processed.

See CHANGELOG.rdoc + test suite for further changes.

== Installation

Install the plugin:

  git://github.com/smtlaissezfaire/fixturereplacement.git

=== Using it with RSpec

Add the following to your <tt>spec/rails_helper.rb</tt> file, in the configuration section:

  RSpec.configure do |config|
    config.include FixtureReplacement
  end

=== Using it with Test::Unit

Add the following to your <tt>test/test_helper.rb</tt> file:

  class Test::Unit::TestCase
    include FixtureReplacement
  end

== How to use FixtureReplacement

=== Defining default attributes

At the heart of FixtureReplacement is the <tt>db/example_data.rb</tt> file where you
define the default attributes for each of your test models. This example shows the default
attributes for a user:

  module FixtureReplacement

    attributes_for :user do |u|
      password = random_string

      u.value                  = "a value",
      u.other                  = "other value",
      u.another                = random_string,     # random string 10 characters long
      u.one_more               = random_string(15), # 15 characters long
      u.password               = password,
      u.password_confirmation  = password,
      u.associated_object      = new_bar            # expects attributes_for :bar to be setup
    end

  end

Note that:

- A 'random_string' method is provided for attributes whose exact value isn't important; this means you can
  create multiple, unique model instances
- you can perform arbitrary set-up and execute any Ruby code prior to returning the hash
  (as shown here where a <tt>password</tt> is generated and then used for both the <tt>:password</tt> and
  <tt>:password_confirmation</tt> attributes)
- a <tt>new_modelname</tt> method is automatically provided that allows you to set up dependent
  model objects (in this case an instance of the <tt>Bar</tt> model)

=== Available methods

Based on the above definition FixtureReplacement makes the following methods available:

- <tt>random_string</tt>: generates a random string as shown above
- <tt>new_user</tt>: equivalent to <tt>User.new</tt> with the attributes for the user.
- <tt>create_user</tt>: equivalent to <tt>User.create!</tt> with the user's attributes.
- <tt>valid_user_attributes</tt>: returns a hash of the user's attributes including associations, specified in db/example_data.rb.

=== Overriding attributes

Overrides of specific attributes can be performed as follows:

  new_user(:thing => "overridden")
  create_user(:thing => "overridden")

Overrides can also be used with associations:

  scott = create_user(:username => "scott")
  post = create_post(:user => scott)


=== Validate your fixtures (thanks Fixjour)

Validate your fixture definitions after including it in the spec helper or test helper:

==== spec_helper.rb:

  Spec::Runner.configuration do |config|
    config.include FixtureReplacement
  end

  FixtureReplacement.validate!

==== test_helper.rb

  class Test::Unit::TestCase
    include FixtureReplacement
  end

  FixtureReplacement.validate!

=== Using FixtureReplacement within <tt>script/console</tt>

  $ ./script/console
  Loading development environment
  >> include FR
  => Object
  >> create_user
  => #<User id: 1, crypted_password: "521faec1c095..." ...>

= Philosophy & Disadvantages

See philosophy_and_bugs.rdoc

= Contributors, Contributions, & BUGS

See contributions.rdoc

== License

This software is dual licensed under the MIT and the GPLv3 Licenses (it's your pick).

Copyright 2007-2009 Scott Taylor / smtlaissezfaire[http://github.com/smtlaissezfaire] (scott@railsnewbie.com)