shoegaze 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ba57e3190d3ef4c36207d28554bb7459ada2e9be71d4e2b8fd02ee26f76bf930
+  data.tar.gz: 0a242d7a0738ee9f2ebd38fb6eff4232bcd541f805f82145611491cccd387a68
+SHA512:
+  metadata.gz: 52ce88092cb6d5fce87931cb38bcc6cbbbb064c91b66029f8d557c4094b0d7fd73f5c073aa9d9f90a1052dd39e57afada10501607a6526e09a2f5d8ff77e3550
+  data.tar.gz: ebe97a469dfc58a2ce1bb23d4f8012b4b5eb2f5a16e92d5f6d4eb61f5143fc8948e08dede4283d7c8060d56f356641b911c0a4cc7f91110010f2c88c70c46721

data/README.md

@@ -0,0 +1,190 @@
+# Shoegaze
+
+[![Build status](https://badge.buildkite.com/0d63e248d5ce1503e1cc1d4e928cc43ff48a9db53463ecdb32.svg)](https://buildkite.com/compose/shoegaze)
+
+Create mocks of modules (especially clients) with easily-defined scenarios (success, invalid, etc) and an optional in-memory persistence layer.
+
+[Documentation](http://www.rubydoc.info/github/compose/shoegaze/master)
+
+## The problem
+
+When unit testing, libraries that constitute dependencies become cumbersome to stub as complexity increases. Most of the time you want to simulate various high-level scenarios that can be produced in your library. Stubbing those high-level scenarios in your tests with low-level tools can be cumbersome and requires a lot of logic about your dependencies to be sprinked throughout your tests. Outright mocking the libraries in various ways (Webmock, VCR, DIY fake classes) can be tricky.
+
+## How Shoegaze solves the problem
+
+When you mock a library using Shoegaze, Shoegaze creates an Rspec double of the library. Using a simple DSL you can specify test `implementations` and their `scenarios` for the mocked library's methods. Swap out your real library implementation for the mock, then drive the high-level behavior in your tests by specifying the scenarios to run. This provides a consistent interface for creating mocks and forces you to mock your library's API, which is the right place to separate the concerns of the library from your tests.
+
+## Mock Twitter Client Example
+
+``` ruby
+class FakeTwitterClient < Shoegaze::Mock
+  # optional. provides in-memory persisted ActiveModel objects so that
+  # your mock can 'remember' its state
+  extend Shoegaze::Datastore
+
+  mock "Twitter::Client"
+
+  # creates both a FakeTwitterClient::Update 'model' and a FactoryBot
+  # factory for the model
+  datastore :Update do
+    id{ BSON::ObjectId.new }
+    date{ Time.new }
+    body{ Faker::Lorem.sentence }
+    location{ [Faker::Address.latitude, Faker::Address.longitude] }
+  end
+
+  implement :update do
+    scenario :success do
+      # optional. you can provide transforms for your 'models' to
+      # represent the data returned by the implementation in various
+      # ways
+      representer do
+        include Representable::JSON
+
+        property :id
+        property :date
+        property :body
+
+        # notice we omit location in this representation
+      end
+
+      # this method will call :as_json on the representer, meaning it
+      # will return a hash. you can also call to_json, for example, to
+      # return stringified JSON instead
+      represent_method :as_json
+
+      datasource do
+        # generate an update and store it in the memory store (you can
+        # grab it with FakerTwitterClient::Update.find(update.id)
+        FactoryBot.create(Update)
+      end
+    end
+
+    scenario :unavailable do
+      datasource do |id|
+        raise Twitter::ConnectionFailed.new(Struct.new(:status).new(status: "504"))
+      end
+    end
+  end
+
+  # you can mock chained methods by nesting implementations, too
+  #
+  # example: ProductMaker.accounts.create({name: "Jack Dorsey"})
+  implement :accounts do
+    scenario :success do
+      datasource do
+        implement :create do
+          # default scenarios can be specified
+          default do |params|
+            FactoryBot.create(Account, params)
+          end
+        end
+      end
+    end
+  end
+end
+
+```
+
+``` ruby
+class ProductMaker
+  class << self
+    def create(name)
+      # ...
+      twitter_client.update("We have a new product: #{product.name}!")
+
+      product
+    end
+
+    private
+
+    def twitter_client
+      @twitter_client ||= Twitter::Client.new
+    end
+  end
+end
+```
+
+``` ruby
+RSpec.configure do |config|
+  config.before :each do
+    # swap out the twitter client for the mock in all tests
+    stub_const("Twitter::Client", FakeTwitterClient.proxy)
+  end
+end
+
+```
+
+```ruby
+describe ProductMaker do
+  describe "#create" do
+    describe "tweeting" do
+      describe "is successful" do
+        before :each do
+          FakeTwitterClient.calling(:update).with(update.body).yields(:success)
+        end
+
+        it "posts a twitter update" do
+          product = ProductMaker.create("some_product")
+
+          update = FakeTwitterClient::Update.find_by_body("We have a new product: #{product.name}!")
+          expect(update).to exist
+        end
+      end
+
+      describe "is unavailable" do
+        before :each do
+          FakeTwitterClient.calling(:update).with(update.body).yields(:unavailable)
+        end
+
+        it "raises a Twitter connection failed error" do
+          expect{ ProductMaker.create("some_product") }.to raise_exception(Twitter::ConnectionFailed)
+        end
+      end
+    end
+  end
+end
+```
+
+# Unit Test Manifesto
+
+## Inject mock dependencies
+
+If a component calls a Twitter client library, create a mock of the
+Twitter client library's API and swap the real implementation for
+the mock.
+
+## Steer injected dependencies at the highest practical level (success, failure, etc)
+
+If you want to test how the component handles Twitter being
+unavailable, create a scenario in the mock implementation of the
+Twitter client library that simulates how the real implementation
+behaves when Twitter is unavailable.
+
+## Test the wiring & the I/O, not the code
+
+Prove that your dependencies were called with the input you
+expect. In a unit test that should be good enough most of the time.
+If those dependency calls would have produced side-effects and it
+matters to your code, your unit may be too complex. Consider
+refactoring. If the side-effects the core intent of the the
+implementation, simulate the side-effects rather than actually
+producing the side-effects.
+
+## Use the dumbest possible test subjects that can prove the I/O works
+
+Much of the time arguments to the API you're testing are not
+inspected in any meaningful way. If all you need to do is prove the
+argument was passed-along correctly, a `double` can do the job
+rather than the real argument type.
+
+## Generate test data randomly and dynamically rather than use fixtures
+
+Use Faker. Generate test data in the most flexible format. Generally
+that's a ruby object with accessors produced by Factory Bot, since
+it can easily be turned into a hash, JSON, or left as-is.
+
+## Test the immediate layer of the component you're testing
+
+If a component calls Net:HTTP, don't serve HTTP, create a mock
+Net:HTTP object and prove it was called with the anticipated I/O.

data/lib/shoegaze.rb

@@ -0,0 +1,15 @@
+module Shoegaze
+end
+
+require 'rspec'
+require 'factory_bot'
+require 'representable'
+require 'multi_json'
+require 'representable/json'
+
+require_relative 'shoegaze/datastore'
+require_relative 'shoegaze/implementation'
+require_relative 'shoegaze/proxy'
+require_relative 'shoegaze/mock'
+require_relative 'shoegaze/scenario'
+require_relative 'shoegaze/model'

data/lib/shoegaze/datastore.rb

@@ -0,0 +1,36 @@
+require_relative "./model"
+
+module Shoegaze
+  module Datastore
+    # Defines both a TopModel-inherited class and a factory in the mock namespace
+    #
+    # @param name [Symbol] upcased name of the datastore to create (example: :User)
+    # @param block [Block] FactoryBot factory implementation expressed in a block
+    # @return [Class] the created datastore class
+    #
+    # example:
+    #
+    #   datastore :User do
+    #     id 123
+    #     name "Karlita"
+    #   end
+    #
+    def datastore(name, &block)
+      klass = create_datastore_class(name)
+
+      FactoryBot.define do
+        factory klass do
+          self.instance_eval(&block)
+        end
+      end
+
+      klass
+    end
+
+    private
+
+    def create_datastore_class(name)
+      self.const_set(name, Class.new(Shoegaze::Model))
+    end
+  end
+end

data/lib/shoegaze/implementation.rb

@@ -0,0 +1,71 @@
+module Shoegaze
+  class Implementation
+    attr_reader :scenarios
+
+    def initialize(mock_class, mock_double, scope, method_name, &block)
+      @_mock_class  = mock_class
+      @_mock_double = mock_double
+      @_scope       = scope
+      @_method_name = method_name
+      @scenarios    = {}
+
+      self.instance_eval(&block)
+    end
+
+    # Defines a named scenario for the implementation
+    #
+    # @param name [Symbol] name of the scenario
+    # @param block [Block] Shoegaze::Scenario implementation expressed in a block
+    # @return [Scenario] the created scenario
+    #
+    # example:
+    #
+    #   scenario :success do
+    #     datasource do
+    #       # ...
+    #     end
+    #   end
+    #
+    def scenario(scenario_name, &block)
+      @scenarios[scenario_name] = Scenario.new(@_method_name, &block)
+    end
+
+    # Defines the default scenario for the implementation
+    #
+    # @param block [Block] Shoegaze::Scenario implementation expressed in a block
+    # @return [Scenario] the created scenario
+    #
+    # example:
+    #
+    #   default do
+    #     datasource do
+    #       # ...
+    #     end
+    #   end
+    #
+    def default(&block)
+      @scenarios[:default] = scenario = Scenario.new(@_method_name, &block)
+
+      scenario_orchestrator = Scenario::Orchestrator.new(@_mock_class, @_mock_double, @_scope, @_method_name)
+
+      # NOTE: we can't use RSpec mock methods here because :default is called outside of a
+      # test scope. so we have added some :default_scenario* methods instead
+      @_mock_double.add_default_scenario(@_method_name, proc do |*args, &datasource_block|
+        scenario_orchestrator.with(*args).execute_scenario(scenario, &datasource_block)
+      end)
+
+      scenario
+    end
+
+    private
+
+    def defining_method
+      case @_scope
+      when :class
+        :define_singleton_method
+      when :instance
+        :define_method
+      end
+    end
+  end
+end

data/lib/shoegaze/mock.rb

@@ -0,0 +1,34 @@
+module Shoegaze
+  # Provides the top-level mocking interface from which our mocks will inherit.
+  class Mock
+    include Proxy::Interface
+
+    class << self
+      # Creates a Shoegaze mock proxy for the provided class name
+      #
+      # @param class_name [String] String name of the constant to mock
+      # @return [Class.new(Shoegaze::Proxy)] The created Shoegaze proxy. Use this as the replacement for your real implementation.
+      #
+      # example:
+      #
+      #   class RealClass
+      #   end
+      #
+      #   class FakeClass < Shoegaze::Mock
+      #     mock "RealClass"
+      #   end
+      #
+      def mock(class_name)
+        @mock_class_double = class_double(class_name)
+        @mock_instance_double = instance_double(class_name)
+
+        extend_double_with_extra_methods(@mock_instance_double)
+        extend_double_with_extra_methods(@mock_class_double)
+
+        @implementations = {class: {}, instance: {}}
+
+        proxy
+      end
+    end
+  end
+end

data/lib/shoegaze/model.rb

@@ -0,0 +1,165 @@
+require "active_model"
+
+class Shoegaze::Model
+  include ActiveModel::Model
+  include ActiveModel::Serializers::JSON
+
+  class UnknownRecordError < StandardError; end;
+
+  class << self
+    attr_writer :store
+
+    def drop_records
+      Shoegaze::Model.store = {}
+    end
+
+    def store
+      if self == Shoegaze::Model
+        @store ||= {}
+      else
+        Shoegaze::Model.store
+      end
+    end
+
+    def ensure_model_namespace(model)
+      # using an array here so that the models appear in the order they were created
+      store[model.class] ||= []
+    end
+
+    def register_model(model)
+      ensure_model_namespace(model)
+      store[model.class] << model
+      model
+    end
+
+    def unregister_model(model)
+      ensure_model_namespace(model)
+      store[model.class].delete(model)
+      model
+    end
+
+    def records_for_class(klass)
+      store[klass] || []
+    end
+
+    def where(options)
+      records_for_class(self).select do |r|
+        options.all? do |k, v|
+          if v.is_a?(Enumerable)
+            v.include?(r.send(k))
+          else
+            r.send(k) == v
+          end
+        end
+      end
+    end
+
+    def find_by(options)
+      where(options).first
+    end
+
+    def all
+      records_for_class(self)
+    end
+
+    def first
+      all[0]
+    end
+
+    def last
+      all[-1]
+    end
+
+    def raw_find(id) #:nodoc:
+      records_for_class(self).find { |r| r.id == id } ||
+        raise(UnknownRecordError, "Couldn't find #{self} with ID=#{id}")
+    end
+
+    def find(id)
+      raw_find(id)
+    end
+    alias :[] :find
+
+    def exists?(id)
+      raw_find(id) != nil
+    end
+
+    def count
+      records_for_class(self).length
+    end
+
+    def select(&block)
+      records_for_class(self).select(&block)
+    end
+
+    def create(attrs = {})
+      instance = self.new(attrs)
+      register_model(instance)
+    end
+
+    def update(id, atts)
+      find(id).update_attributes(atts)
+    end
+
+    def destroy(id)
+      find(id).destroy
+    end
+
+    def find_by_attribute(name, value) #:nodoc:
+      records_for_class(self).find {|r| r.send(name) == value }
+    end
+
+    def method_missing(method_symbol, *args) #:nodoc:
+      method_name = method_symbol.to_s
+
+      if method_name =~ /^find_by_(\w+)!/
+        send("find_by_#{$1}", *args) || raise(UnknownRecord)
+      elsif method_name =~ /^find_by_(\w+)/
+        find_by_attribute($1, args.first)
+      elsif method_name =~ /^find_or_create_by_(\w+)/
+        send("find_by_#{$1}", *args) || create($1 => args.first)
+      elsif method_name =~ /^find_all_by_(\w+)/
+        find_all_by_attribute($1, args.first)
+      else
+        super
+      end
+    end
+  end
+
+  attr_accessor :id
+
+  def initialize(attrs = {})
+    @id = SecureRandom.uuid
+    @__data = OpenStruct.new(attrs)
+  end
+
+  def save
+    Shoegaze::Model.register_model(self)
+  end
+  alias :save! :save
+
+  def destroy
+    Shoegaze::Model.unregister_model(self)
+  end
+  alias :destroy! :destroy
+
+  def update_attributes(attrs)
+    attrs.each do |k, v|
+      send("#{k}=", v)
+    end
+  end
+  alias :update_attributes! :update_attributes
+
+  def reload
+    self.class.find(id) || raise(Shoegaze::Model::UnknownRecordError)
+  end
+
+  def method_missing(method_symbol, *args) #:nodoc:
+    @__data.send(method_symbol, *args)
+  end
+
+  def as_json
+    @__data.to_h.with_indifferent_access
+  end
+  alias :attributes :as_json
+end