synthra 0.1.0

data/tech_docs/integration/rspec.md

@@ -0,0 +1,449 @@
+# RSpec Integration
+
+Using FakeDataDSL with RSpec for testing.
+
+## Table of Contents
+
+- [Setup](#setup)
+- [Basic Usage](#basic-usage)
+- [Shared Contexts](#shared-contexts)
+- [Testing Modes](#testing-modes)
+- [Factory Patterns](#factory-patterns)
+- [Best Practices](#best-practices)
+
+---
+
+## Setup
+
+### Configuration
+
+Create `spec/support/fake_data.rb`:
+
+```ruby
+require 'fake_data_dsl'
+
+RSpec.configure do |config|
+  config.before(:suite) do
+    # Load schemas once
+    $fake_data_registry = FakeDataDSL::Registry.new
+    $fake_data_registry.load_dir('spec/schemas/')
+  end
+end
+
+# Helper module
+module FakeDataHelpers
+  def fake_schema(name)
+    $fake_data_registry.schema(name.to_s.camelize)
+  end
+  
+  def fake(name, **options)
+    fake_schema(name).generate(**options)
+  end
+  
+  def fake_many(name, count, **options)
+    fake_schema(name).generate_many(count, **options)
+  end
+end
+
+RSpec.configure do |config|
+  config.include FakeDataHelpers
+end
+```
+
+### Directory Structure
+
+```
+spec/
+├── schemas/
+│   ├── user.dsl
+│   ├── order.dsl
+│   └── product.dsl
+├── support/
+│   └── fake_data.rb
+└── spec_helper.rb
+```
+
+### spec_helper.rb
+
+```ruby
+require_relative 'support/fake_data'
+```
+
+---
+
+## Basic Usage
+
+### Simple Test
+
+```ruby
+RSpec.describe User do
+  let(:user_data) { fake(:user) }
+  
+  it "creates a valid user" do
+    user = User.new(user_data)
+    expect(user).to be_valid
+  end
+end
+```
+
+### With Overrides
+
+```ruby
+RSpec.describe User do
+  let(:admin_data) { fake(:user).merge('role' => 'admin') }
+  
+  it "creates an admin" do
+    admin = User.new(admin_data)
+    expect(admin.role).to eq('admin')
+  end
+end
+```
+
+### Deterministic Tests
+
+```ruby
+RSpec.describe User do
+  let(:seed) { 12345 }
+  let(:user_data) { fake(:user, seed: seed) }
+  
+  it "generates consistent data" do
+    # Same seed = same data every time
+    expect(user_data['email']).to eq(fake(:user, seed: seed)['email'])
+  end
+end
+```
+
+---
+
+## Shared Contexts
+
+### Basic Context
+
+```ruby
+# spec/support/contexts/fake_data_context.rb
+RSpec.shared_context 'with fake data' do
+  let(:registry) { $fake_data_registry }
+  
+  def build_fake(schema_name, **overrides)
+    data = registry.schema(schema_name.to_s.camelize).generate
+    data.merge(overrides.stringify_keys)
+  end
+  
+  def create_fake(schema_name, **overrides)
+    data = build_fake(schema_name, **overrides)
+    model_class = schema_name.to_s.camelize.constantize
+    model_class.create!(data)
+  end
+end
+```
+
+### Usage
+
+```ruby
+RSpec.describe OrdersController do
+  include_context 'with fake data'
+  
+  let(:user) { create_fake(:user) }
+  let(:order) { create_fake(:order, user_id: user.id) }
+  
+  describe "GET #show" do
+    it "returns the order" do
+      get :show, params: { id: order.id }
+      expect(response).to be_successful
+    end
+  end
+end
+```
+
+### Mode-Specific Context
+
+```ruby
+RSpec.shared_context 'with edge case data' do
+  let(:user_data) { fake(:user, mode: :edge) }
+  let(:order_data) { fake(:order, mode: :edge) }
+end
+
+RSpec.shared_context 'with invalid data' do
+  let(:user_data) { fake(:user, mode: :invalid) }
+  let(:order_data) { fake(:order, mode: :invalid) }
+end
+```
+
+---
+
+## Testing Modes
+
+### Random Mode (Default)
+
+```ruby
+RSpec.describe "Happy path" do
+  let(:data) { fake(:user, mode: :random) }
+  
+  it "processes valid data" do
+    expect(process(data)).to be_success
+  end
+end
+```
+
+### Edge Mode
+
+```ruby
+RSpec.describe "Edge cases" do
+  let(:data) { fake(:user, mode: :edge) }
+  
+  it "handles edge cases" do
+    # Edge data may include empty strings, min/max values
+    expect { process(data) }.not_to raise_error
+  end
+end
+```
+
+### Invalid Mode
+
+```ruby
+RSpec.describe "Validation" do
+  let(:data) { fake(:user, mode: :invalid) }
+  
+  it "rejects invalid data" do
+    user = User.new(data)
+    expect(user).not_to be_valid
+  end
+end
+```
+
+### Comprehensive Testing
+
+```ruby
+RSpec.describe User do
+  describe "handles all input types" do
+    %i[random edge invalid mixed].each do |mode|
+      context "with #{mode} data" do
+        let(:data) { fake(:user, mode: mode) }
+        
+        it "doesn't crash" do
+          expect { User.new(data).validate }.not_to raise_error
+        end
+      end
+    end
+  end
+end
+```
+
+---
+
+## Factory Patterns
+
+### Factory-Like Interface
+
+```ruby
+# spec/support/fake_factories.rb
+module FakeFactories
+  extend self
+  
+  def registry
+    @registry ||= FakeDataDSL::Registry.new.tap do |r|
+      r.load_dir('spec/schemas/')
+    end
+  end
+  
+  def build(name, **attrs)
+    data = registry.schema(name.to_s.camelize).generate
+    data.merge(attrs.stringify_keys)
+  end
+  
+  def create(name, **attrs)
+    data = build(name, **attrs)
+    name.to_s.camelize.constantize.create!(data)
+  end
+  
+  def build_list(name, count, **attrs)
+    count.times.map { build(name, **attrs) }
+  end
+  
+  def create_list(name, count, **attrs)
+    count.times.map { create(name, **attrs) }
+  end
+end
+
+# Global methods
+def build(name, **attrs)
+  FakeFactories.build(name, **attrs)
+end
+
+def create(name, **attrs)
+  FakeFactories.create(name, **attrs)
+end
+
+def build_list(name, count, **attrs)
+  FakeFactories.build_list(name, count, **attrs)
+end
+
+def create_list(name, count, **attrs)
+  FakeFactories.create_list(name, count, **attrs)
+end
+```
+
+### Usage
+
+```ruby
+RSpec.describe "with factory pattern" do
+  let(:user) { create(:user) }
+  let(:admin) { create(:user, role: 'admin') }
+  let(:users) { create_list(:user, 10) }
+  
+  it "creates related records" do
+    order = create(:order, user_id: user.id)
+    expect(order.user).to eq(user)
+  end
+end
+```
+
+### Traits Pattern
+
+```ruby
+module FakeFactories
+  TRAITS = {
+    user: {
+      admin: { role: 'admin' },
+      verified: { verified: true, verified_at: Time.current },
+      inactive: { status: 'inactive' }
+    },
+    order: {
+      completed: { status: 'completed', completed_at: Time.current },
+      cancelled: { status: 'cancelled', cancelled_at: Time.current }
+    }
+  }
+  
+  def build(name, *traits, **attrs)
+    data = registry.schema(name.to_s.camelize).generate
+    
+    # Apply traits
+    traits.each do |trait|
+      trait_attrs = TRAITS.dig(name, trait) || {}
+      data.merge!(trait_attrs.stringify_keys)
+    end
+    
+    data.merge(attrs.stringify_keys)
+  end
+end
+
+# Usage
+user = build(:user, :admin, :verified)
+order = build(:order, :completed)
+```
+
+---
+
+## Best Practices
+
+### 1. Use Deterministic Seeds for Debugging
+
+```ruby
+RSpec.describe "Flaky test debugging" do
+  # Run with specific seed to reproduce
+  let(:seed) { ENV['FAKE_SEED']&.to_i || rand(1..10000) }
+  let(:data) { fake(:user, seed: seed) }
+  
+  before do
+    puts "Using seed: #{seed}" if ENV['DEBUG']
+  end
+  
+  it "processes data" do
+    # If fails, rerun with FAKE_SEED=<seed> to reproduce
+    expect(process(data)).to be_success
+  end
+end
+```
+
+### 2. Test All Modes Systematically
+
+```ruby
+RSpec.describe UserService do
+  shared_examples "handles input" do |mode|
+    let(:input) { fake(:user, mode: mode) }
+    
+    it "doesn't crash with #{mode} data" do
+      expect { subject.process(input) }.not_to raise_error
+    end
+  end
+  
+  include_examples "handles input", :random
+  include_examples "handles input", :edge
+  include_examples "handles input", :invalid
+end
+```
+
+### 3. Isolate Schema Loading
+
+```ruby
+# Load once, use many times
+RSpec.configure do |config|
+  config.before(:suite) do
+    $fake_data_registry = FakeDataDSL::Registry.new
+    $fake_data_registry.load_dir('spec/schemas/')
+  end
+end
+```
+
+### 4. Use Overrides Sparingly
+
+```ruby
+# Good - minimal override for specific test
+let(:admin) { fake(:user).merge('role' => 'admin') }
+
+# Avoid - too many overrides, defeats purpose
+let(:user) do
+  fake(:user).merge(
+    'name' => 'Test User',
+    'email' => 'test@example.com',
+    'age' => 30,
+    # ...
+  )
+end
+```
+
+### 5. Clean Up Generated Data
+
+```ruby
+RSpec.configure do |config|
+  config.after(:each) do
+    # If using database
+    DatabaseCleaner.clean
+  end
+end
+```
+
+---
+
+## Request Specs
+
+```ruby
+RSpec.describe "Users API", type: :request do
+  describe "POST /api/users" do
+    let(:user_params) { fake(:user).slice('name', 'email') }
+    
+    it "creates user" do
+      post '/api/users', params: { user: user_params }
+      expect(response).to have_http_status(:created)
+    end
+    
+    context "with invalid data" do
+      let(:user_params) { fake(:user, mode: :invalid).slice('name', 'email') }
+      
+      it "returns errors" do
+        post '/api/users', params: { user: user_params }
+        expect(response).to have_http_status(:unprocessable_entity)
+      end
+    end
+  end
+end
+```
+
+---
+
+## Next Steps
+
+- [Rails Integration](rails.md) - Rails-specific patterns
+- [Examples](../../tech_example/07_rspec_integration.rb) - More examples
+- [Generation Modes](../modes/overview.md) - Mode details
+