---

Make your tests fast by augmenting them with transactional fixtures powered by your favorite factory library!

We all know that ActiveRecord's fixtures are hard to maintain, and more importantly, disconnected from the models that create your data. This disconnect can lead to invalid or incomplete representations of your objects as your application grows. But Rails did get something right. Fixtures combined with transactional tests are a huge performance win while providing canned references among your team via helper methods that find fixtures using a unique name. The NamedSeeds gem aims to replace YAML fixtures by providing a slim identification layer to be used in conjunction with your factory library of choice. For example, FactoryGirl.

The idea is to leverage your tests' existing factories to generate fixtures that will be populated before testing starts and to use a database transaction strategy around each test. In this way you have a curated set of personas that can be accessed via convenient helper methods like users(:admin) which in turn yields much faster test runs. NamedSeeds fixtures also become your seed data for Rails' development environment. This consistency between development and testing is a huge win for on-boarding new team members. Lastly, database fixtures, even those seeded by factories, are not a panacea and we recommend that you continue to use factories in your tests for edge cases when it makes sense to do so.

NamedSeeds is best when your factories follow two key principals:

• Leveraging your models for most business logic.
• Creation of "valid garbage" with no/minimal args while allowing idempotency via explicit args.

Installation

Add the gem to your Rails' Gemfile in both the development and test group as shown below. This is needed since the NamedSeeds gem has integrations in both environments.

group :development, :test do
  gem 'named_seeds'
end

Quick Start

NamedSeeds only requires that you customize the Rails db/seeds.rb file. The contents of this file can be anything you want! We recommend using a factory library like FactoryGirl or Machinist.

require 'factory_girl'
include FactoryGirl::Syntax::Methods
FactoryGirl.find_definitions rescue false

@bob = create :user, id: NamedSeeds.identify(:bob), email: 'bob@test.com'

In this example we have given our Bob user an explicit primary key using the identify method of NamedSeeds. This ensures we have a handle on Bob in our tests. For this happen, make the following changes to your Rails test_helper.rb file.

ENV["RAILS_ENV"] = "test"
require File.expand_path('../../config/environment', __FILE__)
require 'rails/test_help'
NamedSeeds.load_seed

class ActiveSupport::TestCase

  named_seeds :users

end

Here we have added NamedSeeds.load_seed after our requires. This ensures our test database is properly seeded. We have also added a named_seeds :users declaration that creates a test helper method that can find any persona with a matching identity. The method name follows ActiveRecord model/table name conventions. So in this case we expect to find a User model. An example of what our unit test for Bob might look like with the new users fixture helper would be:

require 'test_helper'

class UserTest < ActiveSupport::TestCase

  tests "should work" do
    user = users(:bob)
    assert_equal 'bob@test.com', user.email
  end

end

This test is very contrived and is only meant to illustrate the users(:bob) test helper which closely mimics ActiveRecord's fixture helpers.

Detailed Usage

Development Benefits

NamedSeeds hooks into the db:setup process. In this way, the same fixture story seeded in your test environment is the same in development. For example, if you are on-boarding a new developer and bootstrapping their environment.

$ bundle
$ rake db:create:all db:setup

Your local development database will now contain all fixtures created in db/seeds. As you fixtures grow, re-create your development environment with confidence.

$ bundle
$ rake db:drop:all db:create:all db:setup

The NamedSeeds::DSL

If you do not like typing NamedSeeds.identify(:persona) over and over again in your seeds file, you can include the NamedSeeds::DSL at the top. This will give you direct scope to the identify method which is also succinctly aliased to just id if you want.

include NamedSeeds::DSL

id(:ruby)       # => 207281424
id(:sapphire_2) # => 1066363776

UUID Identifiers

By default identities boil down to a consistent integer whose values are less than 2^30. These are great for typical primary or foreign keys. Now that Rails supports UUID keys in both models and ActiveRecord fixtures, so does the NamedSeeds gem. The identity method can use an optional second parameter to denote the SQL type when seeding your database.

id(:ken, :uuid) # => '4f156606-8cb3-509e-a177-956ca0a22015'

So if our User model did use a UUID column type, our seed file might look like this.

@bob = create :user, id: NamedSeeds.identify(:bob), email: 'bob@test.com'

String Identifier

If your model uses strings for primary keys or what is known as "natural" keys, then NamedSeeds can still work for you. First, create your seed data without the identity helper. For example, below we are seeding US states in a contrived lookup table.

# In db/seeds.rb file.
create :state, id: 'VA', name: 'Virginia'
create :state, id: 'WA', name: 'Washington'

Here the primary key of the State model is a string column. You have two options to generate test helpers for these objects. Note that none are technically needed since the identities are known and not random integers.

named_seeds :states, identities: {virginia: 'VA', washington: 'WA'}
states(:virginia) # => #<State id: 'VA'... >

named_seeds :states, identities: :natural
states('VA')      # => #<State id: 'VA'... >

By passing an identities hash to named_seeds you can customize the name of the key used in finders. The first line would generate a method that allows you to find states using the longer identities key values. This is great if your natural keys do not necessarily speak to the persona/object under test. If you wanted to use the natural key string values, you can just pass :natural to the identities option.

Setting Fixture Classes

If your test helper name can not infer the class name, just use the :class option when declaring seeds in your test helper.

named_seeds :users, class: Legacy::User

Moving From ActiveRecord Fixtures

Unlike ActiveRecord fixtures, NamedSeeds does not support loading fixtures per test case. Since the entire fixture story is loaded before the test suite runs. NamedSeeds is much more akin to fixtures(:all) and the named_seeds method is more about creating test helper methods to access named fixtures. Lastly, NamedSeeds has no notion of instantiated fixtures.

Using DatabaseCleaner

Rails 4 (maybe starting in 4.1) now has a new test database synchronization strategy. No longer is your entire development schema cloned when you run your tests. This saves time when running tests but it also adds a potential gotcha when using db/seeds.rb with the NamedSeeds gem. We recommend using the DatabaseCleaner gem and cleaning your DB at the top of your seed file.

# In your Gemfile.
group :development, :test do
  gem 'named_seeds'
  gem 'database_cleaner'
end

# Top of db/seeds.rb file.
require 'database_cleaner'
DatabaseCleaner.clean_with :truncation
DatabaseCleaner.clean

Configurations

All configurations are best done in a config/initializers/named_seeds.rb file using a defined check as shown below. All other examples below assume this convention.

if defined?(NamedSeeds)
  Rails.application.config.named_seeds
end

Other Rails::Engine And Seed Loaders

Rails::Engines are a great way to distribute shared functionality. Rails exposes a hook called load_seed that an engine can implement. These are great for seeding tables that an engine's models may need. You can tell NamedSeeds to use any object that responds to load_seed and each will be called after db/seeds.rb is loaded. For example:

config.named_seeds.engines_with_load_seed = [
  GeoData::Engine,
  OurLookupTables
]

Custom Seed File

By default, the NamedSeeds gem relies on Rails db/seeds.rb as your seed file. Some people use this file for setting up new production instances while others have code in this file that is something completely different. If this file is not safe for development/test then you should really re-examine your usage of db/seeds.rb since Rails loads this file on the db:setup task automatically. If you do not want to use this for your development/test seed data, then you can customize the location. However, NamedSeeds does this by running our own named_seeds:setup task after the Rails db:setup task. So the result is still somewhat the same for development but this does keep db/seeds.rb out of the test environment.

config.named_seeds.load_app_seed_file = false
config.named_seeds.custom_seed_file = 'db/seeds_devtest.rb'

Versions

The current master branch is for Rails v4.0.0 and up and. Please use our 1-0-stable branch for Rails v3.x.

Contributing

We use the Appraisal gem from Thoughtbot to help us test different versions of Rails. The rake appraisal test command actually runs our test suite against all Rails versions in our Appraisal file. So after cloning the repo, running the following commands.

$ bundle install
$ bundle exec appraisal install
$ bundle exec appraisal rake test

If you want to run the tests for a specific Rails version, use one of the appraisal names found in our Appraisals file. For example, the following will run our tests suite for Rails 4.1.x.

$ bundle exec appraisal rails41 rake test