Add FactoryBot-compatible build/create/attributes_for syntax methods

Provide syntactic sugar so users migrating from FactoryBot can use
familiar methods like build(:user, :brad), create(:user, :brad), and
attributes_for(:user, :brad). These delegate to Rails fixture accessors
under the hood, requiring no new loading machinery.

Author: bradgessler

README.md

@@ -422,6 +422,40 @@ FixtureBot::Schema.define do
 end
 ```
 
+## Migrating from FactoryBot
+
+FixtureBot provides `build`, `create`, `attributes_for`, and related methods that mirror FactoryBot's API. The key difference is that you pass both a table name and a fixture name instead of just a factory name:
+
+```ruby
+# FactoryBot                    # FixtureBot
+build(:user)                    # build(:user, :brad)
+create(:user)                   # create(:user, :brad)
+build(:user, name: "X")        # build(:user, :brad, name: "X")
+attributes_for(:user)           # attributes_for(:user, :brad)
+build_list(:user, 3)            # build_list(:user, :brad, :alice, :bob)
+create_list(:user, 3)           # create_list(:user, :brad, :alice, :bob)
+build_pair(:user)               # build_pair(:user, :brad, :alice)
+create_pair(:user)              # create_pair(:user, :brad, :alice)
+build_stubbed(:user)            # build_stubbed(:user, :brad)
+```
+
+### Method reference
+
+| Method | Behavior |
+|---|---|
+| `build(:user, :brad, **attrs)` | Duplicates the fixture, applies overrides. Returns unpersisted. |
+| `create(:user, :brad, **attrs)` | Without overrides: returns the fixture (already persisted). With overrides: `build` + `save!`. |
+| `build_stubbed(:user, :brad, **attrs)` | Like `build` but retains `id`. Looks persisted without touching DB. |
+| `attributes_for(:user, :brad, **attrs)` | Returns attributes hash, strips `id`/`created_at`/`updated_at`. |
+| `build_list(:user, :brad, :alice, **attrs)` | Maps each name through `build`. |
+| `create_list(:user, :brad, :alice, **attrs)` | Maps each name through `create`. |
+| `build_pair(:user, :brad, :alice, **attrs)` | Alias for `build_list` with 2 names. |
+| `create_pair(:user, :brad, :alice, **attrs)` | Alias for `create_list` with 2 names. |
+| `build_stubbed_list(:user, :brad, :alice, **attrs)` | Maps each name through `build_stubbed`. |
+| `build_stubbed_pair(:user, :brad, :alice, **attrs)` | Alias for `build_stubbed_list` with 2 names. |
+
+These methods are automatically available in your tests when you require `fixturebot/rspec` or `fixturebot/minitest`. They call the standard Rails fixture accessors under the hood, so `build(:user, :brad)` is equivalent to `users(:brad).dup`.
+
 ## Prior art
 
 ### [Rails fixtures](https://guides.rubyonrails.org/testing.html#the-low-down-on-fixtures)

lib/fixturebot/minitest.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
 require "fixturebot/rails"
+require "fixturebot/syntax"
 
 FixtureBot::Rails.compile
+
+ActiveSupport::TestCase.include FixtureBot::Syntax::Methods

lib/fixturebot/rspec.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
 require "fixturebot/rails"
+require "fixturebot/syntax"
 
 RSpec.configure do |config|
   config.before(:suite) do
     FixtureBot::Rails.compile
   end
+
+  config.include FixtureBot::Syntax::Methods
 end

lib/fixturebot/syntax.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inflections"
+require "active_support/core_ext/hash/keys"
+
+module FixtureBot
+  module Syntax
+    module Methods
+      def build(table_name, fixture_name, **attributes)
+        record = send(table_name.to_s.pluralize, fixture_name).dup
+        record.assign_attributes(attributes) if attributes.any?
+        record
+      end
+
+      def create(table_name, fixture_name, **attributes)
+        if attributes.any?
+          build(table_name, fixture_name, **attributes).tap(&:save!)
+        else
+          send(table_name.to_s.pluralize, fixture_name)
+        end
+      end
+
+      def build_stubbed(table_name, fixture_name, **attributes)
+        source = send(table_name.to_s.pluralize, fixture_name)
+        attrs = source.attributes
+        attrs.merge!(attributes.stringify_keys) if attributes.any?
+        source.class.instantiate(attrs)
+      end
+
+      def attributes_for(table_name, fixture_name, **attributes)
+        send(table_name.to_s.pluralize, fixture_name)
+          .attributes
+          .symbolize_keys
+          .except(:id, :created_at, :updated_at)
+          .merge(attributes)
+      end
+
+      def build_list(table_name, *fixture_names, **attributes)
+        fixture_names.map { |name| build(table_name, name, **attributes) }
+      end
+
+      def create_list(table_name, *fixture_names, **attributes)
+        fixture_names.map { |name| create(table_name, name, **attributes) }
+      end
+
+      def build_pair(table_name, *fixture_names, **attributes)
+        build_list(table_name, *fixture_names, **attributes)
+      end
+
+      def create_pair(table_name, *fixture_names, **attributes)
+        create_list(table_name, *fixture_names, **attributes)
+      end
+
+      def build_stubbed_list(table_name, *fixture_names, **attributes)
+        fixture_names.map { |name| build_stubbed(table_name, name, **attributes) }
+      end
+
+      def build_stubbed_pair(table_name, *fixture_names, **attributes)
+        build_stubbed_list(table_name, *fixture_names, **attributes)
+      end
+    end
+  end
+end

spec/fixturebot/syntax_spec.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "fixturebot/syntax"
+
+RSpec.describe FixtureBot::Syntax::Methods do
+  let(:test_context) do
+    Object.new.tap do |ctx|
+      ctx.extend(FixtureBot::Syntax::Methods)
+
+      # Stub fixture accessor: users(:brad), users(:alice)
+      brad = double("brad",
+        id: 1,
+        attributes: { "id" => 1, "name" => "Brad", "email" => "brad@example.com", "created_at" => "2024-01-01", "updated_at" => "2024-01-01" },
+        class: user_class
+      )
+      allow(brad).to receive(:dup).and_return(
+        double("brad_dup",
+          id: nil,
+          new_record?: true,
+          persisted?: false,
+          class: user_class
+        ).tap do |dup|
+          allow(dup).to receive(:assign_attributes)
+          allow(dup).to receive(:save!)
+        end
+      )
+
+      alice = double("alice",
+        id: 2,
+        attributes: { "id" => 2, "name" => "Alice", "email" => "alice@example.com", "created_at" => "2024-01-01", "updated_at" => "2024-01-01" },
+        class: user_class
+      )
+      allow(alice).to receive(:dup).and_return(
+        double("alice_dup",
+          id: nil,
+          new_record?: true,
+          persisted?: false,
+          class: user_class
+        ).tap do |dup|
+          allow(dup).to receive(:assign_attributes)
+          allow(dup).to receive(:save!)
+        end
+      )
+
+      allow(ctx).to receive(:users).with(:brad).and_return(brad)
+      allow(ctx).to receive(:users).with(:alice).and_return(alice)
+    end
+  end
+
+  let(:user_class) do
+    klass = double("User")
+    allow(klass).to receive(:instantiate) do |attrs|
+      double("stubbed_user", id: attrs["id"], persisted?: true, new_record?: false, **attrs.transform_keys(&:to_sym))
+    end
+    klass
+  end
+
+  describe "#build" do
+    it "returns a dup of the fixture record" do
+      result = test_context.build(:user, :brad)
+      expect(result.new_record?).to be true
+    end
+
+    it "applies attribute overrides" do
+      result = test_context.build(:user, :brad, name: "Changed")
+      expect(result).to have_received(:assign_attributes).with(name: "Changed")
+    end
+
+    it "does not call assign_attributes when no overrides given" do
+      result = test_context.build(:user, :brad)
+      expect(result).not_to have_received(:assign_attributes)
+    end
+  end
+
+  describe "#create" do
+    it "returns the original fixture when no overrides given" do
+      result = test_context.create(:user, :brad)
+      expect(result.id).to eq(1)
+    end
+
+    it "builds and saves when overrides are given" do
+      result = test_context.create(:user, :brad, name: "Changed")
+      expect(result).to have_received(:assign_attributes).with(name: "Changed")
+      expect(result).to have_received(:save!)
+    end
+  end
+
+  describe "#build_stubbed" do
+    it "retains the id from the fixture" do
+      result = test_context.build_stubbed(:user, :brad)
+      expect(result.id).to eq(1)
+    end
+
+    it "uses model class instantiate" do
+      test_context.build_stubbed(:user, :brad)
+      expect(user_class).to have_received(:instantiate)
+    end
+
+    it "merges attribute overrides" do
+      result = test_context.build_stubbed(:user, :brad, name: "Stubbed")
+      expect(result.name).to eq("Stubbed")
+    end
+  end
+
+  describe "#attributes_for" do
+    it "returns a hash without id, created_at, updated_at" do
+      result = test_context.attributes_for(:user, :brad)
+      expect(result).to eq({ name: "Brad", email: "brad@example.com" })
+    end
+
+    it "merges attribute overrides" do
+      result = test_context.attributes_for(:user, :brad, name: "Override")
+      expect(result[:name]).to eq("Override")
+    end
+  end
+
+  describe "#build_list" do
+    it "returns a record for each fixture name" do
+      results = test_context.build_list(:user, :brad, :alice)
+      expect(results.length).to eq(2)
+      expect(results).to all(be_truthy)
+    end
+  end
+
+  describe "#create_list" do
+    it "returns a record for each fixture name" do
+      results = test_context.create_list(:user, :brad, :alice)
+      expect(results.length).to eq(2)
+    end
+  end
+
+  describe "#build_pair" do
+    it "returns two records" do
+      results = test_context.build_pair(:user, :brad, :alice)
+      expect(results.length).to eq(2)
+    end
+  end
+
+  describe "#create_pair" do
+    it "returns two records" do
+      results = test_context.create_pair(:user, :brad, :alice)
+      expect(results.length).to eq(2)
+    end
+  end
+
+  describe "#build_stubbed_list" do
+    it "returns stubbed records for each fixture name" do
+      results = test_context.build_stubbed_list(:user, :brad, :alice)
+      expect(results.length).to eq(2)
+      expect(results.first.id).to eq(1)
+      expect(results.last.id).to eq(2)
+    end
+  end
+
+  describe "#build_stubbed_pair" do
+    it "returns two stubbed records" do
+      results = test_context.build_stubbed_pair(:user, :brad, :alice)
+      expect(results.length).to eq(2)
+    end
+  end
+end

spec/integration/rails_app_spec.rb

@@ -157,4 +157,68 @@ def run_cmd!(cmd, chdir:, unbundled: true)
     expect(File.exist?(File.join(fixtures_dir, "tags.yml"))).to be true
     expect(File.exist?(File.join(fixtures_dir, "posts_tags.yml"))).to be true
   end
+
+  it "supports build, create, and attributes_for via FixtureBot::Syntax::Methods" do
+    # Write a Minitest test that exercises the syntax methods
+    test_file = File.join(@app_dir, "test", "syntax_test.rb")
+    File.write(test_file, <<~RUBY)
+      require "test_helper"
+
+      class SyntaxTest < ActiveSupport::TestCase
+        fixtures :all
+
+        test "build returns unpersisted dup" do
+          blog = build(:blog, :tech)
+          assert blog.new_record?, "build should return an unpersisted record"
+          assert_equal "Tech Blog", blog.title
+        end
+
+        test "build with overrides" do
+          blog = build(:blog, :tech, title: "Overridden")
+          assert_equal "Overridden", blog.title
+        end
+
+        test "create without overrides returns persisted fixture" do
+          blog = create(:blog, :tech)
+          assert blog.persisted?
+          assert_equal "Tech Blog", blog.title
+        end
+
+        test "create with overrides saves new record" do
+          blog = create(:blog, :tech, title: "New Title")
+          assert blog.persisted?
+          assert_equal "New Title", blog.title
+        end
+
+        test "attributes_for returns hash without id and timestamps" do
+          attrs = attributes_for(:blog, :tech)
+          assert_equal "Tech Blog", attrs[:title]
+          assert_nil attrs[:id]
+          assert_nil attrs[:created_at]
+          assert_nil attrs[:updated_at]
+        end
+
+        test "build_list returns multiple records" do
+          blogs = build_list(:blog, :tech, :personal)
+          assert_equal 2, blogs.length
+          assert blogs.all?(&:new_record?)
+        end
+
+        test "create_list returns multiple persisted records" do
+          blogs = create_list(:blog, :tech, :personal)
+          assert_equal 2, blogs.length
+          assert blogs.all?(&:persisted?)
+        end
+
+        test "build_stubbed retains id and looks persisted" do
+          blog = build_stubbed(:blog, :tech)
+          assert_not_nil blog.id
+          assert_equal "Tech Blog", blog.title
+        end
+      end
+    RUBY
+
+    output = run_cmd!("bin/rails test test/syntax_test.rb", chdir: @app_dir)
+    expect(output).to match(/0 failures/)
+  end
 end