anima-core 0.2.1 → 1.0.0

data/skills/rspec/examples/mocks/expectations.rb

@@ -0,0 +1,137 @@
+# RSpec Mocks: Message Expectations (expect) Examples
+# Source: rspec-mocks gem features/basics/expecting_messages.feature
+
+# expect(...).to receive - message must be called
+RSpec.describe "message expectations" do
+  describe "basic expectations" do
+    it "fails if message is not received" do
+      dbl = double("collaborator")
+      expect(dbl).to receive(:foo)
+
+      # Without calling dbl.foo, this would fail with:
+      # "(Double 'collaborator').foo(*(any args)) expected: 1 time..."
+      dbl.foo
+    end
+
+    it "passes when message is received" do
+      dbl = double("collaborator")
+      expect(dbl).to receive(:foo)
+      dbl.foo
+    end
+  end
+
+  describe "negative expectations" do
+    it "fails if forbidden message is received" do
+      dbl = double("collaborator")
+      expect(dbl).not_to receive(:foo)
+
+      # Calling dbl.foo here would fail immediately
+    end
+  end
+
+  describe "custom failure messages" do
+    it "provides context when expectation fails" do
+      dbl = double("collaborator")
+      expect(dbl).to receive(:foo), "dbl should call :foo during authentication"
+      dbl.foo
+    end
+  end
+
+  describe "expect vs allow" do
+    it "allow permits but doesn't require calls" do
+      dbl = double("collaborator")
+      allow(dbl).to receive(:foo)
+      # Not calling foo is fine
+    end
+
+    it "expect requires calls" do
+      dbl = double("collaborator")
+      expect(dbl).to receive(:foo)
+      dbl.foo  # Must be called
+    end
+  end
+end
+
+# Practical example: verifying collaborator interactions
+RSpec.describe Account do
+  subject(:account) { build(:account, logger:, balance: 1000) }
+
+  let(:logger) { instance_double("Logger") }
+
+  describe "#close" do
+    it "logs the closure event" do
+      expect(logger).to receive(:info).with("Account closed")
+      account.close
+    end
+
+    it "logs the final balance" do
+      expect(logger).to receive(:info).with(/Balance: \d+/)
+      account.close
+    end
+  end
+
+  describe "#withdraw" do
+    context "with sufficient funds" do
+      it "does not log warnings" do
+        allow(logger).to receive(:info)
+        expect(logger).not_to receive(:warn)
+
+        account.withdraw(100)
+      end
+    end
+
+    context "with insufficient funds" do
+      it "logs a warning" do
+        allow(logger).to receive(:info)
+        expect(logger).to receive(:warn).with(/insufficient funds/i)
+
+        account.withdraw(10_000)
+      end
+    end
+  end
+end
+
+# Practical example: event publishing
+RSpec.describe OrderService do
+  subject(:service) { build(:order_service, publisher:) }
+
+  let(:publisher) { instance_double("EventPublisher") }
+  let(:order) { build(:order) }
+
+  describe "#complete" do
+    it "publishes order completed event" do
+      expect(publisher).to receive(:publish).with(
+        "order.completed",
+        hash_including(order_id: order.id)
+      )
+
+      service.complete(order)
+    end
+
+    it "publishes exactly one event" do
+      expect(publisher).to receive(:publish).once
+      service.complete(order)
+    end
+  end
+end
+
+# Combining expect and allow on same double
+RSpec.describe "mixed expectations and stubs" do
+  subject(:processor) { build(:payment_processor, gateway:, logger:) }
+
+  let(:gateway) { instance_double("PaymentGateway") }
+  let(:logger) { instance_double("Logger") }
+
+  describe "#process" do
+    it "charges gateway and logs result" do
+      # Stub the gateway response
+      allow(gateway).to receive(:charge).and_return(success: true)
+
+      # Expect logging to happen
+      expect(logger).to receive(:info).with(/Payment processed/)
+
+      processor.process(amount: 100)
+    end
+  end
+end
+

data/skills/rspec/examples/mocks/message_chains.rb

@@ -0,0 +1,173 @@
+# RSpec Mocks: Message Chains Examples
+# Source: rspec-mocks gem features/working_with_legacy_code/message_chains.feature
+
+# WARNING: receive_message_chain violates Law of Demeter.
+# It often indicates:
+# - Code knows too much about collaborator structure
+# - Need for facade or wrapper
+# - Missing encapsulation
+#
+# Use only for legacy code. Prefer proper encapsulation.
+
+# receive_message_chain - stub chained method calls
+RSpec.describe "receive_message_chain" do
+  describe "syntax forms" do
+    it "accepts dot-separated string" do
+      dbl = double("collaborator")
+      allow(dbl).to receive_message_chain("foo.bar.baz") { :result }
+
+      expect(dbl.foo.bar.baz).to eq(:result)
+    end
+
+    it "accepts symbols with hash for final return" do
+      dbl = double("collaborator")
+      allow(dbl).to receive_message_chain(:foo, :bar, baz: :result)
+
+      expect(dbl.foo.bar.baz).to eq(:result)
+    end
+
+    it "accepts symbols with block" do
+      dbl = double("collaborator")
+      allow(dbl).to receive_message_chain(:foo, :bar, :baz) { :result }
+
+      expect(dbl.foo.bar.baz).to eq(:result)
+    end
+  end
+
+  describe "intermediate objects" do
+    it "creates intermediates automatically" do
+      dbl = double("collaborator")
+      allow(dbl).to receive_message_chain(:a, :b, :c) { "end" }
+
+      # Each call returns a new double
+      intermediate = dbl.a.b
+      expect(intermediate.c).to eq("end")
+    end
+  end
+
+  describe "with any_instance_of" do
+    it "stubs chains on any instance" do
+      allow_any_instance_of(User).to receive_message_chain("account.balance") { 100 }
+
+      user = User.new
+      expect(user.account.balance).to eq(100)
+    end
+  end
+end
+
+# ActiveRecord example - common legacy pattern
+RSpec.describe "ActiveRecord chaining" do
+  # Legacy code might do: Article.recent.published.limit(5)
+  describe "stubbing scope chains" do
+    it "stubs the entire chain" do
+      articles = build_list(:article, 3)
+      allow(Article).to receive_message_chain("recent.published.limit") { articles }
+
+      expect(Article.recent.published.limit(5)).to eq(articles)
+    end
+  end
+end
+
+# Better alternatives
+RSpec.describe "alternatives to message chains" do
+  # PROBLEM: Code uses deep chains
+  class LegacyReportGenerator
+    def generate
+      User.active.verified.with_orders.map(&:email)
+    end
+  end
+
+  # BAD: Stubbing chain
+  describe LegacyReportGenerator do
+    subject(:generator) { LegacyReportGenerator.new }
+
+    it "generates report with message chain" do
+      users = build_list(:user, 2, email: "test@example.com")
+      allow(User).to receive_message_chain("active.verified.with_orders") { users }
+
+      expect(generator.generate).to eq(["test@example.com", "test@example.com"])
+    end
+  end
+
+  # BETTER: Extract scope into model method
+  class User < ApplicationRecord
+    def self.eligible_for_report
+      active.verified.with_orders
+    end
+  end
+
+  class BetterReportGenerator
+    def initialize(user_scope: User)
+      @user_scope = user_scope
+    end
+
+    def generate
+      @user_scope.eligible_for_report.map(&:email)
+    end
+  end
+
+  describe BetterReportGenerator do
+    subject(:generator) { BetterReportGenerator.new(user_scope:) }
+
+    let(:user_scope) { class_double("User") }
+
+    it "generates report with single stub" do
+      users = build_list(:user, 2, email: "test@example.com")
+      allow(user_scope).to receive(:eligible_for_report).and_return(users)
+
+      expect(generator.generate).to eq(["test@example.com", "test@example.com"])
+    end
+  end
+
+  # BEST: Inject the query result directly
+  class CleanReportGenerator
+    def initialize(user_repository:)
+      @user_repository = user_repository
+    end
+
+    def generate
+      @user_repository.eligible_users.map(&:email)
+    end
+  end
+
+  describe CleanReportGenerator do
+    subject(:generator) { CleanReportGenerator.new(user_repository:) }
+
+    let(:user_repository) { instance_double("UserRepository") }
+
+    it "generates report with injected dependency" do
+      users = build_list(:user, 2)
+      allow(users).to receive(:map).and_return(["a@test.com", "b@test.com"])
+      allow(user_repository).to receive(:eligible_users).and_return(users)
+
+      result = generator.generate
+      expect(result).to eq(["a@test.com", "b@test.com"])
+    end
+  end
+end
+
+# When message chains might be acceptable
+RSpec.describe "acceptable chain usage" do
+  describe "null object chains" do
+    it "stubs deep configuration access" do
+      # Configuration objects often have deep chains
+      config = double("config").as_null_object
+      allow(config).to receive_message_chain("database.connection.pool_size") { 5 }
+
+      expect(config.database.connection.pool_size).to eq(5)
+    end
+  end
+
+  describe "test setup helpers" do
+    # In test setup, brevity might outweigh purity
+    it "quickly stubs Rails request chain" do
+      controller = double("controller")
+      allow(controller).to receive_message_chain("request.headers.[]")
+        .with("Authorization")
+        .and_return("Bearer token123")
+
+      expect(controller.request.headers["Authorization"]).to eq("Bearer token123")
+    end
+  end
+end
+

data/skills/rspec/examples/mocks/ordering.rb

@@ -0,0 +1,144 @@
+# RSpec Mocks: Message Order Examples
+# Source: rspec-mocks gem features/setting_constraints/message_order.feature
+
+# NOTE: Ordered expectations can make specs brittle.
+# Use only when message order is truly important.
+
+# .ordered - enforce message sequence
+RSpec.describe "message ordering" do
+  describe "basic ordering" do
+    it "requires messages in declared order" do
+      dbl = double("collaborator")
+
+      expect(dbl).to receive(:step_1).ordered
+      expect(dbl).to receive(:step_2).ordered
+      expect(dbl).to receive(:step_3).ordered
+
+      dbl.step_1
+      dbl.step_2
+      dbl.step_3
+    end
+  end
+
+  describe "across multiple doubles" do
+    it "enforces order across collaborators" do
+      collaborator_1 = double("first")
+      collaborator_2 = double("second")
+
+      expect(collaborator_1).to receive(:step_1).ordered
+      expect(collaborator_2).to receive(:step_2).ordered
+      expect(collaborator_1).to receive(:step_3).ordered
+
+      collaborator_1.step_1
+      collaborator_2.step_2
+      collaborator_1.step_3
+    end
+  end
+
+  describe "with have_received" do
+    it "verifies order using spies" do
+      invitation = spy("invitation")
+
+      invitation.prepare
+      invitation.send_email
+      invitation.log_delivery
+
+      expect(invitation).to have_received(:prepare).ordered
+      expect(invitation).to have_received(:send_email).ordered
+      expect(invitation).to have_received(:log_delivery).ordered
+    end
+  end
+
+  describe "partial ordering" do
+    it "only ordered expectations must be in sequence" do
+      dbl = double("collaborator")
+
+      allow(dbl).to receive(:any_time)  # Not ordered
+      expect(dbl).to receive(:first).ordered
+      expect(dbl).to receive(:second).ordered
+
+      dbl.any_time  # Can be called anytime
+      dbl.first
+      dbl.any_time  # Still fine
+      dbl.second
+      dbl.any_time  # Still fine
+    end
+  end
+end
+
+# Practical example: transaction workflow
+RSpec.describe PaymentProcessor do
+  subject(:processor) { build(:payment_processor, gateway:, ledger:) }
+
+  let(:gateway) { instance_double("PaymentGateway") }
+  let(:ledger) { instance_double("Ledger") }
+  let(:payment) { build(:payment, amount: 100) }
+
+  describe "#process" do
+    context "when order matters for consistency" do
+      it "validates before charging" do
+        # Must validate first, then charge
+        expect(gateway).to receive(:validate).ordered.and_return(true)
+        expect(gateway).to receive(:charge).ordered.and_return(true)
+        allow(ledger).to receive(:record)
+
+        processor.process(payment)
+      end
+
+      it "records in ledger after successful charge" do
+        allow(gateway).to receive(:validate).and_return(true)
+
+        expect(gateway).to receive(:charge).ordered.and_return(true)
+        expect(ledger).to receive(:record).ordered
+
+        processor.process(payment)
+      end
+    end
+  end
+end
+
+# Practical example: state machine transitions
+RSpec.describe OrderStateMachine do
+  subject(:machine) { build(:order_state_machine, logger:) }
+
+  let(:logger) { spy("logger") }
+
+  describe "#complete" do
+    it "transitions through states in order" do
+      machine.complete
+
+      expect(logger).to have_received(:log).with("pending -> processing").ordered
+      expect(logger).to have_received(:log).with("processing -> shipped").ordered
+      expect(logger).to have_received(:log).with("shipped -> delivered").ordered
+    end
+  end
+end
+
+# When NOT to use ordering
+RSpec.describe "prefer unordered when possible" do
+  subject(:notifier) { build(:multi_channel_notifier, email:, sms:, push:) }
+
+  let(:email) { spy("email") }
+  let(:sms) { spy("sms") }
+  let(:push) { spy("push") }
+
+  describe "#notify_all" do
+    # BAD: Using ordered when order doesn't matter
+    # it "sends all notifications in order" do
+    #   expect(email).to receive(:send).ordered
+    #   expect(sms).to receive(:send).ordered
+    #   expect(push).to receive(:send).ordered
+    #   notifier.notify_all
+    # end
+
+    # GOOD: Just verify all are called
+    it "sends all notifications" do
+      notifier.notify_all
+
+      expect(email).to have_received(:send)
+      expect(sms).to have_received(:send)
+      expect(push).to have_received(:send)
+    end
+  end
+end
+

data/skills/rspec/examples/mocks/receive_counts.rb

@@ -0,0 +1,181 @@
+# RSpec Mocks: Receive Counts Examples
+# Source: rspec-mocks gem features/setting_constraints/receive_counts.feature
+
+# NOTE: Default expectation is once unless specified
+
+# Exact counts
+RSpec.describe "exact receive counts" do
+  describe "once (default)" do
+    it "expects exactly one call" do
+      dbl = double("collaborator")
+      expect(dbl).to receive(:foo).once
+      dbl.foo
+    end
+  end
+
+  describe "twice" do
+    it "expects exactly two calls" do
+      dbl = double("collaborator")
+      expect(dbl).to receive(:foo).twice
+      dbl.foo
+      dbl.foo
+    end
+  end
+
+  describe "exactly(n).times" do
+    it "expects specific number of calls" do
+      dbl = double("collaborator")
+      expect(dbl).to receive(:foo).exactly(3).times
+      3.times { dbl.foo }
+    end
+
+    it "uses .time for singular" do
+      dbl = double("collaborator")
+      expect(dbl).to receive(:foo).exactly(1).time
+      dbl.foo
+    end
+  end
+end
+
+# Minimum counts
+RSpec.describe "at_least counts" do
+  describe "at_least(:once)" do
+    it "passes with one or more calls" do
+      dbl = double("collaborator")
+      expect(dbl).to receive(:foo).at_least(:once)
+      dbl.foo
+      dbl.foo  # Additional calls are fine
+    end
+  end
+
+  describe "at_least(:twice)" do
+    it "passes with two or more calls" do
+      dbl = double("collaborator")
+      expect(dbl).to receive(:foo).at_least(:twice)
+      dbl.foo
+      dbl.foo
+      dbl.foo  # Additional calls are fine
+    end
+  end
+
+  describe "at_least(n).times" do
+    it "passes with n or more calls" do
+      dbl = double("collaborator")
+      expect(dbl).to receive(:foo).at_least(3).times
+      5.times { dbl.foo }
+    end
+  end
+end
+
+# Maximum counts
+RSpec.describe "at_most counts" do
+  describe "at_most(:once)" do
+    it "passes with zero or one call" do
+      dbl = double("collaborator")
+      expect(dbl).to receive(:foo).at_most(:once)
+      dbl.foo
+    end
+
+    it "also passes with zero calls" do
+      dbl = double("collaborator")
+      expect(dbl).to receive(:foo).at_most(:once)
+      # Not called - still passes
+    end
+  end
+
+  describe "at_most(:twice)" do
+    it "passes with up to two calls" do
+      dbl = double("collaborator")
+      expect(dbl).to receive(:foo).at_most(:twice)
+      dbl.foo
+    end
+  end
+
+  describe "at_most(n).times" do
+    it "passes with n or fewer calls" do
+      dbl = double("collaborator")
+      expect(dbl).to receive(:foo).at_most(3).times
+      2.times { dbl.foo }
+    end
+  end
+end
+
+# have_received with counts
+RSpec.describe "have_received with counts" do
+  it "verifies exact count" do
+    invitation = spy("invitation")
+    invitation.deliver
+    invitation.deliver
+
+    expect(invitation).to have_received(:deliver).twice
+  end
+
+  it "verifies minimum count" do
+    invitation = spy("invitation")
+    5.times { invitation.deliver }
+
+    expect(invitation).to have_received(:deliver).at_least(3).times
+  end
+
+  it "verifies maximum count" do
+    invitation = spy("invitation")
+    2.times { invitation.deliver }
+
+    expect(invitation).to have_received(:deliver).at_most(5).times
+  end
+end
+
+# Practical example
+RSpec.describe BankAccount do
+  subject(:account) { build(:bank_account, logger:) }
+
+  let(:logger) { instance_double("Logger") }
+
+  describe "#transfer" do
+    context "successful transfer" do
+      before do
+        allow(logger).to receive(:info)
+      end
+
+      it "logs exactly twice (start and end)" do
+        expect(logger).to receive(:info).twice
+
+        account.transfer(to: build(:bank_account), amount: 100)
+      end
+    end
+  end
+
+  describe "#batch_transfer" do
+    let(:recipients) { build_list(:bank_account, 5) }
+
+    before do
+      allow(logger).to receive(:info)
+    end
+
+    it "logs at least once per recipient" do
+      expect(logger).to receive(:info).at_least(5).times
+
+      account.batch_transfer(recipients:, amount: 50)
+    end
+  end
+end
+
+# Practical example: rate limiting
+RSpec.describe RateLimitedClient do
+  subject(:client) { build(:rate_limited_client, api:) }
+
+  let(:api) { instance_double("ExternalApi") }
+
+  describe "#fetch_all" do
+    before do
+      allow(api).to receive(:fetch).and_return(data: [])
+    end
+
+    it "makes at most 10 API calls" do
+      expect(api).to receive(:fetch).at_most(10).times
+
+      client.fetch_all(max_pages: 20)
+    end
+  end
+end
+