Oaken

Oaken is designed to bridge the gap between the two most common Rails data strategies:

Compared to Factories

• Speed: Oaken seeds shared records once before tests run and uses transactions to roll back, whereas factories often recreate data per test, which can significantly slow down CI.
• Visibility: Factories optimize for isolation, which can hide the complexity of the object graph. Oaken focuses on shared datasets that reveal the system's structure.
• Reduced Setup: Oaken allows you to write a shared seed for common cases once, rather than repeating setup code in every test file.

Compared to Fixtures

• UX: Replaces cumbersome YAML files with sequential Ruby scripts.
• Organization: Instead of splitting data across many files (e.g., users.yml, accounts.yml), you can describe a complete scenario in a single Ruby script.
• Flexibility: Allows for complex scenarios and edge cases to be broken out into separate scripts without creating massive, unmanageable YAML files.
• Ease of Use: You don't have to manually ensure every single record has a unique label to avoid clashes; you can rely on associations to connect objects.

Oaken uses a DSL that mirrors your model names (e.g., accounts.create, users.create) to build an object graph. You can provide an optional symbol label to a create call to make that specific record easily accessible in your tests.

When you provide a label, you can access the record in a test setup like this: setup { @user = users.kasper } (assuming you used users.create :kasper).

If you do not provide a label, you can still access the record through its associations, for example: accounts.kaspers_donuts.menus.first.menu_items.first.

# Creating a root-level model with a label
account = accounts.create :kaspers_donuts, name: "Kasper's Donuts"

# Creating associated models with labels
kasper   = users.create :kasper,   name: "Kasper",   email_address: "kasper@example.com",   accounts: [account]
coworker = users.create :coworker, name: "Coworker", email_address: "coworker@example.com", accounts: [account]

# Creating models without labels (accessible via associations)
menu = menus.create(account:)
plain_donut     = menu_items.create menu:, name: "Plain",     price_cents: 10_00
sprinkled_donut = menu_items.create menu:, name: "Sprinkled", price_cents: 10_10

Oaken uses a Loader to manage seed files. By default, Oaken.loader is available. You can load seed directories or specific files using the .seed method.

Oaken searches within db/seeds/ and db/seeds/#{Rails.env}/ using a glob pattern. For example, calling .seed :accounts will match accounts.rb, accounts/some_file.rb, or any nested path matching accounts{,**/*}.rb.

Key Loading Rules:

• Order: Files are loaded in the order specified (e.g., Oaken.loader.seed :data, :accounts loads :data first).
• Environment Sharing: Files in the top-level db/seeds/ are shared across all environments. Files in db/seeds/development/ or db/seeds/test/ are environment-specific.
• Transactions: Each file load is wrapped in an ActiveRecord::Base.transaction; if a file fails, the changes in that file roll back.

# Load specific directories/identifiers
Oaken.loader.seed :accounts
Oaken.loader.seed :data, :accounts, :cases

# Load a specific file path
Oaken.seed "cases/pagination"

If you are moving from standard Rails fixtures to Oaken, you can automate the conversion of your YAML fixture files into Oaken seed files.

Convert fixtures

Run the following generator to convert everything in test/fixtures to db/seeds (e.g., test/fixtures/users.yml becomes db/seeds/users.rb):

bin/rails generate oaken:convert:fixtures

Disable fixture generation

Once fully migrated, you can prevent Rails generators from creating new fixtures by updating config/application.rb. This ensures your workflow stays focused on Oaken.

Note: If you are already using FactoryBot, you do not need to disable fixtures manually as FactoryBot typically replaces them.

module YourApp
  class Application < Rails::Application
    # We prefer Oaken to fixtures, so we disable them here.
    config.app_generators { _1.test_framework _1.test_framework, fixture: false }
  end
end

You can improve test suite performance by migrating highly shared, static records from factories to Oaken seeds. Instead of recreating common objects (like a standard Account) in every test, seed them once.

Step 1: Seed Oaken in your test environment

In your db/seeds.rb, trigger the Oaken seeding when in the test environment:

# db/seeds.rb
if Rails.env.test?
  Oaken.seed :accounts
  return
end

Step 2: Define shared scenarios

Create a seed file for your shared records. You can use your existing factory logic to define the attributes for the Oaken seed:

# db/seeds/test/accounts/basic.rb
accounts.create :basic, **FactoryBot.attributes_for(:account)

Step 3: Use the seeded records in tests

Your tests can now reference these pre-seeded records directly, for example, by passing them to other factories:

# Example usage in a test
create(:user, account: accounts.basic)

Best Practice: Do the minimum and go slow. Only migrate records that are 100% safe to share across the entire suite to avoid side effects.