= ModelFactory
ModelFactory is a module designed to replace the use of fixtures for testing
Rails applications.
The best explanation for the motivation behind ModelFactory (and the inspiration
for this module) comes from Dan Manges' blog: http://www.dcmanges.com/blog/38
NOTE that the API has changed recently, but ModelFactory is still fully
backward-compatible with previous releases. For a description of the original
API see ModelFactory::Legacy.
== Usage
The essential purpose of ModelFactory is the automatic generation of valid,
opaque ActiveRecord objects whose contents are unimportant.
require 'modelfactory'
ModelFactory.configuration do
default(User) do |m|
m.name = "Factory User"
m.email = "[email protected]"
end
end
ModelFactory[User].create.name # => 'Factory User'
If you don't care for the factory creation syntax, ModelFactory defines the
factory class method on ActiveRecord models. The following is equivalent
to ModelFactory[User].create:
User.factory.create
Since factory-created instances are meant to be valid, you will probably
need a way to generate unique values. ModelFactory keeps a counter for each
type that increments when each new instance is created. This counter is passed
to configuration blocks to make it easier to generate unique values:
ModelFactory.configuration do
default(User) do |m, i|
m.name = "Factory User #i"
m.email = "user#[email protected]"
end
end
User.factory.create.name # => 'Factory User 1'
User.factory.create.email # => '[email protected]'
Defaults can be overriden on instance creation. By not specifying unimportant
values, the intention of your tests becomes clearer:
def test_welcome
user = ModelFactory[User].create(:name => 'bob')
assert_equal 'Welcome, bob!', user.welcome
end
It's possible to configure named factories:
ModelFactory.configuration do
admin(User) do |m, i|
m.name = "Admin User #i"
m.admin = true
end
end
User.factory.create_admin.admin # => true
Named factories do not inherit anything from the default, so you'll still need to
provide enough to data to allow the creation of valid objects.
=== A Note About Defaults
The purpose of default values is to generate valid instances, not to serve as
replacements for fixture data. When writing tests that use factory-generated
objects, it's important never to depend on default values in your test assertions.
If you depend on defaults in your tests they become more fragile and the intention
is harder to discern. Alway override values you care about when using factory objects.
== Installing ModelFactory
sudo gem install modelfactory
== License
Copyright (c) 2008, 2009 Justin Balthrop and Zack Hobson
Published under The MIT License, see License.txt
ModelFactory is a module designed to replace the use of fixtures for testing
Rails applications.
The best explanation for the motivation behind ModelFactory (and the inspiration
for this module) comes from Dan Manges' blog: http://www.dcmanges.com/blog/38
NOTE that the API has changed recently, but ModelFactory is still fully
backward-compatible with previous releases. For a description of the original
API see ModelFactory::Legacy.
== Usage
The essential purpose of ModelFactory is the automatic generation of valid,
opaque ActiveRecord objects whose contents are unimportant.
require 'modelfactory'
ModelFactory.configuration do
default(User) do |m|
m.name = "Factory User"
m.email = "[email protected]"
end
end
ModelFactory[User].create.name # => 'Factory User'
If you don't care for the factory creation syntax, ModelFactory defines the
factory class method on ActiveRecord models. The following is equivalent
to ModelFactory[User].create:
User.factory.create
Since factory-created instances are meant to be valid, you will probably
need a way to generate unique values. ModelFactory keeps a counter for each
type that increments when each new instance is created. This counter is passed
to configuration blocks to make it easier to generate unique values:
ModelFactory.configuration do
default(User) do |m, i|
m.name = "Factory User #i"
m.email = "user#[email protected]"
end
end
User.factory.create.name # => 'Factory User 1'
User.factory.create.email # => '[email protected]'
Defaults can be overriden on instance creation. By not specifying unimportant
values, the intention of your tests becomes clearer:
def test_welcome
user = ModelFactory[User].create(:name => 'bob')
assert_equal 'Welcome, bob!', user.welcome
end
It's possible to configure named factories:
ModelFactory.configuration do
admin(User) do |m, i|
m.name = "Admin User #i"
m.admin = true
end
end
User.factory.create_admin.admin # => true
Named factories do not inherit anything from the default, so you'll still need to
provide enough to data to allow the creation of valid objects.
=== A Note About Defaults
The purpose of default values is to generate valid instances, not to serve as
replacements for fixture data. When writing tests that use factory-generated
objects, it's important never to depend on default values in your test assertions.
If you depend on defaults in your tests they become more fragile and the intention
is harder to discern. Alway override values you care about when using factory objects.
== Installing ModelFactory
sudo gem install modelfactory
== License
Copyright (c) 2008, 2009 Justin Balthrop and Zack Hobson
Published under The MIT License, see License.txt