A library for making it extremely fast for Rails developers to set up and save ActiveRecord instances when writing test cases.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



A library for making it extremely fast for Rails developers to set up and save ActiveRecord instances when writing test cases. It aims to:

  • meet all your validations automatically
  • only make you specify the attributes you care about
  • give you a rich set of features so you can specify associations as concisely as possible
  • do this with as little configuration as possible


Let's say you've got a set of models that look like this:

class BlogPost < ActiveRecord::Base
  has_many   :blog_post_tags
  has_many   :tags, :through => :blog_post_tags
  belongs_to :user
  validates_presence_of :title, :user_id

class BlogPostTag < ActiveRecord::Base
  belongs_to :blog_post
  belongs_to :tag

class Tag < ActiveRecord::Base
  validates_uniqueness_of :tag
  has_many :blog_post_tags
  has_many :blog_posts, :through => :blog_post_tags

class User < ActiveRecord::Base
  has_many :blog_posts

  validates_inclusion_of    :gender, :in => %w(f m)
  validates_uniqueness_of   :email, :login
  # from http://github.com/alexdunae/validates_email_format_of
  validates_email_format_of :email

You can get a valid instance of a BlogPost by calling BlogPost.sample in a test environment:

blog_post1 = BlogPost.sample
puts blog_post1.title             # => some non-empty string
puts blog_post1.user.is_a?(User)  # => true

user1 = User.sample
puts user1.email                  # => will be a valid email 
puts user1.gender                 # => will be either 'f' or 'm'

Since SampleModels figures out validations and associations from your ActiveRecord class definitions, it can usually fill in the required values without any configuration at all.

If you care about specific fields, you can specify them like so:

blog_post2 = BlogPost.sample(:title => 'What I ate for lunch')
puts blog_post2.title             # => 'What I ate for lunch'
puts blog_post2.user.is_a?(User)  # => true

You can specify associated records in the sample call:

bill = User.sample(:first_name => 'Bill')
bills_post = BlogPost.sample(:user => bill)

funny = Tag.sample(:tag => 'funny')
sad = Tag.sample(:tag => 'sad')
funny_yet_sad = BlogPost.sample(:tags => [funny, sad])

You can also specify associated records by passing them in at the beginning of the argument list, if there's only one association that would work with the record's class:

jane = User.sample(:first_name => 'Jane')
BlogPost.sample(jane, :title => 'What I ate for lunch')

You can also specify associated records by passing in hashes or arrays:

bills_post2 = BlogPost.sample(:user => {:first_name => 'Bill'})
puts bills_post2.user.first_name  # => 'Bill'

funny_yet_sad2 = BlogPost.sample(
  :tags => [{:tag => 'funny'}, {:tag => 'sad'}]
puts funny_yet_sad2.tags.size     # => 2

Instance attributes

By default, SampleModels sets each attribute on a record to a non-blank value that matches the database type. They'll often be nonsensical values like "first_name 5", but the assumption is that if you didn't specify a value, you don't really care what it is as long as it validates. Non-trivial codebases routinely end up having models with many attributes, and when you find yourself writing a test with that model, you may only care about one or two attributes in that test case. SampleModels aims to let you specify only those important attributes while letting SampleModels take care of everything else.

SampleModels reads your validations to get hints about how to craft an instance that will be valid. The current supported validations are:


If you use the validates_email_format_of gem, SampleModels will ensure that the attribute in question is a valid email address.


SampleModels already sets database columns to be non-blank, but this validation comes in handy if you have an attr_accessor:

class UserWithPassword < ActiveRecord::Base
  attr_accessor :password
  validates_presence_of :password

user_with_password = UserWithPassword.sample
puts user_with_password.password  # => Some non-blank string


SampleModels will set the attribute to one of the specified values.


SampleModels will set the attribute to a string within the specified length constraints.


SampleModels will ensure that new instances will have different values for attributes where uniqueness is required, as discussed below under "New records vs. old records."


If your application has an extensive data model, setting up associations for a test case can be an extremely tedious endeavor. SampleModels aims to make this process easy on the programmer and easy on the reader with a number of features.

Belongs-to associations

As demonstrated above, belongs_to associations are automatically set like any other attribute:

blog_post = BlogPost.sample
puts blog_post.user.is_a?(User)   # => true

You can also specify these associations as if you were calling new or create!:

kelley = User.sample(:first_name => 'Kelley')
BlogPost.sample(:user => kelley)
BlogPost.sample(:user_id => kelley.id)

If you want, you can simply specify the record at the beginning of the argument list for sample, and SampleModels will assign them to the appropriate association, as long as there's only one association that fits the class.

kim = User.sample(:first_name => 'Kim')
BlogPost.sample(kim, :title => 'funny')

You can do this with multiple belongs-to associations:

class Network < ActiveRecord::Base

class Show < ActiveRecord::Base
  belongs_to :network
class Video < ActiveRecord::Base
  belongs_to :show
  belongs_to :network

amc = Network.sample(:name => 'AMC')
mad_men = Show.sample(:name => 'Mad Men')
video = Video.sample(amc, mad_men, :name => 'The Suitcase')

If you want, you can simply specify the important attributes of the associated value, and SampleModels will stitch it all together for you:

blog_post = BlogPost.sample(:user => {:first_name => 'Bill'})
puts blog_post.user.first_name  # => 'Bill'

You can combine the two syntaxes in deeper associations:

bb_episode = Video.sample(:show => [amc, {:name => 'Breaking Bad'}])
puts bb_episode.show.network.name   # => 'AMC'
puts bb_episode.show.name           # => 'Breaking Bad'

Polymorphic belongs-to associations

In the case of a polymorphic belongs-to association, SampleModels will attach any record it can find, of any model class.

class Bookmark < ActiveRecord::Base
  belongs_to :bookmarkable, :polymorphic => true

bookmark = Bookmark.sample
puts bookmark.bookmarkable.class  # could be any model class

Of course, you can specify the polymorphic association yourself if that's important to the test.

blog_post = BlogPost.sample(:title => 'Read me later')
Bookmark.sample(:bookmarkable => blog_post)

You can also configure the default class of this polymorphic association with default_class, explained below under "Configuration".

Has-many associations

You can set a has-many association with an array of instances, as you'd do with new or create!:

funny = Tag.sample(:tag => 'funny')
sad = Tag.sample(:tag => 'sad')
funny_yet_sad1 = BlogPost.sample(:tags => [funny, sad])

You can also pass hashes to specify the records:

funny_yet_sad2 = BlogPost.sample(
  :tags => [{:tag => 'funny'}, {:tag => 'sad'}]

Or you can combine the two if that's more convenient:

funny_yet_sad3 = BlogPost.sample(:tags => [{:tag => 'sad'}, funny])


The aim of SampleModels is to require as little configuration as possible -- you'll typically find that most of your models won't need any configuration at all. However, there are a few hooks for when you're trying to accommodate advanced creational behavior.


With before_save you can specify a block that runs before the record is saved. For example, let's say you've got Users, Appointments, and Calendars, and an Appointment should have the same User as the Calendar it belongs to. You can set this behavior with before_save:

# app/models/appointment.rb
class Appointment < ActiveRecord::Base
  belongs_to :calendar
  belongs_to :user
  def validate
    if user_id != calendar.user_id
      errors.add_to_base("Calendar has a different user than me")

# app/models/calendar.rb
class Calendar < ActiveRecord::Base
  has_many    :appointments
  belongs_to  :user

# test/test_helper.rb
SampleModels.configure(Appointment) do |appt|
  appt.before_save do |appt_record|
    appt_record.user_id = appt_record.calendar.user_id

You can also take a second argument, which will pass in the hash that was used during the call to sample.

SampleModels.configure(Appointment) do |appt|
  appt.before_save do |appt_record, sample_attrs|
    unless sample_attrs.has_key?(:user) or sample_attrs.has_key?(:user_id)
      appt_record.user_id = appt_record.calendar.user_id


default will set default values for the field in question.

SampleModels.configure(Category) do |category|
  category.parent.default nil

SampleModels.configure(Video) do |video|
  video.view_count.default 0

A word to the wise: Be sparing with these global defaults. It's easy to tell yourself "Oh, this should be the default value everywhere" -- and then a day later find yourself wanting to override the default all over the place. In many cases you many want to used named samples (see below) instead.


By default, SampleModels fills polymorphic associations with any record, chosen practically at random. You may want to specify this to a more sensible default:

SampleModels.configure(Bookmark) do |bookmark|
  bookmark.bookmarkable.default_class BlogPost


Use force_email_format if you want to ensure that for every newly created instance, the field will be a valid email. This has the same effect as validates_email_format_of, but won't change the behavior of production code.

SampleModels.configure(User) do |user|


Use force_unique if you want to ensure that for every newly created instance, the field will be unique. This has the same effect as validates_uniqueness_of, but won't change how production code behaves.

SampleModels.configure(BlogPost) do |bp|

Named samples

Named samples can be used to pre-set values for commonly used combinations of attributes.

SampleModels.configure(BlogPost) do |bp|
  bp.funny_sample :title => 'Laugh already', :average_rating => 3.0
  bp.sad_sample :title => 'Boo hoo', :average_rating => 2.0

bp1 = BlogPost.sample(:funny)
puts bp1.title   # => 'Laugh already'

bp2 = BlogPost.sample(:funny)
puts bp2.title      # => 'Laugh already'
puts (bp1 == bp2)   # => false

You can override individual attributes, as well:

bp3 = BlogPost.sample(:funny, :average_rating => 4.0)
puts bp3.average_rating   # => 4.0

Backwards-incompatible changes in SampleModels 2

sample always creates a new record now. This is a change from SampleModels 1, which would first attempt to find an existing record in the database that satisfied the stated attributes. In practice, that ended up making tests too confusing.

create_sample and sample now do the same thing, and create_sample is deprecated.


Copyright (c) 2010 Francis Hwang, released under the MIT license.