light-services 2.2 → 3.0.0

data/docs/testing.md

@@ -0,0 +1,549 @@
+# Testing
+
+Testing Light Services is straightforward. This guide covers strategies for unit testing your services effectively.
+
+## Basic Service Testing
+
+### Testing a Simple Service
+
+```ruby
+# app/services/greet_service.rb
+class GreetService < ApplicationService
+  arg :name, type: String
+
+  step :greet
+
+  output :message
+
+  private
+
+  def greet
+    self.message = "Hello, #{name}!"
+  end
+end
+```
+
+```ruby
+# spec/services/greet_service_spec.rb
+RSpec.describe GreetService do
+  describe ".run" do
+    it "returns a greeting message" do
+      service = described_class.run(name: "John")
+
+      expect(service).to be_success
+      expect(service.message).to eq("Hello, John!")
+    end
+  end
+end
+```
+
+## Testing Success and Failure
+
+```ruby
+RSpec.describe User::Create do
+  describe ".run" do
+    context "with valid attributes" do
+      let(:attributes) { { email: "test@example.com", password: "password123" } }
+
+      it "creates a user" do
+        service = described_class.run(attributes: attributes)
+
+        expect(service).to be_success
+        expect(service.user).to be_persisted
+        expect(service.user.email).to eq("test@example.com")
+      end
+    end
+
+    context "with invalid attributes" do
+      let(:attributes) { { email: "", password: "" } }
+
+      it "returns errors" do
+        service = described_class.run(attributes: attributes)
+
+        expect(service).to be_failed
+        expect(service.errors[:email]).to be_present
+      end
+    end
+  end
+end
+```
+
+## Testing with Context
+
+When services use context to share data, test both scenarios:
+
+```ruby
+RSpec.describe Comment::Create do
+  let(:current_user) { create(:user) }
+  let(:post) { create(:post) }
+
+  describe ".run" do
+    context "with current_user in context" do
+      it "creates a comment by the current user" do
+        service = described_class.run(
+          current_user: current_user,
+          post_id: post.id,
+          text: "Great post!"
+        )
+
+        expect(service).to be_success
+        expect(service.comment.user).to eq(current_user)
+      end
+    end
+
+    context "without current_user" do
+      it "fails with authorization error" do
+        service = described_class.run(
+          current_user: nil,
+          post_id: post.id,
+          text: "Great post!"
+        )
+
+        expect(service).to be_failed
+        expect(service.errors[:authorization]).to be_present
+      end
+    end
+  end
+end
+```
+
+## Testing Child Services in Context
+
+When testing services that call other services via `.with(self)`:
+
+```ruby
+RSpec.describe Order::Create do
+  let(:current_user) { create(:user) }
+  let(:product) { create(:product, price: 100) }
+
+  it "creates order and order items in the same transaction" do
+    service = described_class.run(
+      current_user: current_user,
+      items: [{ product_id: product.id, quantity: 2 }]
+    )
+
+    expect(service).to be_success
+    expect(service.order.order_items.count).to eq(1)
+    expect(service.order.total).to eq(200)
+  end
+
+  it "rolls back everything if child service fails" do
+    # Stub the child service to fail
+    allow_any_instance_of(OrderItem::Create).to receive(:validate).and_wrap_original do |method, *args|
+      method.receiver.errors.add(:base, "Simulated failure")
+    end
+
+    expect {
+      described_class.run(
+        current_user: current_user,
+        items: [{ product_id: product.id, quantity: 2 }]
+      )
+    }.not_to change(Order, :count)
+  end
+end
+```
+
+## Testing Conditional Steps
+
+```ruby
+RSpec.describe User::Register do
+  describe "conditional steps" do
+    context "when send_welcome_email is true" do
+      it "sends a welcome email" do
+        expect {
+          described_class.run(
+            email: "test@example.com",
+            password: "password123",
+            send_welcome_email: true
+          )
+        }.to have_enqueued_mail(UserMailer, :welcome)
+      end
+    end
+
+    context "when send_welcome_email is false" do
+      it "does not send a welcome email" do
+        expect {
+          described_class.run(
+            email: "test@example.com",
+            password: "password123",
+            send_welcome_email: false
+          )
+        }.not_to have_enqueued_mail(UserMailer, :welcome)
+      end
+    end
+  end
+end
+```
+
+## Testing Early Exit with done!
+
+```ruby
+RSpec.describe User::FindOrCreate do
+  describe "when user exists" do
+    let!(:existing_user) { create(:user, email: "existing@example.com") }
+
+    it "returns existing user without creating new one" do
+      expect {
+        service = described_class.run(email: "existing@example.com")
+        expect(service.user).to eq(existing_user)
+      }.not_to change(User, :count)
+    end
+  end
+
+  describe "when user does not exist" do
+    it "creates a new user" do
+      expect {
+        service = described_class.run(email: "new@example.com")
+        expect(service.user.email).to eq("new@example.com")
+      }.to change(User, :count).by(1)
+    end
+  end
+end
+```
+
+## Testing Configuration Overrides
+
+```ruby
+RSpec.describe MyService do
+  describe "with raise_on_error config" do
+    it "raises exception when configured" do
+      expect {
+        described_class.run({ invalid: true }, { raise_on_error: true })
+      }.to raise_error(Light::Services::Error)
+    end
+
+    it "collects errors by default" do
+      service = described_class.run(invalid: true)
+      
+      expect(service).to be_failed
+      expect { service }.not_to raise_error
+    end
+  end
+end
+```
+
+## Testing run! vs run
+
+```ruby
+RSpec.describe Payment::Process do
+  context "using run" do
+    it "returns failed service on error" do
+      service = described_class.run(amount: -100)
+      
+      expect(service).to be_failed
+      expect(service.errors[:amount]).to include("must be positive")
+    end
+  end
+
+  context "using run!" do
+    it "raises exception on error" do
+      expect {
+        described_class.run!(amount: -100)
+      }.to raise_error(Light::Services::Error, /Amount must be positive/)
+    end
+  end
+end
+```
+
+## Testing Warnings
+
+```ruby
+RSpec.describe DataImport do
+  it "completes with warnings for skipped records" do
+    service = described_class.run(data: mixed_valid_invalid_data)
+
+    expect(service).to be_success # Warnings don't fail the service
+    expect(service.warnings?).to be true
+    expect(service.warnings[:skipped]).to include("Row 3: invalid format")
+  end
+end
+```
+
+## Mocking External Services
+
+```ruby
+RSpec.describe Payment::Charge do
+  let(:stripe_client) { instance_double(Stripe::PaymentIntent) }
+
+  before do
+    allow(Stripe::PaymentIntent).to receive(:create).and_return(stripe_client)
+    allow(stripe_client).to receive(:id).and_return("pi_123")
+  end
+
+  it "processes payment successfully" do
+    service = described_class.run(amount: 1000, card_token: "tok_visa")
+
+    expect(service).to be_success
+    expect(service.payment_intent_id).to eq("pi_123")
+  end
+
+  context "when Stripe fails" do
+    before do
+      allow(Stripe::PaymentIntent).to receive(:create)
+        .and_raise(Stripe::CardError.new("Card declined", nil, nil))
+    end
+
+    it "handles the error gracefully" do
+      service = described_class.run(amount: 1000, card_token: "tok_declined")
+
+      expect(service).to be_failed
+      expect(service.errors[:payment]).to include("Card declined")
+    end
+  end
+end
+```
+
+## Testing Argument Validation
+
+```ruby
+RSpec.describe MyService do
+  describe "argument validation" do
+    it "requires name argument" do
+      expect {
+        described_class.run(name: nil)
+      }.to raise_error(Light::Services::ArgTypeError)
+    end
+
+    it "validates argument type" do
+      expect {
+        described_class.run(name: 123) # expects String
+      }.to raise_error(Light::Services::ArgTypeError, /must be a String/)
+    end
+
+    it "accepts optional arguments as nil" do
+      service = described_class.run(name: "John", nickname: nil)
+      expect(service).to be_success
+    end
+  end
+end
+```
+
+## Shared Examples for CRUD Services
+
+```ruby
+# spec/support/shared_examples/crud_service.rb
+RSpec.shared_examples "a create service" do |model_class|
+  let(:valid_attributes) { attributes_for(model_class.name.underscore.to_sym) }
+  let(:current_user) { create(:user) }
+
+  it "creates a record" do
+    expect {
+      described_class.run(current_user: current_user, attributes: valid_attributes)
+    }.to change(model_class, :count).by(1)
+  end
+
+  it "returns the created record" do
+    service = described_class.run(current_user: current_user, attributes: valid_attributes)
+    expect(service.record).to be_a(model_class)
+    expect(service.record).to be_persisted
+  end
+end
+
+# Usage in specs
+RSpec.describe Post::Create do
+  it_behaves_like "a create service", Post
+end
+```
+
+## Test Helpers
+
+Create a helper module for common service testing patterns:
+
+```ruby
+# spec/support/service_helpers.rb
+module ServiceHelpers
+  def expect_service_success(service)
+    expect(service).to be_success, -> { "Expected success but got errors: #{service.errors.to_h}" }
+  end
+
+  def expect_service_failure(service, key = nil)
+    expect(service).to be_failed
+    expect(service.errors[key]).to be_present if key
+  end
+end
+
+RSpec.configure do |config|
+  config.include ServiceHelpers, type: :service
+end
+```
+
+## Custom RSpec Matchers
+
+Light Services provides built-in RSpec matchers to make testing more expressive and readable.
+
+### Setup
+
+Add this to your `spec/spec_helper.rb` or `spec/rails_helper.rb`:
+
+```ruby
+require 'light/services/rspec'
+```
+
+This automatically includes all matchers in your RSpec tests.
+
+### DSL Definition Matchers
+
+#### `define_argument`
+
+Test that a service defines specific arguments:
+
+```ruby
+RSpec.describe User::Create do
+  it { expect(described_class).to define_argument(:email) }
+  it { expect(described_class).to define_argument(:email).with_type(String) }
+  it { expect(described_class).to define_argument(:role).optional }
+  it { expect(described_class).to define_argument(:status).with_default("pending") }
+  it { expect(described_class).to define_argument(:current_user).with_context }
+  
+  # Chaining modifiers
+  it { expect(described_class).to define_argument(:age).with_type(Integer).with_default(18) }
+end
+```
+
+#### `define_output`
+
+Test that a service defines specific outputs:
+
+```ruby
+RSpec.describe User::Create do
+  it { expect(described_class).to define_output(:user) }
+  it { expect(described_class).to define_output(:user).with_type(User) }
+  it { expect(described_class).to define_output(:token).optional }
+  it { expect(described_class).to define_output(:count).with_default(0) }
+end
+```
+
+#### `define_step` and `define_steps`
+
+Test that a service defines specific steps:
+
+```ruby
+RSpec.describe User::Create do
+  # Single step
+  it { expect(described_class).to define_step(:validate) }
+  it { expect(described_class).to define_step(:cleanup).with_always(true) }
+  it { expect(described_class).to define_step(:notify).with_if(:should_notify?) }
+  it { expect(described_class).to define_step(:skip_log).with_unless(:logging_enabled?) }
+  
+  # Multiple steps
+  it { expect(described_class).to define_steps(:validate, :process, :save) }
+  
+  # Steps in order
+  it { expect(described_class).to define_steps_in_order(:validate, :process, :save) }
+end
+```
+
+### Error and Warning Matchers
+
+#### `have_error_on` and `have_errors_on`
+
+Test service errors:
+
+```ruby
+RSpec.describe User::Create do
+  context "with invalid email" do
+    let(:service) { described_class.run(email: "") }
+    
+    it { expect(service).to have_error_on(:email) }
+    it { expect(service).to have_error_on(:email).with_message("can't be blank") }
+    it { expect(service).to have_error_on(:email).with_message(/blank/) } # regex
+    
+    # Multiple errors (requires break_on_error: false)
+    it { expect(service).to have_errors_on(:email, :password) }
+  end
+end
+```
+
+#### `have_warning_on` and `have_warnings_on`
+
+Test service warnings:
+
+```ruby
+RSpec.describe Data::Import do
+  context "with deprecated format" do
+    let(:service) { described_class.run(format: "csv_v1") }
+    
+    it { expect(service).to have_warning_on(:format) }
+    it { expect(service).to have_warning_on(:format).with_message("format is deprecated") }
+  end
+end
+```
+
+### Execution Matchers
+
+These matchers require step tracking. Add this to your service:
+
+```ruby
+class ApplicationService < Light::Services::Base
+  output :executed_steps, default: -> { [] }
+  
+  after_step_run do |service, step_name|
+    service.executed_steps << step_name
+  end
+end
+```
+
+#### `execute_step` and `skip_step`
+
+```ruby
+RSpec.describe Order::Process do
+  context "with premium user" do
+    let(:service) { described_class.run(user: premium_user) }
+    
+    it { expect(service).to execute_step(:apply_discount) }
+    it { expect(service).to skip_step(:show_ads) }
+  end
+end
+```
+
+#### `execute_steps` and `execute_steps_in_order`
+
+```ruby
+RSpec.describe Order::Process do
+  let(:service) { described_class.run(order: order) }
+  
+  it { expect(service).to execute_steps(:validate, :charge, :fulfill) }
+  it { expect(service).to execute_steps_in_order(:validate, :charge, :fulfill) }
+end
+```
+
+### Callback Matchers
+
+These matchers require callback tracking. Add this to your service:
+
+```ruby
+class ApplicationService < Light::Services::Base
+  output :callback_log, default: -> { [] }
+  
+  before_service_run { |service| service.callback_log << :before_service_run }
+  after_service_run { |service| service.callback_log << :after_service_run }
+  on_service_success { |service| service.callback_log << :on_service_success }
+  on_service_failure { |service| service.callback_log << :on_service_failure }
+  
+  after_step_run { |service, step| service.callback_log << [:after_step_run, step] }
+end
+```
+
+#### `trigger_callback`
+
+```ruby
+RSpec.describe Order::Process do
+  context "when successful" do
+    let(:service) { described_class.run(order: valid_order) }
+    
+    it { expect(service).to trigger_callback(:before_service_run) }
+    it { expect(service).to trigger_callback(:on_service_success) }
+    it { expect(service).not_to trigger_callback(:on_service_failure) }
+    
+    # Step-specific callbacks
+    it { expect(service).to trigger_callback(:after_step_run).for_step(:validate) }
+  end
+end
+```
+
+## What's Next?
+
+Learn best practices for organizing your services:
+
+[Next: Best Practices](best-practices.md)
+

data/lib/generators/light_services/install/USAGE

@@ -0,0 +1,15 @@
+Description:
+    Installs Light::Services into your Rails application by creating
+    an ApplicationService base class and an optional initializer.
+
+Example:
+    bin/rails generate light_services:install
+
+    This will create:
+        app/services/application_service.rb
+        config/initializers/light_services.rb
+        spec/services/application_service_spec.rb (if RSpec is detected)
+
+Options:
+    --skip-initializer  Skip creating the initializer file
+    --skip-spec         Skip creating the spec file

data/lib/generators/light_services/install/install_generator.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module LightServices
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :skip_initializer, type: :boolean, default: false,
+                                      desc: "Skip creating the initializer file"
+      class_option :skip_spec, type: :boolean, default: false,
+                               desc: "Skip creating the spec file"
+
+      desc "Creates ApplicationService and initializer for Light::Services"
+
+      def create_application_service
+        template "application_service.rb.tt", "app/services/application_service.rb"
+      end
+
+      def create_initializer
+        return if options[:skip_initializer]
+
+        template "initializer.rb.tt", "config/initializers/light_services.rb"
+      end
+
+      def create_spec_file
+        return if options[:skip_spec]
+        return unless rspec_installed?
+
+        template "application_service_spec.rb.tt", "spec/services/application_service_spec.rb"
+      end
+
+      private
+
+      def rspec_installed?
+        File.directory?(File.join(destination_root, "spec"))
+      end
+    end
+  end
+end

data/lib/generators/light_services/install/templates/application_service.rb.tt

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+class ApplicationService < Light::Services::Base
+  # Add common arguments, callbacks, or helpers shared across all services.
+  #
+  # Example: Add a context argument for the current user
+  # arg :current_user, type: User, optional: true, context: true
+end

data/lib/generators/light_services/install/templates/application_service_spec.rb.tt

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe ApplicationService, type: :service do
+  # Add specs for shared behavior defined in ApplicationService
+end

data/lib/generators/light_services/install/templates/initializer.rb.tt

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+Light::Services.configure do |config|
+  # Whether to wrap service execution in a database transaction.
+  # config.use_transactions = true
+
+  # Whether to copy errors to parent service in chain.
+  # config.load_errors = true
+
+  # Whether to stop executing steps when an error is added.
+  # config.break_on_error = true
+
+  # Whether to raise Light::Services::Error when service fails.
+  # config.raise_on_error = false
+
+  # Whether to rollback the transaction when an error is added.
+  # config.rollback_on_error = true
+
+  # Whether to load warnings from the context.
+  # config.load_warnings = true
+
+  # Whether to stop executing steps when a warning is added.
+  # config.break_on_warning = false
+
+  # Whether to raise Light::Services::Error when service has warnings.
+  # config.raise_on_warning = false
+
+  # Whether to rollback the transaction when a warning is added.
+  # config.rollback_on_warning = false
+end

data/lib/generators/light_services/service/USAGE

@@ -0,0 +1,21 @@
+Description:
+    Creates a new service class that inherits from ApplicationService.
+    Supports namespaced services (e.g., user/create creates User::Create).
+
+Example:
+    bin/rails generate light_services:service user/create
+
+    This will create:
+        app/services/user/create.rb
+        spec/services/user/create_spec.rb (if RSpec is detected)
+
+    bin/rails generate light_services:service CreateOrder --args=user product --steps=validate process --outputs=order
+
+    This will create a service with predefined arguments, steps, and outputs.
+
+Options:
+    --args          List of arguments for the service (e.g., --args=user product)
+    --steps         List of steps for the service (e.g., --steps=validate process)
+    --outputs       List of outputs for the service (e.g., --outputs=result)
+    --skip-spec     Skip creating the spec file
+    --parent        Parent class (default: ApplicationService)