rspec-arguments 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: aa45770cbce05f67cb6327da20658a93390aa8fb
+  data.tar.gz: c4cafadad2c0267ef4461eca12c9871c4192dea2
+SHA512:
+  metadata.gz: 150fe729c934b7ad59c3262ed15eb9664f4368476d8ba3a95badb2e691f66ef1c8770b3aef9ce80d8f8b44ea95d82a00fa2afa54e24c3f0cd6f76d5665c432b0
+  data.tar.gz: 9a2214ef9770faa796659fd193137692953be0e7379d85e5045bd2b05a9ef261fef97e63dbe19d073d5411e6ebe571c5cb2be4262296aee30151c94241d9f944

data/.circleci/config.yml

@@ -0,0 +1,14 @@
+# Ruby CircleCI 2.0 configuration file
+# Check https://circleci.com/docs/2.0/language-ruby/ for more details
+version: 2
+jobs:
+  build:
+    docker:
+       - image: circleci/ruby:2.4.3
+    working_directory: ~/repo
+    steps:
+      - checkout
+      - run: bundle install --jobs=4 --retry=3 --path vendor/bundle
+      - run: bundle exec bundle-audit update && bundle exec bundle-audit check
+      - run: bundle exec rubocop
+      - run: bundle exec rspec

data/.gitignore

@@ -0,0 +1,13 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+*.gem

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,7 @@
+inherit_gem:
+  ws-style:
+    - default.yml
+
+AllCops:
+  # Specify your target Ruby version here (only major/minor versions):
+  TargetRubyVersion: 2.4

data/.ruby-version

@@ -0,0 +1 @@
+2.4.3

data/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in rspec-arguments.gemspec
+gemspec

data/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Wealthsimple
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,186 @@
+# RSpec Arguments [![CircleCI](https://circleci.com/gh/wealthsimple/rspec-arguments.svg?style=svg)](https://circleci.com/gh/wealthsimple/rspec-arguments)
+
+Provide arguments to the implicit RSpec `subject`.
+Also, call instance and class methods implicitly.
+
+## Example (TL;DR)
+
+```ruby
+class Thing
+  def initializer(username)
+  end
+  
+  def perform(save:)
+    save
+  end
+end
+
+RSpec.describe Thing do
+  arg(:username, 0) { 'user123' }
+
+  it { is_expected.to be_a(Thing) }
+
+  describe '#save', :method do
+    method_arg(:save) { true }
+    
+    it { is_expected.to eq(save) }
+  end
+end
+```
+
+## Documentation
+
+Out-of-the box, RSpec provides us with an implicit `subject` method that instantiates the described class under test, giving us an instance which we can assert on:
+
+```ruby
+class User
+end
+
+RSpec.describe User do
+  it { is_expected.to be_a(User) }
+do
+```
+
+This is very terse and works great for classes with no initialization parameters.
+
+But we can't use the implicit `subject` when initialization parameters need to be provided.
+
+```ruby
+class User
+  def initialize(name, tag:)
+    # ...
+  end
+end
+
+RSpec.describe User do
+  let(:name) { 'Eva' }
+  let(:tag) { :mobile }
+  
+  subject { described_class.new(name, tag: tag) }
+
+  it { is_expected.to be_a(User) }
+do
+```
+
+Now you have to explicitly declare your `subject`, proving the required parameters to the initializer.
+
+Having parameters in initializers is not uncommon.
+This gem provides new methods that allow you to implicitly provide initializer arguments to the implicit `subject`:
+
+```ruby
+RSpec.describe User do
+  arg(:name, 0) { 'Eva' }
+  arg(:tag) { :mobile }
+  
+  # Translates to:
+  # subject { described_class.new(name, tag: tag) }
+
+  it { is_expected.to be_a(User) }
+end
+```
+
+In this example, `:name` is an initializer positional argument, at position `0`, and `:tag` is the keyword argument with the same symbol.
+
+The interesting part happens when we want to call a method from the class instance under test, a very common use case.
+
+To illustrate this, let's add a new method `save` to the class `User`:
+
+```ruby
+class User
+  def initialize(name, tag:)
+    # ...
+  end
+  
+  def save(validate, touch)
+    # ...
+    return validate
+  end
+end
+```
+
+Traditionally, we could test it as such:
+
+```ruby
+RSpec.describe User do
+  arg(:name, 0) { 'Eva' }
+  arg(:tag) { :mobile }
+
+  it { is_expected.to be_a(User) }
+
+  describe '#save' do
+    let(:validate) { false }
+    let(:touch) { true }
+    
+    subject { described_class.new(name, tag: tag).save(validate, touch) }
+    
+    it { is_expected.to eq(validate) }
+  end
+end
+```
+
+Notice we can't reuse our implicit `subject`, and have to resort to re-initializing our `described_class`, and proving the required arguments to the desired method.
+
+Similarly to initializer methods, this gem introduces methods to facilitate implicit method calls.
+
+```ruby
+RSpec.describe User do
+  arg(:name, 0) { 'Eva' }
+  arg(:tag) { :mobile }
+
+  it { is_expected.to be_a(User) }
+
+  describe '#save', :method do
+    method_arg(:validate, 0) { false }
+    method_arg(:touch, 1) { true }
+    
+    # Translates to:
+    # subject { described_class.new(name, tag: tag).save(validate, touch) }
+    
+    it { is_expected.to eq(validate) }
+  end
+end
+```
+
+Notice that we don't have to repeat ourselves on what method needs to be tested, `save` in this case, as we can infer it from the `describe '#method_name', :method do` context.
+
+Lastly, here's a full example, including methods requiring `&block` arguments, and class method calls:
+
+```ruby
+class User
+  def initialize(name, tag:)
+    # ...
+  end
+  
+  def save(validate, touch)
+    # ...
+    return validate
+  end
+  
+  def self.find_all(&block)
+    # ...
+    block.call
+  end
+end
+```
+
+```ruby
+RSpec.describe User do
+  arg(:name, 0) { 'Eva' }
+  arg(:tag) { :mobile }
+
+  it { is_expected.to be_a(User) }
+
+  describe '#save', :method do
+    method_arg(:validate, 0) { false }
+    method_arg(:touch, 1) { true }
+    
+    it { is_expected.to eq(validate) }
+  end
+  
+  context '.find_all', :class_method do
+    method_arg_block(:block) { proc { 1 } }
+
+    it { is_expected.to eq(1) }
+  end
+end
+```

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/rspec/arguments.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'rspec/support'
+
+RSpec::Support.define_optimized_require_for_rspec(:arguments) { |f| require_relative(f) }
+
+%w[
+  arguments
+  example_group
+  monkey_patcher
+  version
+].each { |file| RSpec::Support.require_rspec_arguments(file) }
+
+RSpec.configure do |c|
+  c.extend RSpec::Arguments::ExampleGroup
+  c.include RSpec::Arguments::MonkeyPatcher
+  c.backtrace_exclusion_patterns << %r(/lib/rspec/arguments)
+end

data/lib/rspec/arguments/arguments.rb

@@ -0,0 +1,119 @@
+module RSpec
+  module Arguments
+    ARG_PREFIX = '__arg_'.freeze
+    METHOD_ARG_PREFIX = '__m_arg_'.freeze
+
+    POSITIONAL_ARG_SUFFIX = 'pos_'.freeze
+    KEYWORD_ARG_SUFFIX = 'kw_'.freeze
+    BLOCK_ARG_SUFFIX = 'blk_'.freeze
+
+    POSITIONAL_ARG = ARG_PREFIX + POSITIONAL_ARG_SUFFIX
+    KEYWORD_ARG = ARG_PREFIX + KEYWORD_ARG_SUFFIX
+    BLOCK_ARG = ARG_PREFIX + BLOCK_ARG_SUFFIX
+
+    METHOD_POSITIONAL_ARG = METHOD_ARG_PREFIX + POSITIONAL_ARG_SUFFIX
+    METHOD_KEYWORD_ARG = METHOD_ARG_PREFIX + KEYWORD_ARG_SUFFIX
+    METHOD_BLOCK_ARG = METHOD_ARG_PREFIX + BLOCK_ARG_SUFFIX
+
+    def process_subject(clazz)
+      class_method = method_under_test(:class_method)
+
+      return call_method_with_args(clazz, class_method.to_sym) if class_method
+
+      process_instance_subject(clazz)
+    end
+
+    def process_instance_subject(clazz)
+      instance = call_initializer_with_args(clazz)
+
+      method = method_under_test(:method)
+
+      return instance unless method
+
+      call_method_with_args(instance, method.to_sym)
+    end
+
+    def call_with_args(list, positional_arg, keyword_arg, block_arg, &proc)
+      positional_args = []
+      keyword_args = {}
+      block_args = nil
+
+      list.sort.each do |name|
+        if name.to_s.start_with?(positional_arg)
+          positional_args << send(name)
+        elsif name.to_s.start_with?(keyword_arg)
+          key = name[keyword_arg.size..-1].to_sym
+          keyword_args[key] = send(name)
+        elsif name.to_s.start_with?(block_arg)
+          block_args = send(name)
+        end
+      end
+
+      # DEBUG CODE
+      # puts "positional_args #{positional_args}"
+      # puts "keyword_args #{keyword_args}"
+      # puts "block_arg #{block_args}"
+
+      positional_args << keyword_args unless keyword_args.empty?
+
+      proc.call(*positional_args, &block_args)
+    end
+
+    # Search for method under testing
+    # inside ExampleGroupHash metadata
+    #
+    # TODO This can likely be improved by using
+    # TODO RSpec filtered extensions.
+    #
+    def method_under_test(key)
+      method_arg = self.class.metadata[key]
+
+      return unless method_arg
+
+      # Return here if you were nice and declared
+      # your method under test using
+      # `method: :method_name`.
+      return method_arg if method_arg.is_a?(Symbol)
+
+      # Otherwise, we have to search for the described
+      # name string somewhere in our ancestor chain.
+
+      # If we are inside a nested example group,
+      # recursively search ascendants' metadata
+      # for the correct method under testing.
+      method_name = search_method_name(self.class.metadata, key)
+      method_name.sub!('#', '')
+      method_name.sub!('.', '')
+      method_name.to_sym
+    end
+
+    def search_method_name(metadata, key)
+      description = metadata[:description]
+      return description unless metadata[:parent_example_group] && metadata[:parent_example_group][key]
+
+      search_method_name(metadata[:parent_example_group], key) if metadata[:parent_example_group]
+    end
+
+    def call_initializer_with_args(receiver)
+      call_with_args(
+        self.class.instance_methods,
+        POSITIONAL_ARG,
+        KEYWORD_ARG,
+        BLOCK_ARG,
+      ) do |*args, &block|
+        receiver.new(*args, &block)
+      end
+    end
+
+    def call_method_with_args(receiver, method_sym)
+      call_with_args(
+        self.class.instance_methods,
+        METHOD_POSITIONAL_ARG,
+        METHOD_KEYWORD_ARG,
+        METHOD_BLOCK_ARG,
+      ) do |*args, &block|
+        receiver.send(method_sym, *args, &block)
+      end
+    end
+  end
+end

data/lib/rspec/arguments/example_group.rb

@@ -0,0 +1,78 @@
+module RSpec
+  module Arguments
+    module ExampleGroup
+      #
+      # @param name [Symbol] binds this parameter to the named method `name`,
+      #   implemented by calling `let(name)`.
+      # @param position [Integer,Symbol] if an Integer is provided, binds this
+      #   argument to a the positional argument at position `position`, 0 indexed.
+      #   If Symbol is provided, binds thi argument to the keyword argument `position`.
+      # @param block [Proc] value to be used for this argument
+      #
+      # @example
+      #
+      #   describe Thing do
+      #     arg(:first, 0) { '0' }
+      #     arg(:second, 1) { '1' }
+      #     arg(:kw_arg) { 3 }
+      #     arg_block(:blk) { proc { 'body' } }
+      #
+      #     # `subject` is now: Thing.new('0', '1', kw_arg: 3, &blk)
+      #
+      #     it { is_expect(subject).to be_a(Thing) }
+      #     it { is_expect(subject.perform).to be_nil }
+      #   end
+      #
+      # TODO support anonymous positional: arg(0) { '0' }
+      #
+      def arg(name, position = nil, &block)
+        _arg(POSITIONAL_ARG, KEYWORD_ARG, name, position, &block)
+      end
+
+      #
+      # Similar to `arg(name, position, &block)`,
+      # but binds this argument as the &block argument
+      # provided to the instance initializer.
+      #
+      def arg_block(name = '', &block)
+        _arg_block(BLOCK_ARG, name, &block)
+      end
+
+      #
+      # Similar to `arg(name, position, &block)`,
+      # but binds this argument to the described method,
+      # instead of described class.
+      #
+      def method_arg(name, position = nil, &block)
+        _arg(METHOD_POSITIONAL_ARG, METHOD_KEYWORD_ARG, name, position, &block)
+      end
+
+      #
+      # Similar to `arg_block(name, &block)`,
+      # but binds this argument to the described method,
+      # instead of described class.
+      #
+      def method_arg_block(name = '', &block)
+        _arg_block(METHOD_BLOCK_ARG, name, &block)
+      end
+
+      private
+
+      def _arg(positional_arg, keyword_arg, name, position = nil, &block)
+        let(name, &block)
+
+        if position.is_a?(Integer)
+          let(positional_arg.+(position.to_s).to_sym) { send(name) }
+        else
+          let(keyword_arg.+((position || name).to_s).to_sym) { send(name) }
+        end
+      end
+
+      def _arg_block(block_arg, name, &block)
+        let(name, &block)
+
+        let(block_arg.+(name.to_s).to_sym) { send(name) }
+      end
+    end
+  end
+end

data/lib/rspec/arguments/monkey_patcher.rb

@@ -0,0 +1,21 @@
+module RSpec
+  module Arguments
+    module MonkeyPatcher
+      include RSpec::Arguments
+
+      #
+      # The only monkey-patching in this gem.
+      #
+      # Mostly untouched, except we call
+      # `process_subject`, instead of simply
+      # instantiating the described_class.
+      #
+      def subject
+        __memoized.fetch_or_store(:subject) do
+          described = described_class || self.class.metadata.fetch(:description_args).first
+          described.is_a?(Class) ? process_subject(described) : described
+        end
+      end
+    end
+  end
+end

data/lib/rspec/arguments/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RSpec
+  module Arguments
+    VERSION = '0.1.0'
+  end
+end

data/rspec-arguments.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'rspec/arguments/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'rspec-arguments'
+  spec.version       = RSpec::Arguments::VERSION
+  spec.authors       = ['Marco Costa']
+  spec.email         = ['marco@marcotc.com']
+  spec.license = "MIT"
+
+  spec.summary       = ' Parameter passing to implicit RSpec subjects.'
+  spec.description   = <<~DESC
+    Allows parameter passing to implicit RSpec subjects.
+    It also adds support for implicit method calls on described_class instances.
+  DESC
+  spec.homepage      = 'https://github.com/wealthsimple/rspec-arguments'
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '>= 2.4'
+
+  spec.add_dependency 'rspec-support', '~> 3'
+
+  spec.add_development_dependency 'bundler', '~> 1.15'
+  spec.add_development_dependency 'bundler-audit'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rspec-its', '~> 1'
+  spec.add_development_dependency 'rubocop', '0.49.1' # Temporarily necessary to avoid breaking ws-style
+  spec.add_development_dependency 'ws-style'
+end

metadata

@@ -0,0 +1,173 @@
+--- !ruby/object:Gem::Specification
+name: rspec-arguments
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Marco Costa
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2018-04-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec-support
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: bundler-audit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-its
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.49.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.49.1
+- !ruby/object:Gem::Dependency
+  name: ws-style
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: |
+  Allows parameter passing to implicit RSpec subjects.
+  It also adds support for implicit method calls on described_class instances.
+email:
+- marco@marcotc.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".circleci/config.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-version"
+- Gemfile
+- LICENSE.md
+- README.md
+- Rakefile
+- lib/rspec/arguments.rb
+- lib/rspec/arguments/arguments.rb
+- lib/rspec/arguments/example_group.rb
+- lib/rspec/arguments/monkey_patcher.rb
+- lib/rspec/arguments/version.rb
+- rspec-arguments.gemspec
+homepage: https://github.com/wealthsimple/rspec-arguments
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.14
+signing_key: 
+specification_version: 4
+summary: Parameter passing to implicit RSpec subjects.
+test_files: []