Wrap fixture DSL in FixtureBot.define block with implicit/explicit styles

Fixture files now require a FixtureBot.define { } wrapper, matching the
FactoryBot convention. Supports explicit receiver style via block arg
(FixtureBot.define { |t| t.user ... }) for editor autocompletion.

Author: bradgessler

README.md

@@ -25,32 +25,34 @@ The generated YAML files are static snapshots you can inspect, diff, and commit.
 Create `spec/fixtures.rb`:
 
 ```ruby
-# Generators — these run for every record unless overridden
-user.email { "#{name}@example.com" }
-
-# Records
-user :brad do
-  name "Brad"
-  email "brad@example.com"
-end
+FixtureBot.define do
+  # Generators — these run for every record unless overridden
+  user.email { "#{name}@example.com" }
+
+  # Records
+  user :brad do
+    name "Brad"
+    email "brad@example.com"
+  end
 
-user :alice do
-  name "Alice"
-end
+  user :alice do
+    name "Alice"
+  end
 
-post :hello_world do
-  title "Hello World"
-  body "Welcome to the blog!"
-  author :brad
-  tags :ruby, :rails
-end
+  post :hello_world do
+    title "Hello World"
+    body "Welcome to the blog!"
+    author :brad
+    tags :ruby, :rails
+  end
 
-tag :ruby do
-  name "Ruby"
-end
+  tag :ruby do
+    name "Ruby"
+  end
 
-tag :rails do
-  name "Rails"
+  tag :rails do
+    name "Rails"
+  end
 end
 ```
 
@@ -106,21 +108,23 @@ end
 Create `test/fixtures.rb`:
 
 ```ruby
-user.email { "#{name}@example.com" }
+FixtureBot.define do
+  user.email { "#{name}@example.com" }
 
-user :brad do
-  name "Brad"
-  email "brad@example.com"
-end
+  user :brad do
+    name "Brad"
+    email "brad@example.com"
+  end
 
-user :alice do
-  name "Alice"
-end
+  user :alice do
+    name "Alice"
+  end
 
-post :hello_world do
-  title "Hello World"
-  body "Welcome to the blog!"
-  author :brad
+  post :hello_world do
+    title "Hello World"
+    body "Welcome to the blog!"
+    author :brad
+  end
 end
 ```
 
@@ -173,27 +177,55 @@ FixtureBot::Schema.define do
 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.
+
 ### Generators
 
 Set default values for columns. The block runs for each record and has access to the record name:
 
 ```ruby
-user.email { "#{name}@example.com" }
+FixtureBot.define do
+  user.email { "#{name}@example.com" }
+end
 ```
 
 If a record sets a literal value for that column, it shadows the generator:
 
 ```ruby
-user.email { "#{name}@example.com" }
+FixtureBot.define do
+  user.email { "#{name}@example.com" }
 
-user :brad do
-  name "Brad"           # generator sees name as "Brad", not "brad"
-  email "brad@hey.com"  # literal — skips the generator entirely
-end
+  user :brad do
+    name "Brad"           # generator sees name as "Brad", not "brad"
+    email "brad@hey.com"  # literal — skips the generator entirely
+  end
 
-user :alice do
-  name "Alice"
-  # email generated as "Alice@example.com"
+  user :alice do
+    name "Alice"
+    # email generated as "Alice@example.com"
+  end
 end
 ```
 
@@ -202,27 +234,33 @@ end
 Define named records with literal column values:
 
 ```ruby
-user :brad do
-  name "Brad"
-  email "brad@example.com"
+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
-user :alice
-# => { id: <stable_id>, email: "alice@example.com" }
+FixtureBot.define do
+  user :alice
+  # => { id: <stable_id>, email: "alice@example.com" }
+end
 ```
 
 ### Associations
 
 Reference other records by name for `belongs_to`:
 
 ```ruby
-post :hello_world do
-  title "Hello World"
-  author :brad  # sets author_id to brad's stable ID
+FixtureBot.define do
+  post :hello_world do
+    title "Hello World"
+    author :brad  # sets author_id to brad's stable ID
+  end
 end
 ```
 
@@ -231,9 +269,11 @@ end
 Reference multiple records for join table associations:
 
 ```ruby
-post :hello_world do
-  title "Hello World"
-  tags :ruby, :rails  # creates rows in posts_tags
+FixtureBot.define do
+  post :hello_world do
+    title "Hello World"
+    tags :ruby, :rails  # creates rows in posts_tags
+  end
 end
 ```
 
@@ -244,5 +284,5 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 Try the playground without Rails:
 
 ```bash
-bundle exec exe/fixturedump show ./playground/blog
+bundle exec exe/fixturebot show ./playground/blog
 ```

lib/fixturebot.rb

@@ -16,16 +16,37 @@
 module FixtureBot
   class Error < StandardError; end
 
-  def self.define(schema, &block)
-    definition = Definition.new(schema)
-    definition.instance_eval(&block)
-    FixtureSet.new(schema, definition)
+  # Programmatic API: FixtureBot.define(schema) { ... }
+  # File API (no schema): FixtureBot.define { ... } — registers block for define_from_file
+  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
+      nil
+    end
   end
 
   def self.define_from_file(schema, fixtures_path)
+    @pending_blocks = []
     content = File.read(fixtures_path)
+    eval(content, TOPLEVEL_BINDING, fixtures_path, 1)
+
     definition = Definition.new(schema)
-    definition.instance_eval(content, fixtures_path, 1)
+    @pending_blocks.each { |blk| evaluate_block(definition, blk) }
+    @pending_blocks = nil
     FixtureSet.new(schema, definition)
   end
+
+  def self.evaluate_block(definition, block)
+    if block.arity > 0
+      block.call(definition)
+    else
+      definition.instance_eval(&block)
+    end
+  end
+  private_class_method :evaluate_block
 end

playground/blog/fixtures.rb

@@ -1,58 +1,60 @@
-user.email { "#{name}@blog.test" }
-
-user :brad do
-  name "Brad"
-  email "brad@blog.test"
-end
-
-user :alice do
-  name "Alice"
-end
-
-user :charlie do
-  name "Charlie"
-end
-
-tag :ruby do
-  name "Ruby"
-end
-
-tag :rails do
-  name "Rails"
-end
-
-tag :testing do
-  name "Testing"
-end
-
-post :hello_world do
-  title "Hello World"
-  body "Welcome to the blog!"
-  author :brad
-  tags :ruby, :rails
-end
-
-post :tdd_guide do
-  title "Getting Started with TDD"
-  body "Test-driven development is a practice where you write tests before code."
-  author :alice
-  tags :ruby, :testing
-end
-
-comment :great_post do
-  body "Great post, thanks for sharing!"
-  post :hello_world
-  author :alice
-end
-
-comment :helpful do
-  body "This was really helpful."
-  post :tdd_guide
-  author :charlie
-end
-
-comment :follow_up do
-  body "Could you write a follow-up on mocking?"
-  post :tdd_guide
-  author :brad
+FixtureBot.define do
+  user.email { "#{name}@blog.test" }
+
+  user :brad do
+    name "Brad"
+    email "brad@blog.test"
+  end
+
+  user :alice do
+    name "Alice"
+  end
+
+  user :charlie do
+    name "Charlie"
+  end
+
+  tag :ruby do
+    name "Ruby"
+  end
+
+  tag :rails do
+    name "Rails"
+  end
+
+  tag :testing do
+    name "Testing"
+  end
+
+  post :hello_world do
+    title "Hello World"
+    body "Welcome to the blog!"
+    author :brad
+    tags :ruby, :rails
+  end
+
+  post :tdd_guide do
+    title "Getting Started with TDD"
+    body "Test-driven development is a practice where you write tests before code."
+    author :alice
+    tags :ruby, :testing
+  end
+
+  comment :great_post do
+    body "Great post, thanks for sharing!"
+    post :hello_world
+    author :alice
+  end
+
+  comment :helpful do
+    body "This was really helpful."
+    post :tdd_guide
+    author :charlie
+  end
+
+  comment :follow_up do
+    body "Could you write a follow-up on mocking?"
+    post :tdd_guide
+    author :brad
+  end
 end