synthra 0.1.0

data/docs/SCENARIOS.md

@@ -0,0 +1,576 @@
+# Scenario-Based Test Data Fixtures
+
+FakeDataDSL Scenarios let you define **complex, interconnected test data** with named references, lazy evaluation, and inheritance. Think of it as "Fixtures 2.0" that combines the best of Rails fixtures and Factory Bot.
+
+## Quick Start
+
+```ruby
+# Define a scenario
+FakeDataDSL::Scenarios.define(:e_commerce_checkout) do
+  # Define entities with 'let'
+  let(:buyer) { User.generate(role: "customer", verified: true) }
+  let(:seller) { User.generate(role: "merchant") }
+  let(:product) { Product.generate(seller: seller, price: 99.99) }
+  let(:cart) { ShoppingCart.generate(user: buyer, items: [product]) }
+  let(:order) { Order.generate(user: buyer, cart: cart, status: "pending") }
+end
+
+# Use in tests
+RSpec.describe "Checkout" do
+  include_scenario :e_commerce_checkout
+  
+  it "completes the order" do
+    expect(order.status).to eq("pending")
+    order.complete!
+    expect(order.status).to eq("completed")
+  end
+end
+```
+
+## Defining Scenarios
+
+### Basic Scenario
+
+```ruby
+FakeDataDSL::Scenarios.define(:basic_user) do
+  let(:user) { User.generate }
+  let(:profile) { Profile.generate(user: user) }
+end
+```
+
+### With Schema References
+
+```ruby
+FakeDataDSL::Scenarios.define(:blog_post) do
+  # Reference other scenarios
+  include_scenario :basic_user
+  
+  let(:category) { Category.generate(name: "Technology") }
+  let(:post) { 
+    Post.generate(
+      author: user,    # From included scenario
+      category: category,
+      published: true
+    )
+  }
+  let(:comments) {
+    3.times.map { Comment.generate(post: post, author: User.generate) }
+  }
+end
+```
+
+### DSL File Syntax
+
+You can also define scenarios in `.dsl` files:
+
+```ruby
+# db/schemas/scenarios/e_commerce.dsl
+@scenario "e_commerce_checkout"
+  Users:
+    buyer: User(role: "customer", verified: true)
+    seller: User(role: "merchant")
+  
+  Products:
+    laptop: Product(seller: @seller, price: 999.99, stock: 10)
+    phone: Product(seller: @seller, price: 499.99, stock: 5)
+  
+  Cart:
+    cart: ShoppingCart(user: @buyer)
+      items:
+        - CartItem(product: @laptop, quantity: 1)
+        - CartItem(product: @phone, quantity: 2)
+  
+  Order:
+    pending_order: Order(user: @buyer, status: "pending")
+      from_cart: @cart
+```
+
+## Using Scenarios
+
+### RSpec Integration
+
+```ruby
+# spec/rails_helper.rb
+require 'fake_data_dsl/scenarios'
+
+RSpec.configure do |config|
+  config.include FakeDataDSL::Scenarios::RSpecHelpers
+end
+```
+
+```ruby
+# spec/features/checkout_spec.rb
+RSpec.describe "Checkout", type: :feature do
+  include_scenario :e_commerce_checkout
+  
+  it "shows cart total" do
+    visit cart_path(cart)
+    expect(page).to have_content("$1,499.97")  # laptop + 2 phones
+  end
+  
+  it "processes payment" do
+    login_as buyer
+    visit checkout_path(order)
+    click_button "Pay Now"
+    expect(order.reload.status).to eq("paid")
+  end
+end
+```
+
+### Minitest Integration
+
+```ruby
+# test/test_helper.rb
+require 'fake_data_dsl/scenarios'
+
+class ActiveSupport::TestCase
+  include FakeDataDSL::Scenarios::MinitestHelpers
+end
+```
+
+```ruby
+# test/integration/checkout_test.rb
+class CheckoutTest < ActionDispatch::IntegrationTest
+  include_scenario :e_commerce_checkout
+  
+  test "completes checkout" do
+    post checkout_path(order), params: { payment_method: "credit_card" }
+    assert_equal "completed", order.reload.status
+  end
+end
+```
+
+## Lazy Evaluation
+
+Scenario entities are lazily evaluated - they're only created when accessed:
+
+```ruby
+FakeDataDSL::Scenarios.define(:expensive_setup) do
+  let(:user) { User.generate }  # Not created yet
+  let(:large_dataset) {
+    1000.times.map { Record.generate(user: user) }
+  }  # Not created yet
+end
+
+RSpec.describe "Performance" do
+  include_scenario :expensive_setup
+  
+  it "accesses user" do
+    expect(user).to be_present  # NOW user is created
+    # large_dataset is never created in this test
+  end
+  
+  it "accesses dataset" do
+    expect(large_dataset.count).to eq(1000)  # NOW both are created
+  end
+end
+```
+
+## Entity References
+
+### Forward References
+
+```ruby
+FakeDataDSL::Scenarios.define(:circular) do
+  let(:team) { Team.generate(lead: lead) }  # References 'lead' defined below
+  let(:lead) { User.generate(team: team) }  # References 'team' defined above
+end
+```
+
+### Cross-Scenario References
+
+```ruby
+FakeDataDSL::Scenarios.define(:users) do
+  let(:admin) { User.generate(role: "admin") }
+  let(:regular) { User.generate(role: "user") }
+end
+
+FakeDataDSL::Scenarios.define(:permissions) do
+  include_scenario :users
+  
+  let(:admin_permissions) { Permission.generate(user: admin, level: "full") }
+  let(:user_permissions) { Permission.generate(user: regular, level: "read") }
+end
+```
+
+## Scenario Inheritance
+
+### Extending Scenarios
+
+```ruby
+FakeDataDSL::Scenarios.define(:base_user) do
+  let(:user) { User.generate }
+  let(:profile) { Profile.generate(user: user) }
+end
+
+FakeDataDSL::Scenarios.define(:admin_user, extends: :base_user) do
+  # Override user definition
+  let(:user) { User.generate(role: "admin", permissions: ["all"]) }
+  
+  # Add new entities
+  let(:audit_log) { AuditLog.generate(admin: user) }
+end
+```
+
+### Multiple Inheritance
+
+```ruby
+FakeDataDSL::Scenarios.define(:full_checkout, 
+  extends: [:e_commerce_checkout, :payment_setup, :shipping_setup]
+) do
+  let(:complete_order) {
+    Order.generate(
+      user: buyer,
+      cart: cart,
+      payment: payment_method,
+      shipping: shipping_address,
+      status: "complete"
+    )
+  }
+end
+```
+
+## Context and State
+
+### Shared Context
+
+```ruby
+FakeDataDSL::Scenarios.define(:multi_tenant) do
+  let(:tenant) { Tenant.generate }
+  
+  # All entities share the tenant context
+  with_context(tenant_id: -> { tenant.id }) do
+    let(:user) { User.generate }  # Automatically gets tenant_id
+    let(:product) { Product.generate }  # Automatically gets tenant_id
+    let(:order) { Order.generate(user: user) }  # Automatically gets tenant_id
+  end
+end
+```
+
+### Conditional Entities
+
+```ruby
+FakeDataDSL::Scenarios.define(:feature_flags) do
+  let(:user) { User.generate }
+  
+  let(:premium_feature) {
+    if user.subscription == "premium"
+      PremiumFeature.generate(user: user)
+    end
+  }
+  
+  let(:beta_feature) {
+    BetaFeature.generate(user: user) if ENV["ENABLE_BETA"]
+  }
+end
+```
+
+## Parameterized Scenarios
+
+### With Arguments
+
+```ruby
+FakeDataDSL::Scenarios.define(:order_with_items) do |count: 3, status: "pending"|
+  let(:user) { User.generate }
+  let(:items) { count.times.map { OrderItem.generate } }
+  let(:order) { Order.generate(user: user, items: items, status: status) }
+end
+
+# Usage
+RSpec.describe "Orders" do
+  include_scenario :order_with_items, count: 5, status: "shipped"
+  
+  it "has correct items" do
+    expect(order.items.count).to eq(5)
+    expect(order.status).to eq("shipped")
+  end
+end
+```
+
+### Dynamic Scenarios
+
+```ruby
+FakeDataDSL::Scenarios.define(:scaled_data) do |scale: 1|
+  let(:users) { (10 * scale).times.map { User.generate } }
+  let(:products) { (100 * scale).times.map { Product.generate } }
+  let(:orders) { (50 * scale).times.map { Order.generate } }
+end
+
+# Small dataset for unit tests
+include_scenario :scaled_data, scale: 1
+
+# Large dataset for load tests
+include_scenario :scaled_data, scale: 100
+```
+
+## Scenario Variants
+
+### Named Variants
+
+```ruby
+FakeDataDSL::Scenarios.define(:user_states) do
+  variant(:active) do
+    let(:user) { User.generate(active: true, verified: true) }
+  end
+  
+  variant(:pending) do
+    let(:user) { User.generate(active: false, verified: false) }
+  end
+  
+  variant(:suspended) do
+    let(:user) { User.generate(active: false, suspended_at: Time.current) }
+  end
+end
+
+# Usage
+include_scenario :user_states, variant: :suspended
+```
+
+### Mode-Based Variants
+
+```ruby
+FakeDataDSL::Scenarios.define(:edge_cases) do
+  variant(:happy_path, mode: :random) do
+    let(:user) { User.generate }
+  end
+  
+  variant(:edge_cases, mode: :edge) do
+    let(:user) { User.generate }  # Will use edge case values
+  end
+  
+  variant(:hostile, mode: :hostile) do
+    let(:user) { User.generate }  # Will use hostile values
+  end
+end
+```
+
+## Hooks
+
+### Setup and Teardown
+
+```ruby
+FakeDataDSL::Scenarios.define(:with_hooks) do
+  before do
+    Rails.cache.clear
+    Sidekiq::Testing.inline!
+  end
+  
+  after do
+    Sidekiq::Testing.fake!
+  end
+  
+  let(:user) { User.generate }
+end
+```
+
+### Entity Callbacks
+
+```ruby
+FakeDataDSL::Scenarios.define(:with_callbacks) do
+  let(:user) {
+    User.generate.tap do |u|
+      u.confirm!  # Run after creation
+      u.update!(last_login: Time.current)
+    end
+  }
+end
+```
+
+## Database Integration
+
+### Creating Records
+
+```ruby
+FakeDataDSL::Scenarios.define(:persisted) do
+  # create() persists to database
+  let(:user) { create(:user) }
+  let(:order) { create(:order, user: user) }
+end
+
+FakeDataDSL::Scenarios.define(:in_memory) do
+  # build() stays in memory
+  let(:user) { build(:user) }
+  let(:order) { build(:order, user: user) }
+end
+```
+
+### Transactional Scenarios
+
+```ruby
+FakeDataDSL::Scenarios.define(:transactional) do
+  transactional!  # Wrap in transaction, rollback after test
+  
+  let(:user) { create(:user) }
+  let(:order) { create(:order) }
+end
+```
+
+## Debugging Scenarios
+
+### Inspect Scenario
+
+```ruby
+scenario = FakeDataDSL::Scenarios.find(:e_commerce_checkout)
+scenario.entities  # => [:buyer, :seller, :product, :cart, :order]
+scenario.dependencies  # => { order: [:buyer, :cart], cart: [:buyer, :product], ... }
+```
+
+### Visualization
+
+```ruby
+# Generate dependency graph
+FakeDataDSL::Scenarios.find(:e_commerce_checkout).to_dot
+# => "digraph { buyer -> cart; cart -> order; ... }"
+```
+
+### Logging
+
+```ruby
+FakeDataDSL::Scenarios.configure do |config|
+  config.logger = Rails.logger
+  config.log_level = :debug
+end
+
+# Now see:
+# [FakeDataDSL::Scenarios] Creating :user
+# [FakeDataDSL::Scenarios] Creating :order (depends on :user, :cart)
+```
+
+## API Reference
+
+### Scenarios.define
+
+```ruby
+FakeDataDSL::Scenarios.define(name, options = {}, &block)
+```
+
+**Parameters:**
+- `name` - Symbol name for the scenario
+- `options[:extends]` - Parent scenario(s) to inherit from
+- `block` - Scenario definition block
+
+### Scenario#let
+
+```ruby
+let(name, &block)
+```
+
+Defines a lazy-evaluated entity.
+
+### Scenario#create
+
+```ruby
+create(schema_name, overrides = {})
+```
+
+Creates and persists a record using the schema.
+
+### Scenario#build
+
+```ruby
+build(schema_name, overrides = {})
+```
+
+Builds a record in memory (not persisted).
+
+### include_scenario
+
+```ruby
+include_scenario(name, **options)
+```
+
+Includes a scenario in a test, making all entities available.
+
+## Best Practices
+
+### 1. Keep Scenarios Focused
+
+```ruby
+# Good: Single purpose
+FakeDataDSL::Scenarios.define(:checkout_ready) do
+  let(:buyer) { create(:user, :verified) }
+  let(:cart) { create(:cart, user: buyer, items: [product]) }
+end
+
+# Bad: Too much unrelated data
+FakeDataDSL::Scenarios.define(:everything) do
+  let(:user) { ... }
+  let(:admin) { ... }
+  let(:product) { ... }
+  let(:report) { ... }
+  # ...50 more entities
+end
+```
+
+### 2. Use Inheritance for Variations
+
+```ruby
+FakeDataDSL::Scenarios.define(:base_order) do
+  let(:user) { create(:user) }
+  let(:order) { create(:order, user: user) }
+end
+
+FakeDataDSL::Scenarios.define(:pending_order, extends: :base_order) do
+  let(:order) { create(:order, user: user, status: "pending") }
+end
+
+FakeDataDSL::Scenarios.define(:shipped_order, extends: :base_order) do
+  let(:order) { create(:order, user: user, status: "shipped") }
+end
+```
+
+### 3. Document Dependencies
+
+```ruby
+FakeDataDSL::Scenarios.define(:complex_workflow) do
+  # This scenario sets up a complete order fulfillment workflow
+  # Dependencies:
+  #   - buyer: Customer placing the order
+  #   - seller: Merchant fulfilling the order
+  #   - product: Item being purchased
+  #   - order: The order connecting buyer and seller
+  #   - shipment: Delivery tracking
+  
+  let(:buyer) { ... }
+  let(:seller) { ... }
+  # ...
+end
+```
+
+## Troubleshooting
+
+### Circular Dependencies
+
+```ruby
+# Error: Circular dependency detected: user -> team -> user
+
+# Fix: Break the cycle with nil defaults
+FakeDataDSL::Scenarios.define(:team_setup) do
+  let(:team) { create(:team, lead: nil) }
+  let(:user) { create(:user, team: team) }
+  
+  after do
+    team.update!(lead: user)
+  end
+end
+```
+
+### Entity Not Found
+
+```ruby
+# Error: Unknown entity: :admin
+
+# Fix: Check includes
+FakeDataDSL::Scenarios.define(:needs_admin) do
+  include_scenario :users  # Make sure this defines :admin
+  
+  let(:action) { AdminAction.create(admin: admin) }
+end
+```
+
+## See Also
+
+- [Factory Bot Integration](FACTORY_BOT.md)
+- [Personas](PERSONAS.md)
+- [Time Travel](TIME_TRAVEL.md)
+- [Property Testing](PROPERTY_TESTING.md)