Open Source Ecosystems

= FixtureReplacement

== What is FixtureReplacement?

FixtureReplacement is a Rails gem 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.

(If you've ever used FactoryGirl / FactoryBot, you're probably already quite familiar with fixture_replacement, as it proceeded FactoryGirl. Also, FR is much more opinionated, and much less PC!)

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

Add it to your Gemfile:

group :development, :test do gem "fixture_replacement", "~> 4.0" end

=== Using it with RSpec

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

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

=== Using it with Test::Unit

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

class Test::Unit::TestCase include FixtureReplacement end

== How to use FixtureReplacement

=== Defining default attributes

At the heart of FixtureReplacement is the db/example_data.rb 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 password is generated and then used for both the :password and
:password_confirmation attributes)
a new_modelname method is automatically provided that allows you to set up dependent
model objects (in this case an instance of the Bar model)

=== Available methods

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

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