shoegaze 1.1.0

data/lib/shoegaze/proxy.rb

@@ -0,0 +1,24 @@
+require_relative 'proxy/template'
+require_relative 'proxy/interface'
+
+module Shoegaze
+  module Proxy
+    # Creates a Shoegaze mock proxy that delegates all the class method calls to the class
+    # double and all the instance method calls to the instance double.
+    #
+    # @param mock_class_double [RSpec::Mocks::ClassVerifyingDouble] RSpec class double that will receive class method calls
+    # @param mock_instance_double [RSpec::Mocks::InstanceVerifyingDouble] RSpec instance double that will receive instance method calls
+    # @return [Class.new(Shoegaze::Proxy)] The created Shoegaze proxy.
+    #
+    # The goal here is to create a bare-bones anonymous class that delegates all class
+    # methods to the class double and all instance methods to the instance double such that
+    # it implements almost nothing else to avoid conflicts with the actual implementations.
+    def self.new(mock_class_double, mock_instance_double)
+      proxy = Class.new(Template)
+      proxy.class_double    = mock_class_double
+      proxy.instance_double = mock_instance_double
+
+      proxy
+    end
+  end
+end

data/lib/shoegaze/proxy/interface.rb

@@ -0,0 +1,169 @@
+module Shoegaze
+  module Proxy
+    # A common interface module for defining mock implementations, scenarios, and driving
+    # the implementations/scenarios from the test interface.
+    module Interface
+      def self.included(base)
+        base.extend ClassMethods
+        base.class_eval do
+          extend RSpec::Mocks::ExampleMethods
+
+          class << self
+            attr_reader :implementations
+          end
+        end
+      end
+
+      module ClassMethods
+        # Defines a named Shoegaze implementation for a class method.
+        #
+        # @param method_name [Symbol] Symbol name for the class method that is being implemented
+        # @param block [Block] Shoegaze::Implementation expressed in a block
+        # @return [Shoegaze::Implementation] The created implementation.
+        #
+        # example:
+        #
+        #   class FakeThing < Shoegaze::Mock
+        #     mock "RealThing"
+        #
+        #     implement_class_method :find_significant_other do
+        #       default do
+        #         datasource do
+        #           :ohhai
+        #         end
+        #       end
+        #     end
+        #   end
+        #
+        # example usage:
+        #
+        #   $ FakeThing.proxy.find_significant_other
+        #   :ohhai
+        def implement_class_method(method_name, &block)
+          implementations[:class][method_name] = Implementation.new(self, @mock_class_double, :class, method_name, &block)
+        end
+
+        # Defines a named Shoegaze implementation for a instance method.
+        #
+        # @param method_name [Symbol] Symbol name for the instance method that is being implemented
+        # @param block [Block] Shoegaze::Implementation expressed in a block
+        # @return [Shoegaze::Implementation] The created implementation.
+        #
+        # example:
+        #
+        #   class FakeThing < Shoegaze::Mock
+        #     mock "RealThing"
+        #
+        #     implement_instance_method :find_significant_other do
+        #       default do
+        #         datasource do
+        #           :ohhai
+        #         end
+        #       end
+        #     end
+        #   end
+        #
+        # example usage:
+        #
+        #   $ FakeThing.proxy.new.find_significant_other
+        #   :ohhai
+        def implement_instance_method(method_name, &block)
+          implementations[:instance][method_name] = Implementation.new(self, @mock_instance_double, :instance, method_name, &block)
+        end
+
+        alias_method :implement, :implement_instance_method
+
+        # Defines a Scenario::Orchestrator for the method name, which is used to trigger
+        # particular scenarios when the class method is called on the mock proxy.
+        #
+        # @param method_name [Symbol] Symbol name for the class method that is being orchestrated.
+        # @return [Shoegaze::Orchestrator] The created Shoegaze orchestration.
+        #
+        # example:
+        #
+        #   class FakeThing < Shoegaze::Mock
+        #     mock "RealThing"
+        #
+        #     implement_instance_method :find_significant_other do
+        #       scenario :success do
+        #         datasource do
+        #           :ohhai
+        #         end
+        #       end
+        #     end
+        #   end
+        #
+        # example usage:
+        #
+        #   $ FakeThing.proxy.class_call(:find_significant_other).with(:wow).yields(:success)
+        #   $ FakeThing.proxy.find_significant_other(:wow)
+        #   :ohhai
+        #
+        def class_call(method_name)
+          Scenario::Orchestrator.new(self, @mock_class_double, :class, method_name)
+        end
+
+        # Defines a Scenario::Orchestrator for the method name, which is used to trigger
+        # particular scenarios when the instance method is called on the mock proxy.
+        #
+        # @param method_name [Symbol] Symbol name for the instance method that is being orchestrated.
+        # @return [Shoegaze::Orchestrator] The created Shoegaze orchestration.
+        #
+        # example:
+        #
+        #   class FakeThing < Shoegaze::Mock
+        #     mock "RealThing"
+        #
+        #     implement_instance_method :find_significant_other do
+        #       scenario :success do
+        #         datasource do
+        #           :ohhai
+        #         end
+        #       end
+        #     end
+        #   end
+        #
+        # example usage:
+        #
+        #   $ FakeThing.proxy.instance_call(:find_significant_other).with(:wow).yields(:success)
+        #   $ FakeThing.proxy.new.find_significant_other(:wow)
+        #   :ohhai
+        #
+        def instance_call(method_name)
+          Scenario::Orchestrator.new(self, @mock_instance_double, :instance, method_name)
+        end
+
+        alias_method :calling, :instance_call
+
+        # Creates an anonymous class inherited from Shoegaze::Proxy that delegates method
+        # calls to the proxy instance and class doubles. This is the stand-in for your
+        # real implementation.
+        #
+        # @return [Class.new(Shoegaze::Proxy)] A Shoegaze proxy class stand-in for the real implementation.
+        def proxy
+          @proxy ||= Shoegaze::Proxy.new(@mock_class_double, @mock_instance_double)
+        end
+
+        private
+
+        # Rspec doubles don't let us use them outside of tests, which is pretty annoying
+        # because the 'default' scenario method needs to set up a scenario outside of the
+        # testing scope. combine that with how rspec also overrides respond_to? and you
+        # end up with a lovely hack like this
+        def extend_double_with_extra_methods(double)
+          double.instance_eval do
+            @default_scenarios = {}
+
+            def add_default_scenario(method_name, implementation)
+              @default_scenarios[method_name] = implementation
+            end
+
+            def default_scenario(method_name)
+              @default_scenarios[method_name]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shoegaze/proxy/template.rb

@@ -0,0 +1,61 @@
+module Shoegaze
+  module Proxy
+    # Provides the basic 'template' for our anonymous proxy classes whose *only purpose* is to
+    # delegate implementation method calls to the class and instance doubles.
+    class Template
+      class << self
+        attr_accessor :class_double
+        attr_accessor :instance_double
+
+        def method_missing(method, *args, &block)
+          # yeah, we are abusing re-use of rspec doubles
+          class_double.instance_variable_set(:@__expired, false)
+
+          default_scenario = class_double.default_scenario(method)
+
+          if class_double.respond_to?(method)
+            return class_double.send(method, *args, &block)
+          end
+
+          return default_scenario.call(*args, &block) if default_scenario
+
+          begin
+            super
+          rescue NoMethodError
+            raise_no_implementation_error(method, class_double)
+          end
+        end
+
+        private
+
+        def raise_no_implementation_error(method, double)
+          raise Shoegaze::Scenario::Orchestrator::NoImplementationError.new("#{self.name} either has no Shoegaze mock implementation or no scenario has been orchestrated for method :#{method}")
+        end
+      end
+
+      def initialize(*args)
+        # no-op to allow newifying instances
+        # NOTE: due to complexity, mocking of :initialize is not actually supported. drive
+        # your behaviors via other methods
+      end
+
+      def method_missing(method, *args, &block)
+        double = self.class.instance_double
+
+        # yeah, we are abusing re-use of rspec doubles
+        double.instance_variable_set(:@__expired, false)
+
+        default_scenario = double.default_scenario(method)
+
+        return double.send(method, *args, &block) if double.respond_to?(method)
+        return default_scenario.call(*args, &block) if default_scenario
+
+        begin
+          super
+        rescue NoMethodError
+          self.class.raise_no_implementation_error(method, double)
+        end
+      end
+    end
+  end
+end

data/lib/shoegaze/scenario.rb

@@ -0,0 +1,100 @@
+require_relative 'scenario/mock'
+require_relative 'scenario/orchestrator'
+
+module Shoegaze
+  class Scenario
+    def initialize(method_name, &block)
+      @_method_name = method_name
+
+      self.instance_eval(&block)
+    end
+
+    # Specifies the (optional) representer to use when returning the evaluated data
+    # source. If no representer is specified, the data source itself is returned
+    # untouched. You can specify either a stand-alone Representable::Decorator, or provide
+    # an inline one implementation via a block. This is a getter and a setter. Call it with no
+    # arg to _get_ the current representer.
+    #
+    # @param representer_class [Representable::Decorator] (optional) A decorator class that will be used to wrap the result of the data source.
+    # @param representer_block [Block] (optional) An inline Representable::Decorator implementation expressed as a block.
+    # @return [Representable::Decorator] The created or referenced representer.
+    #
+    # example:
+    #
+    #   class FakeThing < Shoegaze::Mock
+    #     mock "RealThing"
+    #
+    #     implement :method do
+    #       scenario :success do
+    #         representer ThingRepresenter
+    #
+    #         # or...
+    #
+    #         representer do
+    #           property :id
+    #           property :name
+    #         end
+    #       end
+    #     end
+    #   end
+    #
+    def representer(representer_class = nil, &block)
+      if representer_class
+        @_representer = representer_class
+      end
+
+      if block_given?
+        @_representer = Class.new(Representable::Decorator).class_eval do
+          self.class_eval(&block)
+          self
+        end
+      end
+
+      @_representer
+    end
+
+    # Specifies the method to call on the scenario's representer. Common examples as
+    # :as_json or :to_json. You can omit this and, if a representer is specified, the
+    # representer itself will be returned. This is a getter and a setter. Call it with no
+    # arg to _get_ the current representation_method.
+    #
+    # @param representation_method [Symbol] The method to call on the Representable::Decorator, the result of which is ultimately returned out of the implementation of this scenario.
+    # @return [Symbol] The representation method
+    #
+    # example:
+    #
+    #   class FakeThing < Shoegaze::Mock
+    #     mock "RealThing"
+    #
+    #     implement :method do
+    #       scenario :success do
+    #         representer ThingRepresenter
+    #         represent_method :as_json
+    #       end
+    #     end
+    #   end
+    #
+    def represent_method(representation_method = nil)
+      if representation_method
+        @_representation_method = representation_method
+      end
+
+      @_representation_method
+    end
+
+    # Specifies the datasource (actual implementation code) for the implementation scenario. This is ruby code in a block. The result of this block is fed into the scenario representer, if one is specified, or returned untouched if the scenario is not represented.
+    #
+    # @param block [Block] The implementation for the scenario's data source expressed as a block.
+    # @return [Block] The block
+    def datasource(&block)
+      @_datasource = block
+    end
+
+    # This just returns the datasource block.
+    #
+    # @return [Block] The current data source block
+    def to_proc
+      @_datasource
+    end
+  end
+end

data/lib/shoegaze/scenario/mock.rb

@@ -0,0 +1,52 @@
+module Shoegaze
+  class Scenario
+    class Mock
+      include Proxy::Interface
+
+      class << self
+        # This is a mocking interface for all mocking contexts except for the top-level
+        # mocking context. in other words, when you're chaining implementation calls, this
+        # interface will be used beyond the top-level context. It behaves almost exactly
+        # like Shoegaze::Mock.
+        #
+        # example:
+        #
+        #   class Fake < Shoegaze::Mock
+        #     mock "Real"
+        #
+        #     implement :accounts do # top-level Shoegaze::Mock interface
+        #       scenario :success do
+        #         datasource do
+        #           implement :create do # Shoegaze::ScenarioMock interface from now on
+        #             default do
+        #               datasource do
+        #                 implement :even_more_things # yup, still Shoegaze::ScenarioMock...
+        #                   default do
+        #                     datasource do |params|
+        #                       OkayFinally.new(params)
+        #                     end
+        #                   end
+        #                 end
+        #               end
+        #             end
+        #           end
+        #         end
+        #       end
+        #     end
+        #   end
+        def mock(_nothing = nil)
+          @_mock_class = double
+          @mock_class_double = double
+          @mock_instance_double = double
+
+          extend_double_with_extra_methods(@mock_instance_double)
+          extend_double_with_extra_methods(@mock_class_double)
+
+          @implementations = {class: {}, instance: {}}
+
+          proxy
+        end
+      end
+    end
+  end
+end

data/lib/shoegaze/scenario/orchestrator.rb

@@ -0,0 +1,167 @@
+module Shoegaze
+  class Scenario
+    class Orchestrator
+      include RSpec::Mocks::ExampleMethods
+
+      class NoImplementationError < StandardError; end
+
+      def initialize(mock_class, mock_double, scope, method_name)
+        @_scope       = scope
+        @_mock_class  = mock_class
+        @_mock_double = mock_double
+        @_method_name = method_name
+      end
+
+      # Specifies the arguments to which this scenario will be scoped.
+      #
+      # @param args [*Arguments] any number of free-form arguments
+      # @return [Shoegaze::Scenario::Orchestrator] returns the orchestrator `self` for chainability
+      #
+      # example:
+      #
+      #   FakeThing.proxy.calling(:find_cows).with(123, 456).yields(:success)
+      #
+      def with(*args)
+        @_args = args
+        self
+      end
+
+      # Specifies the scenario for the implementation that will be triggered when this method is
+      # called with the specified scope (arguments, etc).
+      #
+      # @param scenario_name [Symbol] The name of the scenario to trigger.
+      # @return [Shoegaze::Scenario::Orchestrator] returns the orchestrator `self` for chainability
+      #
+      # example:
+      #
+      #   FakeThing.proxy.calling(:find_cows).with(123, 456).yields(:success)
+      #
+      def yields(scenario_name)
+        implementation = @_mock_class.implementations[@_scope][@_method_name]
+
+        scenario = begin
+                     implementation.scenarios[scenario_name]
+                   rescue NoMethodError
+                   end
+
+        unless scenario
+          raise NoImplementationError.new(
+                  "#{@_mock_class} has no implementation for scenario :#{scenario_name} of the #{@_scope} method :#{@_method_name}."
+                )
+        end
+
+        # yeah, we are abusing re-use of rspec doubles
+        @_mock_double.instance_variable_set(:@__expired, false)
+
+        args = @_args
+
+        if @_args.nil?
+          args = [anything]
+
+          # also allow no args if no args are specified
+          send(:allow, @_mock_double).to receive(@_method_name) do
+            execute_scenario(scenario)
+          end
+        end
+
+        send(
+          :allow,
+          @_mock_double
+        ).to receive(@_method_name).with(*args) do |*_args, &datasource_block|
+          execute_scenario(scenario, &datasource_block)
+        end
+
+        self
+      end
+
+      # Executes the specified implementation scenario.
+      #
+      # @param scenario_name [Symbol] The name of the scenario to run.
+      # @yield [datasource_result] yields the result of the provided datasource block
+      # @return [Misc] returns the represented result of the scenario
+      #
+      def execute_scenario(scenario, &datasource_block)
+        # we do this crazy dance because we want scenario.to_proc to be run in the context
+        # of self (an orchestrator) in order to enable nesting, but we also want to be
+        # able to pass in a block. instance_exec would solve the context problem but
+        # doesn't enable the passing of the block while simply calling the method would
+        # allow passing the block but not changing the context.
+        self.define_singleton_method :bound_proc, &scenario.to_proc
+        data = self.bound_proc(*@_args, &datasource_block)
+
+        represent(data, scenario)
+      end
+
+      # Specifies a sub-implementation proxy interface used for recursive chaining of
+      # implementations. Think of it as a recursable Shoegaze::Mock.implement_class_method.
+      # All sub-implementations are internally implemented as class methods for simplicity.
+      #
+      # @param method_name [Symbol] The name of the nested method to implement
+      # @return [Class.new(Shoegaze::Proxy)] A Shoegaze proxy for next layer of the implementation.
+      #
+      # example:
+      #
+      #   class Fake < Shoegaze::Mock
+      #     mock "Real"
+      #
+      #     implement :accounts do # top-level Shoegaze::Mock interface
+      #       scenario :success do
+      #         datasource do
+      #           implement :create do # _this method_
+      #             default do
+      #               datasource do
+      #                 implement :even_more_things # _this method again_
+      #                   default do
+      #                     datasource do |params|
+      #                       :popcorn
+      #                     end
+      #                   end
+      #                 end
+      #               end
+      #             end
+      #           end
+      #         end
+      #       end
+      #     end
+      #   end
+      #
+      #   $ Fake.accounts.create.even_more_things
+      #   :popcorn
+      #
+      def implement(method_name, &block)
+        proxy_interface.implement_class_method(method_name, &block)
+        proxy_interface.proxy
+      end
+
+      private
+
+      def allowance
+        case @_scope
+        when :instance
+          :allow_any_instance_of
+        when :class
+          :allow
+        end
+      end
+
+      def represent(data, scenario)
+        return data unless scenario.representer
+
+        representer = scenario.representer.new(data)
+        return representer unless scenario.represent_method
+
+        representer.send(scenario.represent_method)
+      end
+
+      # creates a new mocking context for the nested method call
+      # see Shoegaze::Scenario::Mock
+      def proxy_interface
+        return @_proxy_interface if @_proxy_interface
+
+        @_proxy_interface = Class.new(Scenario::Mock)
+        @_proxy_interface.mock
+        @_proxy_interface
+      end
+    end
+  end
+end