fixturebot-rails 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47f7ad238dac229d37e2bdef254074b14d31657e57775db19f47cbddc06ffe16
-  data.tar.gz: e8c506013cc891b6f2f2d93e05d044c53ee5687ffa7cb628a7bf472f34fa4056
+  metadata.gz: 8c83c05f009409eb651e9e464fcc70bad3b3abeb377943eef42bfff31b29f9ac
+  data.tar.gz: 79973f2828cb2dcb83c4f238ad1023681c0a241d0f7ca1daab13ad1627685f64
 SHA512:
-  metadata.gz: f801adcf5885114ba66a13a9d7d472b908c9b6ed7de49426c007a70efced6293ba12683253b9cbe7bb38cceaf97902f2642acea3e44ec8522d74da21a57038bb
-  data.tar.gz: c6972d1aed753deed6d109126302ac2267cf99dddb4e5ff45f981bb63753831292e5a44f2d743f11a5a9680f9b088152234ccef8184f1c07ecb0b33de9ee0dfa
+  metadata.gz: b3c5cfd9eeb975bb9209a2a3e37ca98d7a00225b6c63f638c3f4bdc2a44ff2782eebfcc4616a327d1134d3bcf3dcbbc0a5a661918ab1f4b6fefdffc4ebefed96
+  data.tar.gz: 3ea33f5090363d4ee7c8be75720e7fa1a8364c7665304824071d08fd2e5912be7f0d293f9255c7c69f61a0bafc9c06d9ca600954e33d6adb321dba1a748b10eb

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.3.0
+
+### Added
+
+- **UUID primary keys.** Tables with UUID primary keys are auto-detected in Rails. For manual schemas, pass `key: FixtureBot::Key::Uuid`. Generates deterministic UUID v5 values.
+- **Polymorphic associations.** Use `votable post(:hello)` to set both `votable_id` and `votable_type: "Post"`. Auto-detected in Rails from `_id`/`_type` column pairs without foreign key constraints. For manual schemas, declare with `polymorphic :votable`.
+- **Custom key strategies.** Any module or object responding to `generate(table_name, record_name)` can be passed as `key:` on a table definition.
+- **Custom primary key columns.** Tables using a column other than `id` as the primary key are auto-detected in Rails. For manual schemas, pass `primary_key: :uid`.
+- **Hardcoded IDs.** Set `id 42` in a record block to override the generated key. Foreign key references resolve to the hardcoded value.
+
+### Internals
+
+- Key generation strategies (`Key::Integer`, `Key::Uuid`) are stateless modules instead of a single `Key.generate` method.
+- All association types share a unified `resolve(ref, keys)` interface.
+- `KeyRegistry` pre-computes primary key values for all records.
+- `Default::Generator` wraps generator blocks instead of passing raw procs.
+- Foreign key naming conventions (`_id`, `_type`) live as class methods on `BelongsTo` and `PolymorphicBelongsTo`.
+- File-based `define` uses thread-local state instead of module-level `@pending_blocks`.
+
 ## 0.2.0
 
 ### Breaking changes

data/README.md

@@ -9,6 +9,8 @@ FixtureBot lets you define your test data in a Ruby DSL and compiles it into sta
 - **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
+- **UUID support** for tables with UUID primary keys
+- **Polymorphic associations** with automatic type column resolution
 - **Schema auto-detection** from your Rails database (no manual column lists)
 - **Auto-generates** before your test suite runs (RSpec and Minitest)
 
@@ -175,7 +177,13 @@ FixtureBot.define do
 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.
+The generator block receives a `fixture` object with a `key` method (the record's symbol name). Bare methods inside the block refer to column values set on the record:
+
+```ruby
+FixtureBot.define do
+  user.display_name { |fixture| "#{fixture.key} (#{email})" }
+end
+```
 
 When a generator covers all the columns you need, records don't need a block at all:
 
@@ -225,6 +233,46 @@ FixtureBot.define do
 end
 ```
 
+### Polymorphic associations
+
+For polymorphic `belongs_to`, reference the target using its table helper to set both `_id` and `_type` columns:
+
+```ruby
+FixtureBot.define do
+  post :hello do
+    title "Hello"
+  end
+
+  comment :nice do
+    body "Nice post"
+  end
+
+  vote :upvote_post do
+    votable post(:hello)       # sets votable_id and votable_type: "Post"
+  end
+
+  vote :upvote_comment do
+    votable comment(:nice)     # sets votable_id and votable_type: "Comment"
+  end
+end
+```
+
+In the manual schema, declare polymorphic associations with `polymorphic`:
+
+```ruby
+FixtureBot::Schema.define do
+  table :posts, singular: :post, columns: [:title]
+  table :comments, singular: :comment, columns: [:body]
+
+  table :votes, singular: :vote, columns: [:votable_id, :votable_type, :voter_id] do
+    polymorphic :votable
+    belongs_to :voter, table: :users
+  end
+end
+```
+
+In Rails, polymorphic associations are auto-detected from `_id`/`_type` column pairs that don't have a foreign key constraint.
+
 ### Join tables (HABTM)
 
 Reference multiple records for join table associations:
@@ -238,6 +286,100 @@ FixtureBot.define do
 end
 ```
 
+### Hardcoded IDs
+
+By default, FixtureBot generates stable IDs deterministically from the table and record name. You can override this with an explicit value:
+
+```ruby
+FixtureBot.define do
+  user :admin do
+    id 42
+    name "Admin"
+  end
+
+  post :hello do
+    title "Hello"
+    author :admin  # author_id resolves to 42
+  end
+end
+```
+
+### UUID primary keys
+
+Tables with UUID primary keys work automatically in Rails (detected from the column type). In the manual schema, pass `key: FixtureBot::Key::Uuid`:
+
+```ruby
+FixtureBot::Schema.define do
+  table :projects, singular: :project, columns: [:name], key: FixtureBot::Key::Uuid
+end
+```
+
+FixtureBot generates deterministic UUID v5 values, so the output is stable across runs.
+
+You can also provide your own key strategy — any object (or module) that responds to `generate(table_name, record_name)`. For example, Stripe-style prefixed IDs:
+
+```ruby
+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
+  # => customer_id: "customer_1a2b3c"
+end
+```
+
+### Custom primary key column
+
+If your table uses a column other than `id` as the primary key:
+
+```ruby
+FixtureBot::Schema.define do
+  table :users, singular: :user, columns: [:name], primary_key: :uid
+end
+```
+
+In Rails, this is auto-detected from the database.
+
+### Multiple files
+
+For larger apps, split fixtures across multiple files using `FixtureBot.require`:
+
+```ruby
+# spec/fixtures.rb
+FixtureBot.require "spec/fixtures/**/*.rb"
+
+FixtureBot.define do
+  user.email { |fixture| "#{fixture.key}@example.com" }
+end
+```
+
+```ruby
+# spec/fixtures/users.rb
+FixtureBot.define do
+  user :brad do
+    name "Brad"
+  end
+end
+```
+
+```ruby
+# spec/fixtures/posts.rb
+FixtureBot.define do
+  post :hello do
+    title "Hello"
+    author :brad
+  end
+end
+```
+
+Each file calls `FixtureBot.define` with its own block. Files are loaded in alphabetical order. References across files work because everything is resolved after all files are loaded.
+
 ### Implicit vs explicit style
 
 By default, the block is evaluated implicitly. Table methods like `user` and `post` are available directly:
@@ -280,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)

data/lib/fixturebot/cli.rb

@@ -10,14 +10,7 @@ module FixtureBot
 
     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)
+      fixture_set = load_fixture_set(dir)
 
       output_dir = File.join(dir, "fixtures")
       Compiler.new(fixture_set).compile(output_dir)
@@ -31,15 +24,8 @@ module FixtureBot
 
     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 = load_fixture_set(dir)
+      compiler = Compiler.new(fixture_set)
 
       fixture_set.tables.each do |table_name, records|
         next if records.empty?
@@ -53,5 +39,18 @@ module FixtureBot
     def version
       say "fixturebot #{FixtureBot::VERSION}"
     end
+
+    private
+
+    def load_fixture_set(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)
+      FixtureBot.define_from_file(schema, fixtures_path)
+    end
   end
 end

data/lib/fixturebot/default.rb

@@ -2,8 +2,6 @@
 
 module FixtureBot
   module Default
-    Fixture = Data.define(:key)
-
     class Definition
       def initialize(table, defaults)
         @defaults = defaults
@@ -16,22 +14,39 @@ module FixtureBot
         table.columns.each do |col|
           define_singleton_method(col) do |&block|
             raise ArgumentError, "#{col} requires a block" unless block
-            @defaults[col] = block
+            @defaults[col] = Generator.new(block)
           end
         end
       end
     end
 
-    class Context
-      def initialize(literal_values: {})
-        define_literal_value_methods(literal_values)
+    Fixture = Data.define(:key)
+
+    class Generator
+      def initialize(block)
+        @block = block
+      end
+
+      def generate(record_name, literal_values)
+        context = Context.new(literal_values)
+        context.instance_exec(Fixture.new(key: record_name), &@block)
       end
 
       private
 
-      def define_literal_value_methods(literal_values)
-        literal_values.each do |col, val|
-          define_singleton_method(col) { val }
+      Context = Struct.new(:literal_values) do
+        private
+
+        def method_missing(name, *)
+          if literal_values.key?(name)
+            literal_values[name]
+          else
+            super
+          end
+        end
+
+        def respond_to_missing?(name, *)
+          literal_values.key?(name) || super
         end
       end
     end

data/lib/fixturebot/definition.rb

@@ -33,7 +33,7 @@ module FixtureBot
       row_def = Row::Definition.new(table, @schema)
       row_def.instance_eval(&block) if block
       @rows << Row::Declaration.new(
-        table: table.name,
+        table_name: table.name,
         name: record_name,
         literal_values: row_def.literal_values,
         association_refs: row_def.association_refs,

data/lib/fixturebot/fixture_set.rb

@@ -10,18 +10,21 @@ module FixtureBot
       schema.tables.each_key { |name| @tables[name] = {} }
       schema.join_tables.each_key { |name| @tables[name] = {} }
 
+      keys = KeyRegistry.new(definition.rows, schema.tables)
+
       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
+          table: schema.tables[row.table_name],
+          defaults: definition.defaults[row.table_name],
+          join_tables: schema.join_tables,
+          keys: keys
         )
 
-        @tables[row.table][row.name] = builder.record
+        @tables[row.table_name][row.name] = builder.record
 
         builder.join_rows.each do |join_row|
-          @tables[join_row[:join_table]][join_row[:key]] = join_row[:row]
+          @tables[join_row.join_table][join_row.key] = join_row.row
         end
       end
     end

data/lib/fixturebot/key/integer.rb

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

data/lib/fixturebot/key/uuid.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "digest/sha1"
+
+module FixtureBot
+  module Key
+    module Uuid
+      NAMESPACE = "fixturebot"
+
+      module_function
+
+      def generate(table_name, record_name)
+        digest = Digest::SHA1.digest("#{NAMESPACE}:#{table_name}:#{record_name}")
+        # Set version 5 (bits 4-7 of byte 6)
+        digest[6] = ((digest[6].ord & 0x0f) | 0x50).chr
+        # Set variant (bits 6-7 of byte 8)
+        digest[8] = ((digest[8].ord & 0x3f) | 0x80).chr
+
+        hex = digest[0, 16].unpack1("H*")
+        "#{hex[0, 8]}-#{hex[8, 4]}-#{hex[12, 4]}-#{hex[16, 4]}-#{hex[20, 12]}"
+      end
+    end
+  end
+end

data/lib/fixturebot/key.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
-require "zlib"
+require_relative "key/integer"
+require_relative "key/uuid"
 
 module FixtureBot
   module Key
+    # Backward compatibility
     def self.generate(table_name, record_name)
-      Zlib.crc32("#{table_name}:#{record_name}") & 0x7FFFFFFF
+      Integer.generate(table_name, record_name)
     end
   end
 end

data/lib/fixturebot/key_registry.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module FixtureBot
+  class KeyRegistry
+    def initialize(rows, schema_tables)
+      @values = {}
+
+      rows.each do |row|
+        table = schema_tables[row.table_name]
+        pk_col = table.primary_key
+        @values[[row.table_name, row.name]] = if row.literal_values.key?(pk_col)
+          row.literal_values[pk_col]
+        else
+          table.key.generate(row.table_name, row.name)
+        end
+      end
+    end
+
+    def resolve(table_name, record_name)
+      @values.fetch([table_name, record_name])
+    end
+  end
+end

data/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

data/lib/fixturebot/rails/schema_loader.rb

@@ -38,11 +38,15 @@ module FixtureBot
       end
 
       def build_table(name)
+        pk_column_name = @connection.primary_key(name) || "id"
+        pk_column = @connection.columns(name).find { |c| c.name == pk_column_name }
+        key = pk_column && pk_column.type == :uuid ? Key::Uuid : Key::Integer
+
         columns = @connection.columns(name)
-          .reject { |c| framework_column?(c.name) }
+          .reject { |c| c.name == pk_column_name || timestamp_column?(c.name) }
           .map { |c| c.name.to_sym }
 
-        associations = @connection.foreign_keys(name).map do |fk|
+        fk_associations = @connection.foreign_keys(name).map do |fk|
           Schema::BelongsTo.new(
             name: association_name(fk.column),
             table: fk.to_table.to_sym,
@@ -50,11 +54,17 @@ module FixtureBot
           )
         end
 
+        polymorphic_associations = detect_polymorphic_associations(name, columns, fk_associations)
+
+        associations = fk_associations + polymorphic_associations
+
         Schema::Table.new(
           name: name.to_sym,
           singular_name: singularize(name),
           columns: columns,
-          belongs_to_associations: associations
+          associations: associations,
+          key: key,
+          primary_key: pk_column_name.to_sym
         )
       end
 
@@ -74,8 +84,8 @@ module FixtureBot
         @connection.tables - %w[ar_internal_metadata schema_migrations]
       end
 
-      def framework_column?(name)
-        %w[id created_at updated_at].include?(name)
+      def timestamp_column?(name)
+        %w[created_at updated_at].include?(name)
       end
 
       def foreign_key_column?(column)
@@ -110,6 +120,25 @@ module FixtureBot
           foreign_key_columns(name).size == 2
         end
       end
+
+      def detect_polymorphic_associations(table_name, columns, fk_associations)
+        fk_column_names = fk_associations.map { |a| a.foreign_key }
+        id_columns = columns.select { |c| c.to_s.end_with?("_id") }
+
+        id_columns.filter_map do |id_col|
+          next if fk_column_names.include?(id_col)
+
+          name = id_col.to_s.sub(/_id$/, "").to_sym
+          type_col = Schema::PolymorphicBelongsTo.foreign_type(name)
+          next unless columns.include?(type_col)
+
+          Schema::PolymorphicBelongsTo.new(
+            name: name,
+            foreign_key: id_col,
+            foreign_type: type_col
+          )
+        end
+      end
     end
   end
 end

data/lib/fixturebot/row.rb

@@ -2,7 +2,10 @@
 
 module FixtureBot
   module Row
-    Declaration = Data.define(:table, :name, :literal_values, :association_refs, :tag_refs)
+    TableReference = Data.define(:table_name, :record_name)
+    TagRef = Data.define(:other_table, :refs)
+    JoinRow = Data.define(:key, :join_table, :row)
+    Declaration = Data.define(:table_name, :name, :literal_values, :association_refs, :tag_refs)
 
     class Definition
       attr_reader :literal_values, :association_refs, :tag_refs
@@ -13,8 +16,10 @@ module FixtureBot
         @tag_refs = {}
 
         define_column_methods(table)
+        define_primary_key_method(table)
         define_association_methods(table)
         define_join_table_methods(table, schema)
+        define_table_reference_methods(schema, table)
       end
 
       private
@@ -27,8 +32,15 @@ module FixtureBot
         end
       end
 
+      def define_primary_key_method(table)
+        pk_col = table.primary_key
+        define_singleton_method(pk_col) do |value|
+          @literal_values[pk_col] = value
+        end unless respond_to?(pk_col)
+      end
+
       def define_association_methods(table)
-        table.belongs_to_associations.each do |assoc|
+        table.associations.each do |assoc|
           define_singleton_method(assoc.name) do |ref|
             @association_refs[assoc.name] = ref
           end
@@ -39,48 +51,58 @@ module FixtureBot
         schema.join_tables.each_value do |jt|
           if jt.left_table == table.name
             define_singleton_method(jt.right_table) do |*refs|
-              @tag_refs[jt.name] = { table: jt.right_table, refs: refs }
+              @tag_refs[jt.name] = TagRef.new(other_table: jt.right_table, refs: refs)
             end
           elsif jt.right_table == table.name
             define_singleton_method(jt.left_table) do |*refs|
-              @tag_refs[jt.name] = { table: jt.left_table, refs: refs }
+              @tag_refs[jt.name] = TagRef.new(other_table: jt.left_table, refs: refs)
             end
           end
         end
       end
+
+      def define_table_reference_methods(schema, table)
+        schema.tables.each_value do |t|
+          method_name = t.singular_name
+          next if respond_to?(method_name)
+          define_singleton_method(method_name) do |record_name|
+            TableReference.new(table_name: t.name, record_name: record_name)
+          end
+        end
+      end
     end
 
     class Builder
-      def initialize(row:, table:, defaults:, join_tables:)
+      def initialize(row:, table:, defaults:, join_tables:, keys:)
         @row = row
         @table = table
         @defaults = defaults
         @join_tables = join_tables
+        @keys = keys
       end
 
-      def id
-        @id ||= Key.generate(@row.table, @row.name)
+      def primary_key_value
+        @primary_key_value ||= @keys.resolve(@row.table_name, @row.name)
       end
 
       def record
-        result = { id: id }
+        values = {}
+          .merge!(defaulted_values)
+          .merge!(association_values)
+          .merge!(@row.literal_values)
+
+        result = { @table.primary_key => primary_key_value }
         @table.columns.each do |col|
-          if @row.literal_values.key?(col)
-            result[col] = @row.literal_values[col]
-          elsif foreign_key_values.key?(col)
-            result[col] = foreign_key_values[col]
-          elsif defaulted_values.key?(col)
-            result[col] = defaulted_values[col]
-          end
+          result[col] = values[col] if values.key?(col)
         end
         result
       end
 
       def join_rows
-        @row.tag_refs.flat_map do |join_table_name, tag_info|
+        @row.tag_refs.flat_map do |join_table_name, tag_ref|
           jt = @join_tables[join_table_name]
-          tag_info[:refs].map do |tag_ref|
-            build_join_row(jt, tag_info[:table], tag_ref)
+          tag_ref.refs.map do |ref|
+            build_join_row(jt, tag_ref.other_table, ref)
           end
         end
       end
@@ -88,38 +110,36 @@ module FixtureBot
       private
 
       def build_join_row(jt, other_table, tag_ref)
-        other_id = Key.generate(other_table, tag_ref)
+        other_id = @keys.resolve(other_table, tag_ref)
 
-        if jt.left_table == @row.table
-          {
+        if jt.left_table == @row.table_name
+          JoinRow.new(
             key: :"#{@row.name}_#{tag_ref}",
             join_table: jt.name,
-            row: { jt.left_foreign_key => id, jt.right_foreign_key => other_id }
-          }
+            row: { jt.left_foreign_key => primary_key_value, jt.right_foreign_key => other_id }
+          )
         else
-          {
+          JoinRow.new(
             key: :"#{tag_ref}_#{@row.name}",
             join_table: jt.name,
-            row: { jt.left_foreign_key => other_id, jt.right_foreign_key => id }
-          }
+            row: { jt.left_foreign_key => other_id, jt.right_foreign_key => primary_key_value }
+          )
         end
       end
 
-      def foreign_key_values
-        @foreign_key_values ||= @row.association_refs.each_with_object({}) do |(assoc_name, ref), hash|
-          assoc = @table.belongs_to_associations.find { |a| a.name == assoc_name }
-          hash[assoc.foreign_key] = Key.generate(assoc.table, ref)
+      def association_values
+        @association_values ||= @row.association_refs.each_with_object({}) do |(assoc_name, ref), hash|
+          assoc = @table.associations.find { |a| a.name == assoc_name }
+          hash.merge!(assoc.resolve(ref, @keys))
         end
       end
 
       def defaulted_values
-        @defaulted_values ||= @defaults.each_with_object({}) do |(col, block), result|
+        @defaulted_values ||= @defaults.each_with_object({}) do |(col, generator), result|
           next if @row.literal_values.key?(col)
-          next if foreign_key_values.key?(col)
+          next if association_values.key?(col)
 
-          fixture = Default::Fixture.new(key: @row.name)
-          context = Default::Context.new(literal_values: @row.literal_values)
-          result[col] = context.instance_exec(fixture, &block)
+          result[col] = generator.generate(@row.name, @row.literal_values)
         end
       end
     end

data/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

data/lib/fixturebot/schema.rb

@@ -2,8 +2,46 @@
 
 module FixtureBot
   class Schema
-    Table = Data.define(:name, :singular_name, :columns, :belongs_to_associations)
-    BelongsTo = Data.define(:name, :table, :foreign_key)
+    Table = Data.define(:name, :singular_name, :columns, :associations, :key, :primary_key) do
+      def initialize(name:, singular_name:, columns:, associations: [], key: Key::Integer, primary_key: :id)
+        super
+      end
+
+      def belongs_to_associations
+        associations.reject(&:polymorphic?)
+      end
+
+      def polymorphic_associations
+        associations.select(&:polymorphic?)
+      end
+    end
+
+    BelongsTo = Data.define(:name, :table, :foreign_key) do
+      def self.foreign_key(name) = :"#{name}_id"
+
+      def polymorphic? = false
+
+      def resolve(ref, keys)
+        { foreign_key => keys.resolve(table, ref) }
+      end
+    end
+
+    PolymorphicBelongsTo = Data.define(:name, :foreign_key, :foreign_type) do
+      def self.foreign_key(name) = :"#{name}_id"
+      def self.foreign_type(name) = :"#{name}_type"
+
+      def polymorphic? = true
+
+      def resolve(table_ref, keys)
+        require "active_support/inflector" unless defined?(ActiveSupport::Inflector)
+
+        {
+          foreign_key => keys.resolve(table_ref.table_name, table_ref.record_name),
+          foreign_type => ActiveSupport::Inflector.classify(table_ref.table_name.to_s)
+        }
+      end
+    end
+
     JoinTable = Data.define(:name, :left_table, :right_table, :left_foreign_key, :right_foreign_key)
 
     attr_reader :tables, :join_tables
@@ -33,7 +71,7 @@ module FixtureBot
         @schema = schema
       end
 
-      def table(name, singular:, columns: [], &block)
+      def table(name, singular:, columns: [], key: Key::Integer, primary_key: :id, &block)
         associations = []
         if block
           table_builder = TableBuilder.new(associations)
@@ -43,7 +81,9 @@ module FixtureBot
           name: name,
           singular_name: singular,
           columns: columns,
-          belongs_to_associations: associations
+          associations: associations,
+          key: key,
+          primary_key: primary_key
         ))
       end
 
@@ -54,8 +94,8 @@ module FixtureBot
           name: name,
           left_table: left_table,
           right_table: right_table,
-          left_foreign_key: :"#{left_singular}_id",
-          right_foreign_key: :"#{right_singular}_id"
+          left_foreign_key: BelongsTo.foreign_key(left_singular),
+          right_foreign_key: BelongsTo.foreign_key(right_singular)
         ))
       end
     end
@@ -66,8 +106,15 @@ module FixtureBot
       end
 
       def belongs_to(name, table:)
-        foreign_key = :"#{name}_id"
-        @associations << BelongsTo.new(name: name, table: table, foreign_key: foreign_key)
+        @associations << BelongsTo.new(name: name, table: table, foreign_key: BelongsTo.foreign_key(name))
+      end
+
+      def polymorphic(name)
+        @associations << PolymorphicBelongsTo.new(
+          name: name,
+          foreign_key: PolymorphicBelongsTo.foreign_key(name),
+          foreign_type: PolymorphicBelongsTo.foreign_type(name)
+        )
       end
     end
   end

data/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

data/lib/fixturebot/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FixtureBot
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/fixturebot.rb

@@ -6,6 +6,7 @@ require_relative "fixturebot/key"
 require_relative "fixturebot/default"
 require_relative "fixturebot/row"
 require_relative "fixturebot/definition"
+require_relative "fixturebot/key_registry"
 require_relative "fixturebot/fixture_set"
 require_relative "fixturebot/compiler"
 require_relative "fixturebot/cli"
@@ -14,28 +15,31 @@ module FixtureBot
   class Error < StandardError; end
 
   # Programmatic API: FixtureBot.define(schema) { ... }
-  # File API (no schema): FixtureBot.define { ... } — registers block for define_from_file
+  # File API (no schema): FixtureBot.define { ... } — evaluated against current_definition if set
   def self.define(schema = nil, &block)
     if schema
       definition = Definition.new(schema)
       evaluate_block(definition, block)
       FixtureSet.new(schema, definition)
-    else
-      @pending_blocks ||= []
-      @pending_blocks << block
+    elsif Thread.current[:fixturebot_definition]
+      evaluate_block(Thread.current[:fixturebot_definition], block)
       nil
+    else
+      raise Error, "FixtureBot.define without a schema must be called from within define_from_file"
     end
   end
 
-  def self.define_from_file(schema, fixtures_path)
-    @pending_blocks = []
-    content = File.read(fixtures_path)
-    eval(content, TOPLEVEL_BINDING, fixtures_path, 1)
+  def self.require(glob)
+    Dir.glob(glob).sort.each { |f| load f }
+  end
 
+  def self.define_from_file(schema, fixtures_path)
     definition = Definition.new(schema)
-    @pending_blocks.each { |blk| evaluate_block(definition, blk) }
-    @pending_blocks = nil
+    Thread.current[:fixturebot_definition] = definition
+    eval(File.read(fixtures_path), TOPLEVEL_BINDING, fixtures_path, 1)
     FixtureSet.new(schema, definition)
+  ensure
+    Thread.current[:fixturebot_definition] = nil
   end
 
   def self.evaluate_block(definition, block)

data/lib/generators/fixturebot/templates/fixtures.rb.tt

@@ -1,3 +1,5 @@
+FixtureBot.require "<%= rspec? ? "spec" : "test" %>/fixtures/**/*.rb"
+
 FixtureBot.define do
   # Define your fixtures here. Example:
   #

data/playground/blog/fixtures.rb

@@ -51,4 +51,19 @@ FixtureBot.define do
     post :tdd_guide
     author :brad
   end
+
+  vote :alice_likes_hello do
+    votable post(:hello_world)
+    voter :alice
+  end
+
+  vote :brad_likes_tdd do
+    votable post(:tdd_guide)
+    voter :brad
+  end
+
+  vote :charlie_likes_great_post do
+    votable comment(:great_post)
+    voter :charlie
+  end
 end

data/playground/blog/schema.rb

@@ -13,4 +13,9 @@ FixtureBot::Schema.define do
   table :tags, singular: :tag, columns: [:name]
 
   join_table :posts_tags, :posts, :tags
+
+  table :votes, singular: :vote, columns: [:votable_id, :votable_type, :voter_id] do
+    polymorphic :votable
+    belongs_to :voter, table: :users
+  end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: fixturebot-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Brad Gessler
 bindir: exe
 cert_chain: []
-date: 2026-02-09 00:00:00.000000000 Z
+date: 2026-03-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -74,6 +74,9 @@ files:
 - lib/fixturebot/definition.rb
 - lib/fixturebot/fixture_set.rb
 - lib/fixturebot/key.rb
+- lib/fixturebot/key/integer.rb
+- lib/fixturebot/key/uuid.rb
+- lib/fixturebot/key_registry.rb
 - lib/fixturebot/minitest.rb
 - lib/fixturebot/rails.rb
 - lib/fixturebot/rails/cli.rb
@@ -82,6 +85,7 @@ files:
 - lib/fixturebot/row.rb
 - lib/fixturebot/rspec.rb
 - lib/fixturebot/schema.rb
+- lib/fixturebot/syntax.rb
 - lib/fixturebot/version.rb
 - lib/generators/fixturebot/install_generator.rb
 - lib/generators/fixturebot/templates/fixtures.rb.tt