spec-me-maybe 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e9bcf87280a746990982afabc7a5c7e7c029ffd4
+  data.tar.gz: dc93caf5e9476ce027b63552e2d7bbc22e244fb5
+SHA512:
+  metadata.gz: cb73bc826fed48f8ffef33ba6dc1663f683045575c8097d045a8f8e0f81201877c9051e0a6f399e961b1f1e28379e0c09a64b937080e0910504270d0714281d4
+  data.tar.gz: ce3dd3f882e53b74f4ec31a30cbda2367c6f563416c473b5314d77365ad40b1bee31019b627868a4f0c96cf90d58720834051a4302a8ed2ec3f856e84ab308b1

data/lib/rspec/maybes.rb

@@ -0,0 +1,48 @@
+require 'rspec/expectations'
+require 'rspec/maybes/configuration'
+
+module RSpec
+  # RSpec::Maybes provides a simple, readable API to express possible outcomes
+  # in a code example. To express an potential outcome, wrap an object or block
+  # in `maybe`, call `will` or `will_not` and pass it a matcher object:
+  #
+  #     maybe(order.total).will eq(Money.new(5.55, :USD))
+  #     maybe(list).will include(user)
+  #     maybe(message).will_not match(/foo/)
+  #     maybe { do_something }.will raise_error
+  #
+  # The last form (the block form) is needed to match against ruby constructs
+  # that are not objects, but can only be observed when executing a block
+  # of code. This includes raising errors, throwing symbols, yielding,
+  # and changing values.
+  #
+  # When `maybe(...).will` is invoked with a matcher, it turns around
+  # and calls `matcher.matches?(<object wrapped by maybe>)`.  For example,
+  # in the expression:
+  #
+  #     maybe(order.total).will eq(Money.new(5.55, :USD))
+  #
+  # ...`eq(Money.new(5.55, :USD))` returns a matcher object, and it results
+  # in the equivalent of `eq.matches?(order.total)`. If `matches?` happens to
+  # return `true`, the expectation is met and execution continues. If `false`,
+  # then the spec fails with the message returned by `eq.failure_message`.
+  #
+  # Given the expression:
+  #
+  #     maybe(order.entries).will_not include(entry)
+  #
+  # ... pretty much the same thing happens. `will_not` is simply an alias of
+  # `will`. It's random!
+  #
+  # spec-me-maybe ships with the same standard set of useful matchers as
+  # rspec-expectations does, and writing your own matchers is quite simple.
+  module Maybes
+    # Exception raised when a maybe fails.
+    #
+    # @note We subclass Exception so that in a stub implementation if
+    # the user sets an expectation, it can't be caught in their
+    # code by a bare `rescue`.
+    # @api public
+    MaybeNot = Class.new(::RSpec::Expectations::ExpectationNotMetError)
+  end
+end

data/lib/rspec/maybes/configuration.rb

@@ -0,0 +1,54 @@
+require 'rspec/maybes/syntax'
+
+module RSpec
+  module Core
+    class Configuration
+      def conditionally_disable_expectations_monkey_patching
+        return unless disable_monkey_patching && rspec_expectations_loaded?
+
+        RSpec::Expectations.configuration.syntax = :maybe
+      end
+    end
+  end
+
+  module Expectations
+    class Configuration
+      alias :original_syntax= :syntax=
+      alias :original_syntax  :syntax
+
+      # Configures the supported syntax.
+      # @param [Array<Symbol>, Symbol] values the syntaxes to enable
+      # @example
+      #   RSpec.configure do |rspec|
+      #     rspec.expect_with :rspec do |c|
+      #       c.syntax = :maybe
+      #       # or
+      #       c.syntax = :expect
+      #       # or
+      #       c.syntax = [:maybe, :expect]
+      #     end
+      #   end
+      def syntax=(values)
+        original_syntax = values
+
+        if Array(values).include?(:maybe)
+          Maybes::Syntax.enable_maybe
+        else
+          Maybes::Syntax.disable_maybe
+        end
+      end
+
+      # The list of configured syntaxes.
+      # @return [Array<Symbol>] the list of configured syntaxes.
+      # @example
+      #   unless RSpec::Matchers.configuration.syntax.include?(:maybe)
+      #     raise "this RSpec extension gem requires the spec-me-maybe `:maybe` syntax"
+      #   end
+      def syntax
+        syntaxes = original_syntaxes
+        syntaxes << :maybe if Maybes::Syntax.maybe_enabled?
+        syntaxes
+      end
+    end
+  end
+end

data/lib/rspec/maybes/fail_with.rb

@@ -0,0 +1,21 @@
+module RSpec
+  module Maybes
+    class << self
+      # Raises an RSpec::Maybes::MaybeNot with message.
+      # @param [String] message
+      #
+      # Adds a diff to the failure message when `expected` and `actual` are
+      # both present.
+      def fail_with(message, failure_message_method)
+        unless message
+          raise ArgumentError, "Failure message is nil. Does your matcher define the " \
+                               "appropriate failure_message[_when_negated] method to return a string?"
+        end
+
+        message = "#{message} Maybe next time, though?"
+
+        raise RSpec::Maybes::MaybeNot, message
+      end
+    end
+  end
+end

data/lib/rspec/maybes/handlers.rb

@@ -0,0 +1,55 @@
+require 'rspec/maybes/fail_with'
+
+module RSpec
+  module Maybes
+    # @private
+    module MaybeHelper
+      def self.handle_failure(matcher, message, failure_message_method)
+        message = message.call if message.respond_to?(:call)
+        message ||= matcher.__send__(failure_message_method)
+
+        ::RSpec::Maybes.fail_with message, failure_message_method
+      end
+    end
+
+    class MaybeHandler < RSpec::Expectations::PositiveExpectationHandler
+      def self.handle_matcher(actual, initial_matcher, message = nil, &block)
+        matcher = Expectations::ExpectationHelper.setup(self, initial_matcher, message)
+        matcher.instance_variable_set(:@actual, actual)
+        return matcher
+      end
+
+      def self.passes?(matcher)
+        matcher.on_your_machine? || rand < 0.9
+      end
+    end
+
+    # @private
+    class PositiveMaybeHandler < MaybeHandler
+      def self.handle_matcher(actual, initial_matcher, message = nil, &block)
+        matcher = super
+
+        return ::RSpec::Matchers::BuiltIn::PositiveOperatorMatcher.new(actual) unless initial_matcher
+        passes?(matcher) || MaybeHelper.handle_failure(matcher, message, :failure_message)
+      end
+
+      def self.verb
+        'might'
+      end
+    end
+
+    # @private
+    class NegativeMaybeHandler < MaybeHandler
+      def self.handle_matcher(actual, initial_matcher, message=nil, &block)
+        matcher = super
+
+        return ::RSpec::Matchers::BuiltIn::NegativeOperatorMatcher.new(actual) unless initial_matcher
+        passes?(matcher) || MaybeHelper.handle_failure(matcher, message, :failure_message_when_negated)
+      end
+
+      def self.verb
+        'might not'
+      end
+    end
+  end
+end

data/lib/rspec/maybes/maybe_target.rb

@@ -0,0 +1,119 @@
+require 'rspec/maybes/handlers'
+
+module RSpec
+  module Maybes
+    # Wraps the target of a maybe.
+    #
+    # @example
+    #   maybe(something)       # => MaybeTarget wrapping something
+    #   maybe { do_something } # => MaybeTarget wrapping the block
+    #
+    #   # used with `will`
+    #   maybe(actual).will eq(3)
+    #
+    #   # with `will_not`
+    #   maybe(actual).will_not eq(3)
+    #
+    # @note `MaybeTarget` is not intended to be instantiated
+    #   directly by users. Use `maybe` instead.
+    class MaybeTarget
+      # @private
+      # Used as a sentinel value to be able to tell when the user
+      # did not pass an argument. We can't use `nil` for that because
+      # `nil` is a valid value to pass.
+      UndefinedValue = Module.new
+
+      # @api private
+      def initialize(value)
+        @target = value
+      end
+
+      # @private
+      def self.for(value, block)
+        if UndefinedValue.equal?(value)
+          unless block
+            raise ArgumentError, "You must pass either an argument or a block to `maybe`."
+          end
+          BlockMaybeTarget.new(block)
+        elsif block
+          raise ArgumentError, "You cannot pass both an argument and a block to `maybe`."
+        else
+          new(value)
+        end
+      end
+
+      # Runs the given maybe, passing randomly.
+      # @example
+      #   maybe(value).will eq(5)
+      #   maybe { perform }.will_not raise_error
+      # @param [Matcher]
+      #   matcher
+      # @param [String or Proc] message optional message to display when the expectation fails
+      # @return [Boolean] true if the maybe succeeds (else raises)
+      # @see RSpec::Matchers
+      def will(matcher = nil, message = nil, &block)
+        prevent_operator_matchers(:will) unless matcher
+        RSpec::Maybes::PositiveMaybeHandler.handle_matcher(@target, matcher, message, &block)
+      end
+
+      # Runs the given maybe, failing randomly.
+      # @example
+      #   maybe(value).will_not eq(5)
+      # @param [Matcher]
+      #   matcher
+      # @param [String or Proc] message optional message to display when the maybe fails
+      # @return [Boolean] false if the negative maybe succeeds (else raises)
+      # @see RSpec::Matchers
+      def will_not(matcher = nil, message = nil, &block)
+        prevent_operator_matchers(:will_not) unless matcher
+        RSpec::Maybes::NegativeMaybeHandler.handle_matcher(@target, matcher, message, &block)
+      end
+
+      private
+
+      def prevent_operator_matchers(verb)
+        raise ArgumentError, "The maybe syntax does not support operator matchers, " \
+                             "so you must pass a matcher to `##{verb}`."
+      end
+    end
+
+    # @private
+    # Validates the provided matcher to ensure it supports block
+    # maybes, in order to avoid user confusion when they
+    # use a block thinking the maybe will be on the return
+    # value of the block rather than the block itself.
+    class BlockMaybeTarget < MaybeTarget
+      def will(matcher, message = nil, &block)
+        enforce_block_maybe(matcher)
+        super
+      end
+
+      def will_not(matcher, message = nil, &block)
+        enforce_block_maybe(matcher)
+        super
+      end
+
+      private
+
+      def enforce_block_maybe(matcher)
+        return if supports_block_maybes?(matcher)
+
+        raise MaybeNot, "You must pass an argument rather than " \
+          "a block to use the provided matcher (#{description_of matcher}), or " \
+          "the matcher must implement `supports_block_expectations?`."
+      end
+
+      def supports_block_maybes?(matcher)
+        matcher.supports_block_expectations?
+      rescue NoMethodError
+        false
+      end
+
+      def description_of(matcher)
+        matcher.description
+      rescue NoMethodError
+        matcher.inspect
+      end
+    end
+  end
+end

data/lib/rspec/maybes/syntax.rb

@@ -0,0 +1,74 @@
+require 'rspec/maybes/maybe_target'
+
+module RSpec
+  module Maybes
+    # @api private
+    # Provides methods for enabling and disabling the maybe syntax
+    module Syntax
+      MONKEYPATCHED_CLASSES = [
+        RSpec::Matchers::BuiltIn::BaseMatcher,
+        RSpec::Matchers::BuiltIn::RaiseError,
+        RSpec::Matchers::BuiltIn::ThrowSymbol
+      ]
+
+      module_function
+
+      # @api private
+      # Enables the `maybe` syntax.
+      def enable_maybe(syntax_host = ::RSpec::Matchers)
+        return if maybe_enabled?(syntax_host)
+
+        syntax_host.module_exec do
+          def maybe(value = ::RSpec::Maybes::MaybeTarget::UndefinedValue, &block)
+            ::RSpec::Maybes::MaybeTarget.for(value, block)
+          end
+        end
+
+        MONKEYPATCHED_CLASSES.each do |klass|
+          klass.class_eval do
+            alias old_matches? matches?
+
+            def matches?(actual)
+              @actual = actual
+              @your_machine || old_matches?(actual)
+            end
+
+            def on_my_machine
+              @your_machine = true
+              return self
+            end
+
+            def on_your_machine?() @your_machine end
+          end
+        end
+      end
+
+      # @api private
+      # Disables the `maybe` syntax.
+      def disable_maybe(syntax_host = ::RSpec::Matchers)
+        return unless maybe_enabled?(syntax_host)
+
+        syntax_host.module_exec do
+          undef maybe
+        end
+
+        MONKEYPATCHED_CLASSES.each do |klass|
+          klass.class_eval do
+            undef matches?
+            alias matches? old_matches?
+            undef old_matches?
+
+            undef on_my_machine
+            undef on_your_machine?
+          end
+        end
+      end
+
+      # @api private
+      # Indicates whether or not the `maybe` syntax is enabled.
+      def maybe_enabled?(syntax_host = ::RSpec::Matchers)
+        syntax_host.method_defined?(:maybe)
+      end
+    end
+  end
+end

data/lib/rspec/maybes/version.rb

@@ -0,0 +1,15 @@
+module RSpec
+  module Maybes
+    class Version
+      MAJOR = 1
+      MINOR = 0
+      PATCH = 0
+
+      def self.to_s
+        [MAJOR, MINOR, PATCH].join('.')
+      end
+    end
+
+    VERSION = Version.to_s
+  end
+end

data/lib/spec-me-maybe.rb

@@ -0,0 +1 @@
+require 'rspec/maybes'

data/spec/rspec/maybes_spec.rb

@@ -0,0 +1,25 @@
+require 'spec_helper'
+
+RSpec.describe RSpec::Maybes do
+  it 'might be defined' do
+    maybe { RSpec::Maybes }.will_not raise_error(NameError)
+  end
+
+  it 'might be a module' do
+    maybe(RSpec::Maybes).will be_an_instance_of(Module)
+  end
+
+  it 'really is a module on my machine, though. Yours must be broken.' do
+    maybe(RSpec::Maybes).will be_an_instance_of(Module).on_my_machine
+  end
+
+  context 'after the syntax is disabled' do
+    before { RSpec::Maybes::Syntax.disable_maybe }
+
+    it 'maybe doesnt do anything anymore' do
+      maybe(RSpec::Maybes).will_not even_care_anymore
+    end
+
+    after { RSpec::Maybes::Syntax.enable_maybe }
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,89 @@
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# The generated `.rspec` file contains `--require spec_helper` which will cause this
+# file to always be loaded, without a need to explicitly require it in any files.
+#
+# Given that it is always loaded, you are encouraged to keep this file as
+# light-weight as possible. Requiring heavyweight dependencies from this file
+# will add to the boot time of your test suite on EVERY test run, even for an
+# individual file that may not need all of that loaded. Instead, consider making
+# a separate helper file that requires the additional dependencies and performs
+# the additional setup, and require it from the spec files that actually need it.
+#
+# The `.rspec` file also contains a few flags that are not defaults but that
+# users commonly want.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+
+require 'rspec/maybes'
+
+RSpec.configure do |config|
+  # rspec-expectations config goes here. You can use an alternate
+  # assertion/expectation library such as wrong or the stdlib/minitest
+  # assertions if you prefer.
+  config.expect_with :rspec do |expectations|
+    # This option will default to `true` in RSpec 4. It makes the `description`
+    # and `failure_message` of custom matchers include text for helper methods
+    # defined using `chain`, e.g.:
+    # be_bigger_than(2).and_smaller_than(4).description
+    #   # => "be bigger than 2 and smaller than 4"
+    # ...rather than:
+    #   # => "be bigger than 2"
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+    expectations.syntax = :maybe
+  end
+
+  # rspec-mocks config goes here. You can use an alternate test double
+  # library (such as bogus or mocha) by changing the `mock_with` option here.
+  config.mock_with :rspec do |mocks|
+    # Prevents you from mocking or stubbing a method that does not exist on
+    # a real object. This is generally recommended, and will default to
+    # `true` in RSpec 4.
+    mocks.verify_partial_doubles = true
+  end
+
+  # These two settings work together to allow you to limit a spec run
+  # to individual examples or groups you care about by tagging them with
+  # `:focus` metadata. When nothing is tagged with `:focus`, all examples
+  # get run.
+  config.filter_run :focus
+  config.run_all_when_everything_filtered = true
+
+  # Limits the available syntax to the non-monkey patched syntax that is recommended.
+  # For more details, see:
+  #   - http://myronmars.to/n/dev-blog/2012/06/rspecs-new-expectation-syntax
+  #   - http://teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/
+  #   - http://myronmars.to/n/dev-blog/2014/05/notable-changes-in-rspec-3#new__config_option_to_disable_rspeccore_monkey_patching
+  config.disable_monkey_patching!
+
+  # This setting enables warnings. It's recommended, but in some cases may
+  # be too noisy due to issues in dependencies.
+  config.warnings = true
+
+  # Many RSpec users commonly either run the entire suite or an individual
+  # file, and it's useful to allow more verbose output when running an
+  # individual spec file.
+  if config.files_to_run.one?
+    # Use the documentation formatter for detailed output,
+    # unless a formatter has already been configured
+    # (e.g. via a command-line flag).
+    config.default_formatter = 'doc'
+  end
+
+  # Print the 10 slowest examples and example groups at the
+  # end of the spec run, to help surface which specs are running
+  # particularly slow.
+  config.profile_examples = 10
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = :random
+
+  # Seed global randomization in this process using the `--seed` CLI option.
+  # Setting this allows you to use `--seed` to deterministically reproduce
+  # test failures related to randomization by passing the same `--seed` value
+  # as the one that triggered the failure.
+  Kernel.srand config.seed
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: spec-me-maybe
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- David Celis
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-09-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec-expectations
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+description: |
+  Adds the `maybe` syntax to RSpec:
+       describe Thing do
+        it 'is maybe equal to another thing' do
+          maybe(Thing.new).will eq(another_thing) # Passes sometimes. Maybe.
+        end
+      end
+email:
+- me@davidcel.is
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/rspec/maybes.rb
+- lib/rspec/maybes/configuration.rb
+- lib/rspec/maybes/fail_with.rb
+- lib/rspec/maybes/handlers.rb
+- lib/rspec/maybes/maybe_target.rb
+- lib/rspec/maybes/syntax.rb
+- lib/rspec/maybes/version.rb
+- lib/spec-me-maybe.rb
+- spec/rspec/maybes_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/davidcelis/spec-me-maybe
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Adds the `maybe` syntax to RSpec.
+test_files:
+- spec/rspec/maybes_spec.rb
+- spec/spec_helper.rb
+has_rdoc: