FixtureBot

FixtureBot provides a Ruby DSL that compiles down to standard YAML fixtures. This allows you to keep the speed of Rails fixtures while avoiding the maintenance pain of hand-written YAML.

Key Comparisons

Core Philosophy

• Vs Rails Fixtures: FixtureBot solves the

FixtureBot simplifies defining relationships between records.

belongs_to

Reference other records by their name to set the foreign key using their stable ID:

post :hello_world do
  author :brad # sets author_id to brad's ID
end

Polymorphic associations

Use the table helper to set both the _id and _type columns:

# If 'votable' is a polymorphic association
vote :upvote_post do
  votable post(:hello) # sets votable_id and votable_type: "Post"
end

Join tables (HABTM)

Pass multiple record names to create rows in the join table:

post :hello_world do
  tags :ruby, :rails # creates rows in posts_tags
end

To use FixtureBot, add the fixturebot-rails gem to your Gemfile. You can then use the Rails generator to automate the setup of your fixture definition files and test helper integration.

# Add to Gemfile
gem "fixturebot-rails"

# Run the generator
rails generate fixturebot:install

If you prefer not to use the generator, you can set up FixtureBot manually by requiring the appropriate integration in your test helper and creating a fixtures.rb file.

RSpec

1. Add require "fixturebot/rspec" to spec/rails_helper.rb.
2. Create spec/fixtures.rb for your definitions.

Minitest

1. Add require "fixturebot/minitest" to test/test_helper.rb.
2. Create test/fixtures.rb for your definitions.

Fixtures are automatically generated before the test suite runs.

FixtureBot automatically detects your fixtures file (e.g., spec/fixtures.rb) and sets the output directory by stripping the .rb extension. You can override these settings in config/application.rb or config/environments/test.rb using the following configuration keys:

config.fixturebot.fixtures_file = "test/my_fixtures.rb"
config.fixturebot.output_dir = "test/fixtures"

To set up FixtureBot in your Rails application, run the Rails generator. The generator automatically detects whether you are using RSpec or Minitest and performs the following actions:

1. Creates a fixtures configuration file:
   • For RSpec: spec/fixtures.rb
   • For Minitest: test/fixtures.rb
2. Injects the required FixtureBot integration into your test helper:
   • For RSpec: Adds require "fixturebot/rspec" to spec/rails_helper.rb after require 'rspec/rails'.
   • For Minitest: Adds require "fixturebot/minitest" to test/test_helper.rb after require "rails/test_help".

rails generate fixturebot:install

If you are not using Rails, you must define your database schema manually using FixtureBot::Schema.define. This allows FixtureBot to understand tables, columns, and associations.

FixtureBot::Schema.define do
  table :users, singular: :user, columns: [:name, :email]

  table :posts, singular: :post, columns: [:title, :body, :author_id] do
    belongs_to :author, table: :users
  end

  join_table :posts_tags, :posts, :tags
end

FixtureBot generates deterministic, stable IDs. You can customize how these IDs are generated.

Hardcoded IDs

Override the deterministic ID with an explicit value:

user :admin do
  id 42
end

UUIDs

In Rails, UUID primary keys are auto-detected. For manual schema definitions, use FixtureBot::Key::Uuid to ensure deterministic UUID v5 generation.

Custom Key Strategies

You can provide a custom object that responds to generate(table_name, record_name) to implement custom ID logic (e.g., prefixed IDs).

# Example of a custom key strategy
module PrefixedKey
  module_function
  def generate(table_name, record_name)
    hash = Zlib.crc32("#{table_name}:#{record_name}").to_s(36)
    "#{table_name.to_s.chomp('s')}_#{hash}"
  end
end

FixtureBot::Schema.define do
  table :customers, singular: :customer, columns: [:name], key: PrefixedKey
end

You can configure the default paths for fixture compilation within your Rails application configuration. This allows you to avoid passing explicit paths to the compile method.

Set the following keys under the fixturebot configuration object in your Rails environment files:

• fixtures_file: The path to your fixture definition file (e.g., spec/fixtures.rb).
• output_dir: The directory where compiled fixtures should be written.

# Example configuration in config/environments/test.rb
Rails.application.configure do
  config.fixturebot = {
    fixtures_file: 'spec/fixtures.rb',
    output_dir: 'spec/fixtures/compiled'
  }
end