fixturebot-rails 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 47f7ad238dac229d37e2bdef254074b14d31657e57775db19f47cbddc06ffe16
+  data.tar.gz: e8c506013cc891b6f2f2d93e05d044c53ee5687ffa7cb628a7bf472f34fa4056
+SHA512:
+  metadata.gz: f801adcf5885114ba66a13a9d7d472b908c9b6ed7de49426c007a70efced6293ba12683253b9cbe7bb38cceaf97902f2642acea3e44ec8522d74da21a57038bb
+  data.tar.gz: c6972d1aed753deed6d109126302ac2267cf99dddb4e5ff45f981bb63753831292e5a44f2d743f11a5a9680f9b088152234ccef8184f1c07ecb0b33de9ee0dfa

data/.rspec

@@ -0,0 +1,4 @@
+--format documentation
+--color
+--require spec_helper
+--tag ~integration

data/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## 0.2.0
+
+### Breaking changes
+
+- **Generator block parameter:** Generator blocks now receive a `fixture` object as a block parameter instead of the magic `name` method. Use `fixture.key` to get the record's symbol name. Column values are available as bare methods inside the block.
+
+  ```ruby
+  # Before
+  user.email { "#{name}@example.com" }
+
+  # After
+  user.email { |fixture| "#{fixture.key}@example.com" }
+  ```
+
+### Improvements
+
+- Rename `YamlDumper` to `Compiler`, `generate`/`dump` to `compile`
+- Rename rake task from `fixturebot:generate` to `fixturebot:compile`
+- Strip YAML document prefix (`---`) from compiled output
+- Fix CLI entrypoint to detect Rails app instead of rescuing LoadError
+- Internal refactor: group classes into `Row` and `Default` modules, replace `method_missing` with `define_singleton_method`
+
+## 0.1.1
+
+- Internal refactoring and README updates
+
+## 0.1.0
+
+- Initial release
+- Ruby DSL for defining fixtures with generators, associations, and join tables
+- Auto-generates YAML fixture files from database schema
+- RSpec and Minitest integration with auto-generation hooks
+- Rails Railtie with `config.fixturebot` namespace and `fixturebot:generate` rake task
+- Install generator: `rails generate fixturebot:install`

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brad Gessler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,322 @@
+# FixtureBot
+
+The syntactic sugar of factories with the speed of fixtures.
+
+FixtureBot lets you define your test data in a Ruby DSL and compiles it into standard Rails fixture YAML files. The generated YAML is deterministic and should be checked into git, just like a lockfile. Your tests never see FixtureBot at runtime; Rails just loads the YAML fixtures as usual.
+
+**Features:**
+
+- **Ruby DSL** for defining records, associations, and join tables
+- **Generators** for filling in required columns (like email) across all records
+- **Stable IDs** so foreign keys are consistent and diffs are clean across runs
+- **Schema auto-detection** from your Rails database (no manual column lists)
+- **Auto-generates** before your test suite runs (RSpec and Minitest)
+
+## Read the article
+
+More background at [BeautifulRuby.com](https://beautifulruby.com/code/fixturebot).
+
+[![Screenshot of Don't throw the specs out with the factories article](https://immutable.terminalwire.com/frotvIWicKOgyNTufNGKSjpaI3RecS7IoO4hAWFycOC4zMopBylYljvcg62Br7NGHwsMikw3U5eLxQ0CpI7aVaVkLNLhCYK6OYI9.jpeg)](https://beautifulruby.com/code/fixturebot)
+
+## Quick example
+
+```ruby
+# spec/fixtures.rb
+FixtureBot.define do
+  # Generators fill in required columns so you don't have to repeat yourself.
+  # |fixture| gives you the fixture key; bare methods give column values.
+  user.email { |fixture| "#{fixture.key}@example.com" }
+
+  user :brad do
+    name "Brad"
+    email "brad@example.com"  # overrides the generator
+  end
+
+  user :alice do
+    name "Alice"              # email filled in by generator: "alice@example.com"
+  end
+
+  user :deactivated do
+    name "Ghost"
+    email nil                 # explicit nil, generator skipped, email set to null
+  end
+
+  post :hello_world do
+    title "Hello World"
+    body "Welcome to the blog!"
+    author :brad              # sets author_id to brad's stable ID
+    tags :ruby, :rails        # creates rows in posts_tags
+  end
+
+  tag.name { |fixture| fixture.key.to_s.capitalize }
+
+  tag :ruby                   # name: "Ruby"
+  tag :rails                  # name: "Rails"
+end
+```
+
+This generates YAML files like `users.yml`, `posts.yml`, `tags.yml`, and `posts_tags.yml` in your fixtures directory. Use them in tests like any other fixture:
+
+```ruby
+# RSpec
+RSpec.describe Post, type: :model do
+  fixtures :all
+
+  it "belongs to an author" do
+    post = posts(:hello_world)
+    expect(post.author).to eq(users(:brad))
+  end
+end
+
+# Minitest
+class PostTest < ActiveSupport::TestCase
+  def test_belongs_to_author
+    post = posts(:hello_world)
+    assert_equal users(:brad), post.author
+  end
+end
+```
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "fixturebot-rails"
+```
+
+### Rails generator
+
+The easiest way to get started:
+
+```bash
+rails generate fixturebot:install
+```
+
+This creates `spec/fixtures.rb` (RSpec) or `test/fixtures.rb` (Minitest) with a skeleton DSL file and adds the appropriate require to your test helper.
+
+### Manual setup
+
+#### RSpec
+
+Add to `spec/rails_helper.rb`:
+
+```ruby
+require "fixturebot/rspec"
+```
+
+Create `spec/fixtures.rb` with your fixture definitions.
+
+Fixtures are auto-generated before each suite run, no rake task needed.
+
+#### Minitest
+
+Add to `test/test_helper.rb`:
+
+```ruby
+require "fixturebot/minitest"
+```
+
+Create `test/fixtures.rb` with your fixture definitions.
+
+Fixtures are auto-generated when the helper is loaded, no rake task needed.
+
+### Rake task
+
+A `fixturebot:compile` rake task is also available if you prefer manual control:
+
+```bash
+bundle exec rake fixturebot:compile
+```
+
+### Configuration
+
+FixtureBot auto-detects your fixtures file (`test/fixtures.rb` or `spec/fixtures.rb`) and derives the output directory by stripping `.rb` (e.g. `spec/fixtures.rb` writes to `spec/fixtures/`). To override:
+
+```ruby
+# config/application.rb or config/environments/test.rb
+config.fixturebot.fixtures_file = "test/my_fixtures.rb"
+config.fixturebot.output_dir = "test/fixtures"
+```
+
+## The DSL
+
+### Records
+
+Define named records with literal column values:
+
+```ruby
+FixtureBot.define do
+  user :brad do
+    name "Brad"
+    email "brad@example.com"
+  end
+end
+```
+
+Records without a block get an auto-generated ID and any generator defaults:
+
+```ruby
+FixtureBot.define do
+  user.email { |fixture| "#{fixture.key}@example.com" }
+
+  user :alice
+  # => { id: <stable_id>, email: "alice@example.com" }
+end
+```
+
+### Generators
+
+Generators set default column values. They run for each record that doesn't explicitly set that column. Generators are never created implicitly; columns without a value or generator are omitted from the YAML output (Rails uses the database column default).
+
+```ruby
+FixtureBot.define do
+  user.email { |fixture| "#{fixture.key}@example.com" }
+end
+```
+
+The generator block receives a `fixture` object as a block parameter with access to `fixture.key` (the record's symbol name). Bare methods inside the block refer to column values set on the record.
+
+When a generator covers all the columns you need, records don't need a block at all:
+
+```ruby
+FixtureBot.define do
+  tag.name { |fixture| fixture.key.to_s.capitalize }
+
+  tag :ruby     # name: "Ruby"
+  tag :rails    # name: "Rails"
+  tag :testing  # name: "Testing"
+end
+```
+
+A literal value shadows the generator. An explicit `nil` also shadows it:
+
+```ruby
+FixtureBot.define do
+  user.email { |fixture| "#{fixture.key}@example.com" }
+
+  user :brad do
+    name "Brad"
+    email "brad@hey.com"  # literal, skips the generator
+  end
+
+  user :alice do
+    name "Alice"
+    # no email set, generator produces "alice@example.com"
+  end
+
+  user :deactivated do
+    name "Ghost"
+    email nil              # explicit nil, skips the generator, sets email to null
+  end
+end
+```
+
+### Associations
+
+Reference other records by name for `belongs_to`:
+
+```ruby
+FixtureBot.define do
+  post :hello_world do
+    title "Hello World"
+    author :brad  # sets author_id to brad's stable ID
+  end
+end
+```
+
+### Join tables (HABTM)
+
+Reference multiple records for join table associations:
+
+```ruby
+FixtureBot.define do
+  post :hello_world do
+    title "Hello World"
+    tags :ruby, :rails  # creates rows in posts_tags
+  end
+end
+```
+
+### Implicit vs explicit style
+
+By default, the block is evaluated implicitly. Table methods like `user` and `post` are available directly:
+
+```ruby
+FixtureBot.define do
+  user :brad do
+    name "Brad"
+  end
+end
+```
+
+If you prefer an explicit receiver (useful for editor autocompletion or clarity in large files), pass a block argument:
+
+```ruby
+FixtureBot.define do |t|
+  t.user :brad do
+    name "Brad"
+  end
+end
+```
+
+Both styles are equivalent. Record blocks (the inner `do...end`) are always implicit.
+
+### Schema
+
+FixtureBot reads your database schema automatically in Rails. Outside of Rails, you can define it by hand:
+
+```ruby
+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
+
+  table :tags, singular: :tag, columns: [:name]
+
+  join_table :posts_tags, :posts, :tags
+end
+```
+
+## Prior art
+
+### [Rails fixtures](https://guides.rubyonrails.org/testing.html#the-low-down-on-fixtures)
+
+Rails fixtures are YAML files that get loaded into the database once before your test suite runs. Each test wraps in a transaction and rolls back, so the data is always clean and tests are fast. This is the approach FixtureBot builds on.
+
+The problem is writing YAML by hand. Foreign keys are magic strings (`author: brad`), there's no way to DRY up repeated columns, and large fixture files are hard to read. FixtureBot gives you a Ruby DSL that compiles down to the same YAML, so you keep the speed of fixtures without the pain of maintaining them.
+
+### [FactoryBot](https://github.com/thoughtbot/factory_bot)
+
+FactoryBot creates records on the fly inside each test. You call `create(:user)` and it inserts a row. This makes tests self-contained and easy to read, but it's slow. Every test that needs data pays the cost of inserting records, and complex object graphs lead to cascading `create` calls.
+
+FixtureBot borrows the DSL feel of FactoryBot (named records, associations by symbol, default generators) but compiles to fixtures instead of inserting at runtime. You get the ergonomics of factories with the speed of fixtures.
+
+### [Oaken](https://github.com/kaspth/oaken)
+
+Oaken and FixtureBot share the same motivation: replace hand-written YAML fixtures with a Ruby DSL. They take very different approaches.
+
+**Oaken inserts records into the database** at runtime using `ActiveRecord::Base#create!`. It also supports loading different seed files per test case (`seed "cases/pagination"`), which means your data set can vary across tests. This flexibility comes at a cost: you lose the "load once, wrap every test in a transaction" speed advantage that makes Rails fixtures fast. It's closer to factories in that regard, with more structure around organizing seed scripts.
+
+**FixtureBot is more opinionated.** One fixture file, one data set, compiled to plain YAML and checked into git. At test time, FixtureBot is out of the picture entirely. Rails loads the YAML fixtures once and wraps each test in a transaction as usual. No runtime dependency, no per-test seeding, no seed file organization to manage.
+
+| | FixtureBot | Rails fixtures | FactoryBot | Oaken |
+|---|---|---|---|---|
+| **Define data in** | Ruby DSL | YAML | Ruby DSL | Ruby scripts |
+| **Output** | YAML files in git | YAML files in git | Database rows per test | Database rows at boot |
+| **Runtime dependency** | None | None | Required per test | Required at boot |
+| **Data set** | One set, loaded once | One set, loaded once | Built per test | Per-test via seed files |
+| **Speed** | Fast (fixtures) | Fast (fixtures) | Slow (inserts per test) | Varies |
+| **Stable IDs** | Deterministic | Deterministic | Database-assigned | Database-assigned |
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt.
+
+Try the playground without Rails:
+
+```bash
+bundle exec exe/fixturebot show ./playground/blog
+```

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/exe/fixturebot

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "fixturebot"
+
+if defined?(::Rails::Application)
+  require "fixturebot/rails"
+  FixtureBot::Rails::CLI.start(ARGV)
+else
+  FixtureBot::CLI.start(ARGV)
+end

data/lib/fixturebot/cli.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module FixtureBot
+  class CLI < Thor
+    def self.exit_on_failure?
+      true
+    end
+
+    desc "compile DIR", "Compile DIR/schema.rb and DIR/fixtures.rb to YAML fixture files"
+    def compile(dir)
+      schema_path = File.join(dir, "schema.rb")
+      fixtures_path = File.join(dir, "fixtures.rb")
+
+      raise Thor::Error, "Schema file not found: #{schema_path}" unless File.exist?(schema_path)
+      raise Thor::Error, "Fixtures file not found: #{fixtures_path}" unless File.exist?(fixtures_path)
+
+      schema = eval(File.read(schema_path), binding, schema_path, 1)
+      fixture_set = FixtureBot.define_from_file(schema, fixtures_path)
+
+      output_dir = File.join(dir, "fixtures")
+      Compiler.new(fixture_set).compile(output_dir)
+
+      say "Compiled fixtures to #{output_dir}/"
+      fixture_set.tables.each do |table_name, records|
+        next if records.empty?
+        say "  #{table_name}.yml (#{records.size} records)"
+      end
+    end
+
+    desc "show DIR", "Compile DIR/schema.rb and DIR/fixtures.rb, then print YAML to stdout"
+    def show(dir)
+      schema_path = File.join(dir, "schema.rb")
+      fixtures_path = File.join(dir, "fixtures.rb")
+
+      raise Thor::Error, "Schema file not found: #{schema_path}" unless File.exist?(schema_path)
+      raise Thor::Error, "Fixtures file not found: #{fixtures_path}" unless File.exist?(fixtures_path)
+
+      schema = eval(File.read(schema_path), binding, schema_path, 1)
+      fixture_set = FixtureBot.define_from_file(schema, fixtures_path)
+      compiler = FixtureBot::Compiler.new(fixture_set)
+
+      fixture_set.tables.each do |table_name, records|
+        next if records.empty?
+        puts "# #{table_name}.yml"
+        puts compiler.compile_table(table_name)
+      end
+    end
+
+    map %w[-v --version] => :version
+    desc "version", "Show version"
+    def version
+      say "fixturebot #{FixtureBot::VERSION}"
+    end
+  end
+end

data/lib/fixturebot/compiler.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+
+module FixtureBot
+  class Compiler
+    def initialize(fixture_set)
+      @fixture_set = fixture_set
+    end
+
+    def compile(output_dir)
+      FileUtils.mkdir_p(output_dir)
+      @fixture_set.tables.each do |table_name, records|
+        next if records.empty?
+        path = File.join(output_dir, "#{table_name}.yml")
+        File.write(path, compile_table(table_name))
+      end
+    end
+
+    def compile_table(table_name)
+      records = @fixture_set.tables[table_name]
+      hash = {}
+      records.each do |record_name, columns|
+        hash[record_name.to_s] = columns.transform_keys(&:to_s)
+      end
+      YAML.dump(hash).delete_prefix("---\n")
+    end
+  end
+end

data/lib/fixturebot/default.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module FixtureBot
+  module Default
+    Fixture = Data.define(:key)
+
+    class Definition
+      def initialize(table, defaults)
+        @defaults = defaults
+        define_column_methods(table)
+      end
+
+      private
+
+      def define_column_methods(table)
+        table.columns.each do |col|
+          define_singleton_method(col) do |&block|
+            raise ArgumentError, "#{col} requires a block" unless block
+            @defaults[col] = block
+          end
+        end
+      end
+    end
+
+    class Context
+      def initialize(literal_values: {})
+        define_literal_value_methods(literal_values)
+      end
+
+      private
+
+      def define_literal_value_methods(literal_values)
+        literal_values.each do |col, val|
+          define_singleton_method(col) { val }
+        end
+      end
+    end
+  end
+end

data/lib/fixturebot/definition.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module FixtureBot
+  class Definition
+    attr_reader :defaults, :rows
+
+    def initialize(schema)
+      @schema = schema
+      @defaults = {}
+      @rows = []
+
+      schema.tables.each_value do |table|
+        @defaults[table.name] = {}
+        define_table_method(table)
+      end
+    end
+
+    private
+
+    def define_table_method(table)
+      define_singleton_method(table.singular_name) do |record_name = nil, &block|
+        if record_name.nil? && block.nil?
+          Default::Definition.new(table, @defaults[table.name])
+        elsif record_name
+          add_row(table, record_name, block)
+        else
+          raise ArgumentError, "#{table.singular_name} requires a record name or no arguments"
+        end
+      end
+    end
+
+    def add_row(table, record_name, block)
+      row_def = Row::Definition.new(table, @schema)
+      row_def.instance_eval(&block) if block
+      @rows << Row::Declaration.new(
+        table: table.name,
+        name: record_name,
+        literal_values: row_def.literal_values,
+        association_refs: row_def.association_refs,
+        tag_refs: row_def.tag_refs
+      )
+    end
+  end
+end

data/lib/fixturebot/fixture_set.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module FixtureBot
+  class FixtureSet
+    attr_reader :tables
+
+    def initialize(schema, definition)
+      @tables = {}
+
+      schema.tables.each_key { |name| @tables[name] = {} }
+      schema.join_tables.each_key { |name| @tables[name] = {} }
+
+      definition.rows.each do |row|
+        builder = Row::Builder.new(
+          row: row,
+          table: schema.tables[row.table],
+          defaults: definition.defaults[row.table],
+          join_tables: schema.join_tables
+        )
+
+        @tables[row.table][row.name] = builder.record
+
+        builder.join_rows.each do |join_row|
+          @tables[join_row[:join_table]][join_row[:key]] = join_row[:row]
+        end
+      end
+    end
+  end
+end

data/lib/fixturebot/key.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "zlib"
+
+module FixtureBot
+  module Key
+    def self.generate(table_name, record_name)
+      Zlib.crc32("#{table_name}:#{record_name}") & 0x7FFFFFFF
+    end
+  end
+end

data/lib/fixturebot/minitest.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require "fixturebot/rails"
+
+FixtureBot::Rails.compile

data/lib/fixturebot/rails/cli.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "fixturebot/cli"
+
+module FixtureBot
+  module Rails
+    class CLI < FixtureBot::CLI
+      desc "compile FIXTURES_FILE [OUTPUT_DIR]", "Compile FixtureBot DSL to YAML fixture files"
+      def compile(fixtures_path, output_dir = "test/fixtures")
+        unless File.exist?(fixtures_path)
+          raise Thor::Error, "Fixtures file not found: #{fixtures_path}"
+        end
+
+        schema = SchemaLoader.load
+        fixture_set = FixtureBot.define_from_file(schema, fixtures_path)
+        Compiler.new(fixture_set).compile(output_dir)
+
+        say "Compiled fixtures to #{output_dir}/"
+        fixture_set.tables.each do |table_name, records|
+          next if records.empty?
+          say "  #{table_name}.yml (#{records.size} records)"
+        end
+      end
+    end
+  end
+end

data/lib/fixturebot/rails/railtie.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module FixtureBot
+  module Rails
+    class Railtie < ::Rails::Railtie
+      config.fixturebot = ActiveSupport::OrderedOptions.new
+
+      rake_tasks do
+        namespace :fixturebot do
+          desc "Compile FixtureBot DSL to YAML fixture files"
+          task compile: :environment do
+            FixtureBot::Rails.compile
+          end
+        end
+      end
+    end
+  end
+end