servus 0.1.2 → 0.1.4

data/docs/integration/2_testing.md

@@ -0,0 +1,164 @@
+# @title Integration / 2. Testing
+
+# Testing
+
+Services are designed for easy testing with explicit inputs (arguments) and outputs (Response objects). No special test infrastructure needed.
+
+## Schema Example Helpers
+
+Servus provides test helpers that extract `example` values from your JSON schemas, making it easy to generate test fixtures without maintaining separate factories.
+
+### Setup
+
+Include the helpers in your test suite:
+
+```ruby
+# spec/spec_helper.rb
+require 'servus/testing'
+
+RSpec.configure do |config|
+  config.include Servus::Testing::ExampleBuilders
+end
+```
+
+### Using Schema Examples
+
+Add `example` or `examples` keywords to your schemas:
+
+```ruby
+class ProcessPayment::Service < Servus::Base
+  schema(
+    arguments: {
+      type: "object",
+      properties: {
+        user_id: { type: "integer", example: 123 },
+        amount: { type: "number", example: 100.0 },
+        currency: { type: "string", examples: ["USD", "EUR", "GBP"] }
+      }
+    },
+    result: {
+      type: "object",
+      properties: {
+        transaction_id: { type: "string", example: "txn_abc123" },
+        status: { type: "string", example: "approved" }
+      }
+    }
+  )
+end
+```
+
+Then use the helpers in your tests:
+
+```ruby
+RSpec.describe ProcessPayment::Service do
+  it "processes payment successfully" do
+    # Extract examples from schema and override specific values
+    args = servus_arguments_example(ProcessPayment::Service, amount: 50.0)
+    # => { user_id: 123, amount: 50.0, currency: "USD" }
+
+    result = ProcessPayment::Service.call(**args)
+
+    expect(result).to be_success
+    expect(result.data.keys).to match_array(
+      servus_result_example(ProcessPayment::Service).data.keys
+    )
+  end
+
+  it "handles different currencies" do
+    %w[USD EUR GBP].each do |currency|
+      result = ProcessPayment::Service.call(
+        **servus_arguments_example(ProcessPayment::Service, currency: currency)
+      )
+      expect(result).to be_success
+    end
+  end
+end
+```
+
+### Deep Merging
+
+Overrides are deep-merged with schema examples, allowing you to override nested values:
+
+```ruby
+# Schema has nested structure
+args = servus_arguments_example(
+  CreateUser::Service,
+  user: { profile: { age: 35 } }
+)
+# => { user: { id: 1, profile: { name: 'Alice', age: 35 } } }
+```
+
+### Available Helpers
+
+- `servus_arguments_example(ServiceClass, **overrides)` - Returns hash of argument examples
+- `servus_result_example(ServiceClass, **overrides)` - Returns Response object with result examples
+
+## Basic Testing Pattern
+
+```ruby
+RSpec.describe ProcessPayment::Service do
+  describe ".call" do
+    let(:user) { create(:user, balance: 1000) }
+
+    subject(:result) { described_class.call(user_id: user.id, amount: amount) }
+
+    context "with sufficient balance" do
+      let(:amount) { 50 }
+
+      it "processes payment" do
+        expect(result.success?).to be true
+        expect(result.data[:new_balance]).to eq(950)
+        expect(result.reload.balance).to eq(950)
+      end
+    end
+
+    context "with insufficient balance" do
+      let(:amount) { 2000 }
+
+      it "returns failure" do
+        expect(result.success?).to be false
+        expect(result.error.message).to eq("Insufficient funds")
+        expect(result.error).to be_a(Servus::Support::Errors::ServiceError)
+      end
+    end
+  end
+end
+```
+
+## Testing Service Composition
+
+When testing services that call other services, mock the child services:
+
+```ruby
+describe Users::CreateWithAccount::Service do
+  # Make local or global helpers to clean up tests
+  def servus_success_result(data)
+    Servus::Support::Response.new(success: true, data: data, error: nil)
+  end
+
+  it "calls both create services" do
+    # Mock child services
+    allow(Users::Create::Service).to receive(:call).and_return(servus_success_result{ user: user })
+    allow(Accounts::Create::Service).to receive(:call).and_return(servus_success_result{ account: account })
+
+    result = described_class.call(email: "test@example.com", plan: "premium")
+
+    expect(Users::Create::Service).to have_received(:call)
+    expect(Accounts::Create::Service).to have_received(:call)
+
+    expect(result.success?).to be true
+  end
+end
+```
+
+## Testing Schema Validation
+
+Don't test that valid arguments pass validation - that's testing the framework. Do test that your schema catches invalid inputs:
+
+```ruby
+it "validates required fields" do
+  expect {
+    Service.call(invalid: "params")
+  }.to raise_error(Servus::Support::Errors::ValidationError, /required/)
+end
+```

data/docs/integration/3_rails_integration.md

@@ -0,0 +1,99 @@
+# @title Integration / 3. Rails Integration
+
+# Rails Integration
+
+Servus core works in any Ruby application. Rails-specific features (async, controller helpers, generators) are optional additions that integrate with Rails conventions.
+
+## Controller Integration
+
+Use the `run_service` helper to call services from controllers with automatic error handling:
+
+```ruby
+class UsersController < ApplicationController
+  include Servus::Helpers::ControllerHelpers
+
+  def create
+    run_service(Users::Create::Service, user_params)
+  end
+
+  # Failures automatically render JSON:
+  # { "error": { "code": "validation_error", "message": "..." } }
+  # with appropriate HTTP status code
+  #
+  # Success will go to view and service result will be available on @result
+end
+```
+
+Without the helper, handle responses manually:
+
+```ruby
+def create
+  result = Users::Create::Service.call(user_params)
+  if result.success?
+    render json: { user: result.data[:user] }, status: :created
+  else
+    render json: { error: result.error.api_error }, status: error_status(result.error)
+  end
+end
+```
+
+## Generator
+
+Generate services with specs and schema files:
+
+```bash
+rails generate servus:service process_payment
+
+# Creates:
+# app/services/process_payment/service.rb
+# spec/services/process_payment/service_spec.rb
+# app/schemas/services/process_payment/arguments.json
+# app/schemas/services/process_payment/result.json
+```
+
+Schema files are optional - delete them if you don't need validation.
+
+## Autoloading
+
+Servus follows Rails autoloading conventions. Services in `app/services/` are automatically loaded by Rails:
+
+```ruby
+# app/services/users/create/service.rb
+module Users
+  module Create
+    class Service < Servus::Base
+      # ...
+    end
+  end
+end
+
+# Rails autoloads this as Users::Create::Service
+```
+
+## Configuration
+
+Configure Servus in an initializer if needed:
+
+```ruby
+# config/initializers/servus.rb
+Servus.configure do |config|
+  config.schema_root = Rails.root.join('config/schemas')
+end
+```
+
+Most applications don't need any configuration.
+
+## Background Jobs
+
+Async execution requires ActiveJob setup. Configure your adapter:
+
+```ruby
+# config/application.rb
+config.active_job.queue_adapter = :sidekiq
+```
+
+Then use `.call_async`:
+
+```ruby
+Users::SendWelcomeEmail::Service.call_async(user_id: user.id)
+```