synthra 0.1.0

data/tech_docs/integration/factory_bot.md

@@ -0,0 +1,485 @@
+# Factory Bot Comparison
+
+Comparing FakeDataDSL with Factory Bot and migration guide.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Feature Comparison](#feature-comparison)
+- [Syntax Comparison](#syntax-comparison)
+- [When to Use Each](#when-to-use-each)
+- [Migration Guide](#migration-guide)
+- [Using Together](#using-together)
+
+---
+
+## Overview
+
+**Factory Bot** and **FakeDataDSL** serve different purposes:
+
+| Tool | Primary Purpose |
+|------|-----------------|
+| **Factory Bot** | Create model instances for testing |
+| **FakeDataDSL** | Generate fake data from schemas |
+
+They can complement each other rather than compete.
+
+---
+
+## Feature Comparison
+
+| Feature | Factory Bot | FakeDataDSL |
+|---------|-------------|-------------|
+| **Model Integration** | ✅ Deep Rails integration | ⚠️ Data only, not models |
+| **Associations** | ✅ Automatic | ⚠️ Manual with Ref() |
+| **Traits** | ✅ Built-in | ⚠️ Via overrides |
+| **Sequences** | ✅ Built-in | ✅ id_sequence |
+| **Callbacks** | ✅ after_create, etc. | ❌ Not available |
+| **Lazy Evaluation** | ✅ Built-in | ❌ Not available |
+| **DSL File** | ❌ Ruby code | ✅ Separate DSL |
+| **Generation Modes** | ❌ Not available | ✅ random/edge/invalid |
+| **Behaviors** | ❌ Not available | ✅ latency/failure/etc. |
+| **Streaming** | ❌ Not available | ✅ Memory-efficient |
+| **Deterministic** | ⚠️ With Faker.seed | ✅ Built-in seeds |
+| **CLI** | ❌ Not available | ✅ Command line |
+| **Non-Rails** | ⚠️ Possible | ✅ Framework agnostic |
+
+---
+
+## Syntax Comparison
+
+### Defining Data Shape
+
+**Factory Bot:**
+```ruby
+# spec/factories/users.rb
+FactoryBot.define do
+  factory :user do
+    id { SecureRandom.uuid }
+    name { Faker::Name.name }
+    email { Faker::Internet.email }
+    age { rand(18..65) }
+    active { [true, false].sample }
+    role { %w[user admin moderator].sample }
+    created_at { rand(1..365).days.ago }
+  end
+end
+```
+
+**FakeDataDSL:**
+```dsl
+# schemas/user.dsl
+User:
+  id: uuid
+  name: name
+  email: email
+  age: number(18..65)
+  active: boolean
+  role: enum(user, admin, moderator)
+  created_at: past_date(1y)
+```
+
+### Creating Records
+
+**Factory Bot:**
+```ruby
+# Build (doesn't save)
+user = build(:user)
+
+# Create (saves to DB)
+user = create(:user)
+
+# With overrides
+admin = create(:user, role: 'admin')
+
+# Multiple
+users = create_list(:user, 10)
+```
+
+**FakeDataDSL:**
+```ruby
+# Generate data hash
+user_data = schema.generate
+
+# Create model manually
+user = User.create!(user_data)
+
+# With overrides
+admin = User.create!(schema.generate.merge('role' => 'admin'))
+
+# Multiple
+users_data = schema.generate_many(10)
+users = User.insert_all!(users_data)
+```
+
+### Traits
+
+**Factory Bot:**
+```ruby
+factory :user do
+  name { Faker::Name.name }
+  role { 'user' }
+  
+  trait :admin do
+    role { 'admin' }
+  end
+  
+  trait :inactive do
+    active { false }
+    deactivated_at { Time.current }
+  end
+end
+
+# Usage
+admin = create(:user, :admin)
+inactive_admin = create(:user, :admin, :inactive)
+```
+
+**FakeDataDSL:**
+```ruby
+# Using helper methods
+def fake_user(*traits, **overrides)
+  data = schema.generate
+  
+  traits.each do |trait|
+    case trait
+    when :admin
+      data['role'] = 'admin'
+    when :inactive
+      data['active'] = false
+      data['deactivated_at'] = Time.current.iso8601
+    end
+  end
+  
+  data.merge(overrides.stringify_keys)
+end
+
+# Usage
+admin = User.create!(fake_user(:admin))
+inactive_admin = User.create!(fake_user(:admin, :inactive))
+```
+
+### Associations
+
+**Factory Bot:**
+```ruby
+factory :post do
+  title { Faker::Lorem.sentence }
+  user  # Automatically creates associated user
+end
+
+factory :comment do
+  body { Faker::Lorem.paragraph }
+  post
+  user
+end
+
+# Usage
+post = create(:post)  # Creates user automatically
+post.user  # => User instance
+```
+
+**FakeDataDSL:**
+```ruby
+# Manual association
+user = User.create!(fake(:user))
+post_data = fake(:post).merge('user_id' => user.id)
+post = Post.create!(post_data)
+
+# Or use Ref() in DSL (references previously generated)
+# post.dsl
+# Post:
+#   user_id: Ref(User.id)
+```
+
+### Sequences
+
+**Factory Bot:**
+```ruby
+factory :user do
+  sequence(:email) { |n| "user#{n}@example.com" }
+  sequence(:username) { |n| "user_#{n}" }
+end
+```
+
+**FakeDataDSL:**
+```dsl
+User:
+  id: id_sequence
+  email: email(unique: true)
+  username: username
+```
+
+---
+
+## When to Use Each
+
+### Use Factory Bot When:
+
+1. **Deep Rails integration needed**
+   - Automatic association handling
+   - Callbacks (after_create, etc.)
+   - ActiveRecord features
+
+2. **Complex test setup**
+   - Nested associations
+   - Transactional rollback
+   - Database state management
+
+3. **Traits are essential**
+   - Many variations of same model
+   - Composable configurations
+
+### Use FakeDataDSL When:
+
+1. **Schema-first approach**
+   - Define data contracts
+   - Share schemas across teams
+   - Generate docs from schemas
+
+2. **Testing modes needed**
+   - Edge case testing
+   - Invalid data testing
+   - Validation testing
+
+3. **Non-Rails contexts**
+   - API testing
+   - Data migration
+   - Load testing
+
+4. **Large data volumes**
+   - Streaming generation
+   - Memory efficiency
+   - Database seeding
+
+5. **Behavior simulation**
+   - Latency testing
+   - Failure testing
+   - Chaos engineering
+
+---
+
+## Migration Guide
+
+### From Factory Bot to FakeDataDSL
+
+#### Step 1: Convert Factories to Schemas
+
+**Before (Factory Bot):**
+```ruby
+# spec/factories/users.rb
+FactoryBot.define do
+  factory :user do
+    id { SecureRandom.uuid }
+    name { Faker::Name.name }
+    email { Faker::Internet.email }
+    age { rand(18..65) }
+    role { 'user' }
+    
+    trait :admin do
+      role { 'admin' }
+    end
+    
+    trait :verified do
+      verified { true }
+      verified_at { Time.current }
+    end
+  end
+end
+```
+
+**After (FakeDataDSL):**
+```dsl
+# spec/schemas/user.dsl
+User:
+  id: uuid
+  name: name
+  email: email
+  age: number(18..65)
+  role: enum(user:80%, admin:10%, moderator:10%)
+  verified: boolean(false:80%)
+  verified_at?: past_date(1y)
+```
+
+#### Step 2: Create Helper Module
+
+```ruby
+# spec/support/fake_data.rb
+module FakeDataHelpers
+  TRAITS = {
+    user: {
+      admin: { 'role' => 'admin' },
+      verified: { 'verified' => true, 'verified_at' => Time.current.iso8601 }
+    }
+  }
+  
+  def fake(name, *traits, **overrides)
+    data = fake_schema(name).generate
+    
+    traits.each do |trait|
+      trait_data = TRAITS.dig(name, trait) || {}
+      data.merge!(trait_data)
+    end
+    
+    data.merge(overrides.stringify_keys)
+  end
+  
+  def create_fake(name, *traits, **overrides)
+    model_class = name.to_s.camelize.constantize
+    model_class.create!(fake(name, *traits, **overrides))
+  end
+  
+  def create_fake_list(name, count, *traits, **overrides)
+    count.times.map { create_fake(name, *traits, **overrides) }
+  end
+  
+  private
+  
+  def fake_schema(name)
+    @registry ||= FakeDataDSL::Registry.new.tap do |r|
+      r.load_dir('spec/schemas')
+    end
+    @registry.schema(name.to_s.camelize)
+  end
+end
+```
+
+#### Step 3: Update Specs
+
+**Before:**
+```ruby
+RSpec.describe User do
+  let(:user) { create(:user) }
+  let(:admin) { create(:user, :admin) }
+end
+```
+
+**After:**
+```ruby
+RSpec.describe User do
+  include FakeDataHelpers
+  
+  let(:user) { create_fake(:user) }
+  let(:admin) { create_fake(:user, :admin) }
+end
+```
+
+### Gradual Migration
+
+You can use both during migration:
+
+```ruby
+# spec/support/factories_and_fake.rb
+
+# Keep Factory Bot for complex cases
+FactoryBot.define do
+  factory :order_with_items do
+    # Complex associations
+  end
+end
+
+# Use FakeDataDSL for simple cases
+module FakeDataHelpers
+  def fake_user(**overrides)
+    schema.generate.merge(overrides.stringify_keys)
+  end
+end
+
+# In specs
+RSpec.describe OrdersController do
+  # Use Factory Bot for complex setup
+  let(:order) { create(:order_with_items) }
+  
+  # Use FakeDataDSL for simple data
+  let(:user_params) { fake_user }
+end
+```
+
+---
+
+## Using Together
+
+### Best of Both Worlds
+
+```ruby
+# spec/factories/users.rb
+FactoryBot.define do
+  factory :user do
+    # Use FakeDataDSL for data generation
+    transient do
+      fake_data { FakeDataHelpers.fake(:user) }
+    end
+    
+    id { fake_data['id'] }
+    name { fake_data['name'] }
+    email { fake_data['email'] }
+    
+    # Keep Factory Bot traits
+    trait :admin do
+      role { 'admin' }
+    end
+    
+    # Keep callbacks
+    after(:create) do |user|
+      user.send_welcome_email
+    end
+  end
+end
+```
+
+### Hybrid Approach
+
+```ruby
+# spec/support/hybrid_factories.rb
+
+module HybridFactories
+  # Use FakeDataDSL for data
+  def fake(name, **options)
+    registry.schema(name.to_s.camelize).generate(**options)
+  end
+  
+  # Use Factory Bot for model creation with associations
+  def create_with_fake(name, *traits, **overrides)
+    data = fake(name)
+    FactoryBot.create(name, *traits, data.merge(overrides))
+  end
+end
+```
+
+### Decision Matrix
+
+| Scenario | Recommendation |
+|----------|---------------|
+| Simple model, no associations | FakeDataDSL |
+| Complex associations | Factory Bot |
+| Edge case testing | FakeDataDSL |
+| After callbacks needed | Factory Bot |
+| Large batch generation | FakeDataDSL |
+| Transactional tests | Factory Bot |
+| API data contracts | FakeDataDSL |
+| Integration tests | Either/Both |
+
+---
+
+## Summary
+
+| Aspect | Factory Bot | FakeDataDSL |
+|--------|-------------|-------------|
+| Best for | Model creation | Data generation |
+| Syntax | Ruby DSL | Custom DSL |
+| Learning curve | Medium | Low |
+| Rails integration | Excellent | Good |
+| Testing modes | No | Yes |
+| Streaming | No | Yes |
+| Behaviors | No | Yes |
+
+**Recommendation:** Use both! Factory Bot for complex Rails model creation, FakeDataDSL for data generation, testing modes, and behavior simulation.
+
+---
+
+## Next Steps
+
+- [RSpec Integration](rspec.md) - RSpec testing patterns
+- [Rails Integration](rails.md) - Rails-specific setup
+- [CI/CD Integration](ci_cd.md) - Continuous integration
+