synthra 0.1.0

data/tech_docs/behaviors/overview.md

@@ -0,0 +1,346 @@
+# Behaviors Overview
+
+Simulate real-world conditions for testing with behaviors.
+
+## Table of Contents
+
+- [What are Behaviors?](#what-are-behaviors)
+- [Why Use Behaviors?](#why-use-behaviors)
+- [Available Behaviors](#available-behaviors)
+- [Schema-Level vs Field-Level](#schema-level-vs-field-level)
+- [Combining Behaviors](#combining-behaviors)
+- [Error Handling](#error-handling)
+
+---
+
+## What are Behaviors?
+
+Behaviors are modifiers that simulate real-world conditions:
+
+- Network latency
+- Service failures
+- Incomplete responses
+- Connection drops
+- HTTP errors
+
+They help you test how your application handles imperfect conditions.
+
+---
+
+## Why Use Behaviors?
+
+### Testing Scenarios
+
+| Scenario | Behavior |
+|----------|----------|
+| Slow API responses | `@latency` |
+| Service outages | `@failure` |
+| Incomplete data | `@partial_data` |
+| Network issues | `@close_connection` |
+| HTTP error codes | `@simulate_error` |
+
+### Benefits
+
+1. **Resilience Testing**: Find bugs before production
+2. **Timeout Handling**: Verify timeout logic works
+3. **Error Recovery**: Test error handling paths
+4. **UI/UX Testing**: See loading states and error messages
+
+---
+
+## Available Behaviors
+
+### @latency
+
+Adds artificial delay to generation.
+
+```dsl
+SlowAPI:
+  @latency 100ms          # Fixed 100ms delay
+  @latency 100..500ms     # Random 100-500ms delay
+  
+  data: object
+```
+
+**Arguments:**
+- Fixed: `Nms` (e.g., `100ms`)
+- Range: `N..Mms` (e.g., `100..500ms`)
+
+### @failure
+
+Throws an error with specified probability.
+
+```dsl
+FlakyService:
+  @failure 5%             # 5% chance of failure
+  
+  data: object
+```
+
+**Throws:** `FakeDataDSL::Errors::SimulatedFailure`
+
+### @partial_data
+
+Randomly omits fields from output.
+
+```dsl
+IncompleteResponse:
+  @partial_data 20%       # 20% chance each field is missing
+  
+  id: uuid
+  name: name
+  email: email
+```
+
+### @close_connection
+
+Simulates connection drop.
+
+```dsl
+UnstableConnection:
+  @close_connection 2%    # 2% chance of connection drop
+  
+  data: object
+```
+
+**Throws:** `FakeDataDSL::Errors::SimulatedConnectionDrop`
+
+### @simulate_error
+
+Returns HTTP error status codes.
+
+```dsl
+ErrorProne:
+  @simulate_error 500 5%  # 5% chance of 500 error
+  @simulate_error 503 2%  # 2% chance of 503 error
+  
+  data: object
+```
+
+**Throws:** `FakeDataDSL::Errors::SimulatedError` with status code
+
+### @randomize_order
+
+Shuffles array fields randomly.
+
+```dsl
+SearchResults:
+  @randomize_order
+  
+  results: array(Result, 1..20)
+```
+
+---
+
+## Schema-Level vs Field-Level
+
+### Schema-Level Behaviors
+
+Apply to the entire schema generation:
+
+```dsl
+APIResponse:
+  @latency 100..500ms     # Delay entire response
+  @failure 5%             # May fail entirely
+  
+  id: uuid
+  data: object
+  meta: object
+```
+
+### Field-Level Behaviors
+
+Apply to specific fields only:
+
+```dsl
+User:
+  id: uuid
+  name: name
+  
+  # This specific field may be missing
+  avatar: url @partial_data 30%
+  
+  # This field has extra latency
+  external_data: object @latency 200ms
+```
+
+### Combining Both
+
+```dsl
+UserAPI:
+  @latency 50..100ms      # Base latency for all
+  @failure 2%             # 2% total failure rate
+  
+  id: uuid
+  name: name
+  
+  # Additional field-specific behaviors
+  avatar: url @partial_data 40%
+  profile: object @latency 100..300ms
+```
+
+---
+
+## Combining Behaviors
+
+### Multiple Schema Behaviors
+
+```dsl
+RealWorldAPI:
+  @latency 100..1000ms    # Network latency
+  @failure 3%             # Random failures
+  @simulate_error 500 1%  # Server errors
+  @simulate_error 503 1%  # Service unavailable
+  @partial_data 10%       # Missing fields
+  
+  data: object
+```
+
+### Behavior Order
+
+Behaviors are applied in order:
+1. `@latency` - Delay happens first
+2. `@failure` - May throw before generating
+3. `@partial_data` - Applied after generation
+4. `@randomize_order` - Applied last
+
+---
+
+## Error Handling
+
+### Handling Behavior Errors
+
+```ruby
+schema = FakeDataDSL.load('flaky_api.dsl')
+
+begin
+  data = schema.generate
+  process(data)
+  
+rescue FakeDataDSL::Errors::SimulatedFailure
+  # Handle @failure behavior
+  puts "Service temporarily unavailable"
+  
+rescue FakeDataDSL::Errors::SimulatedConnectionDrop
+  # Handle @close_connection behavior
+  puts "Connection lost"
+  
+rescue FakeDataDSL::Errors::SimulatedError => e
+  # Handle @simulate_error behavior
+  puts "HTTP #{e.status_code}: #{e.message}"
+  
+rescue FakeDataDSL::Errors::LatencyLimitError => e
+  # Handle latency exceeding limits
+  puts "Request timed out"
+end
+```
+
+### Error Types
+
+| Behavior | Error Class |
+|----------|-------------|
+| `@failure` | `SimulatedFailure` |
+| `@close_connection` | `SimulatedConnectionDrop` |
+| `@simulate_error` | `SimulatedError` |
+| `@latency` (over limit) | `LatencyLimitError` |
+
+### Testing with Errors
+
+```ruby
+RSpec.describe "API Client" do
+  let(:schema) { FakeDataDSL.load('flaky_api.dsl') }
+  
+  it "handles failures gracefully" do
+    # Force failure mode
+    allow_any_instance_of(FakeDataDSL::Behaviors::Failure)
+      .to receive(:should_apply?).and_return(true)
+    
+    expect { schema.generate }
+      .to raise_error(FakeDataDSL::Errors::SimulatedFailure)
+  end
+  
+  it "retries on connection drops" do
+    client = APIClient.new
+    allow(client).to receive(:fetch)
+      .and_raise(FakeDataDSL::Errors::SimulatedConnectionDrop)
+      .once
+      .and_call_original
+    
+    result = client.fetch_with_retry
+    expect(result).to be_present
+  end
+end
+```
+
+---
+
+## Behavior Configuration
+
+### Global Settings
+
+```ruby
+FakeDataDSL.configure do |config|
+  # Maximum allowed latency
+  config.limits.max_latency_ms = 5000  # 5 seconds
+  
+  # Disable all behaviors (for certain tests)
+  config.behaviors_enabled = false
+end
+```
+
+### Disabling Behaviors
+
+```ruby
+# Globally
+FakeDataDSL.configure { |c| c.behaviors_enabled = false }
+
+# Per generation
+schema.generate(behaviors: false)
+```
+
+---
+
+## Use Cases
+
+### Load Testing
+
+```dsl
+LoadTestAPI:
+  @latency 50..2000ms     # Variable latency
+  
+  data: array(Item, 10..100)
+```
+
+### Chaos Engineering
+
+```dsl
+ChaosAPI:
+  @latency 100..5000ms
+  @failure 10%
+  @close_connection 5%
+  @simulate_error 500 3%
+  @simulate_error 503 2%
+  @partial_data 15%
+  
+  data: object
+```
+
+### Integration Testing
+
+```dsl
+ThirdPartyAPI:
+  @latency 200..1000ms    # Realistic external API latency
+  @failure 1%             # Occasional failures
+  @simulate_error 429 5%  # Rate limiting
+  
+  data: object
+```
+
+---
+
+## Next Steps
+
+- [Latency Simulation](latency.md) - Detailed latency guide
+- [Failure Simulation](failure.md) - Failure testing guide
+- [Custom Behaviors](custom.md) - Creating your own behaviors
+