FixtureReplacement (version 3.0.1)
What is FixtureReplacement
FixtureReplacement is a Rails 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 and Test::Unit.
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 spec/spec_helper.rb
file, in the configuration section:
Spec::Runner.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 = # 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 theBar
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 toUser.new
with the attributes for the user. -
create_user
: equivalent toUser.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.
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)
attr_protected / attr_accessible
In the case that the model has an attr_protected field, FixtureReplacement will assign the field as if it wasn’t protected, which is convenient for testing:
class User < ActiveRecord::Base
attr_protected :admin_status
end
user = create_user(:username => "scott", :admin_status => true)
user.admin_status # => true
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 script/console
$ ./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 ([email protected])