clarion-given 1.0.0

data/lib/given/fuzzy_number.rb

@@ -0,0 +1,68 @@
+
+module Given
+  module Fuzzy
+    class FuzzyNumber
+
+      DEFAULT_EPSILON = 10 * Float::EPSILON
+
+      attr_reader :exact_value, :delta_amount
+
+      def initialize(exact_value)
+        @exact_value = exact_value
+        @delta_amount = exact_value * DEFAULT_EPSILON
+      end
+
+      def exactly_equals?(other)
+        other.is_a?(self.class) &&
+          exact_value == other.exact_value &&
+          delta_amount == other.delta_amount
+      end
+
+      # Low limit of the fuzzy number.
+      def low_limit
+        exact_value - delta_amount
+      end
+
+      # High limit of the fuzzy number.
+      def high_limit
+        exact_value + delta_amount
+      end
+
+      # True if the other number is in range of the fuzzy number.
+      def ==(other)
+        (other - exact_value).abs <= delta_amount
+      end
+
+      def to_s
+        "<Approximately #{exact_value} +/- #{delta_amount}>"
+      end
+
+      # Set the delta for a fuzzy number.
+      def delta(delta)
+        @delta_amount = delta.abs
+        self
+      end
+
+      # Specifying a percentage of the exact number to be used in
+      # setting the delta.
+      def percent(percentage)
+        delta(exact_value * (percentage / 100.0))
+      end
+
+      # Specifying the number of epsilons to be used in setting the
+      # delta.
+      def epsilon(neps)
+        delta(exact_value * (neps * Float::EPSILON))
+      end
+    end
+
+    # Create an approximate number that is approximately equal to
+    # the given number, plus or minus the delta value. If no
+    # explicit delta is given, then the default delta that is about
+    # 10X the size of the smallest possible change in the given
+    # number will be used.
+    def about(*args)
+      FuzzyNumber.new(*args)
+    end
+  end
+end

data/lib/given/fuzzy_shortcuts.rb

@@ -0,0 +1 @@
+require 'given/ext/numeric'

data/lib/given/line_extractor.rb

@@ -0,0 +1,57 @@
+require 'ripper'
+require 'sorcerer'
+require 'given/file_cache'
+
+module Given
+  class LineExtractor
+    def initialize(file_cache=nil)
+      @files = file_cache || FileCache.new
+    end
+
+    def line(file_name, line)
+      lines = @files.get(file_name)
+      extract_lines_from(lines, line-1)
+    end
+
+    def to_s
+      "<LineExtractor>"
+    end
+
+    private
+
+    def extract_lines_from(lines, line_index)
+      result = lines[line_index]
+      while result && incomplete?(result)
+        line_index += 1
+        result << lines[line_index]
+      end
+      result
+    end
+
+    def incomplete?(string)
+      builder = Ripper::SexpBuilder.new(string)
+      sexp = builder.parse
+      if builder.error?
+        # Modern Ripper recovers from syntax errors by dropping
+        # statements. A truncated source line parses to a program with
+        # no sourceable content; anything else is left alone.
+        extractable_source(sexp).empty?
+      else
+        ! complete_sexp?(sexp)
+      end
+    end
+
+    def extractable_source(sexp)
+      Sorcerer.source(sexp)
+    rescue Sorcerer::Resource::NotSexpError
+      ""
+    end
+
+    def complete_sexp?(sexp)
+      Sorcerer.source(sexp)
+      true
+    rescue Sorcerer::Resource::NotSexpError => ex
+      false
+    end
+  end
+end

data/lib/given/minitest/all.rb

@@ -0,0 +1,12 @@
+require 'minitest/spec'
+require 'given'
+
+require 'given/minitest/before_extension'
+require 'given/minitest/context_extension'
+require 'given/minitest/failure_must_raise'
+require 'given/minitest/framework'
+require 'given/minitest/configure'
+
+unless Minitest::Spec.instance_methods.include?(:assertions)
+  require 'given/minitest/new_assertions'
+end

data/lib/given/minitest/before_extension.rb

@@ -0,0 +1,36 @@
+
+# The before blocks defined in Minitest are inadequate for our use.
+# This before_extension file allows us to use real before blocks.
+
+module Minitest
+  class Spec
+
+    # Redefine setup to trigger before chains
+    alias original_setup_without_given setup
+    def setup
+      original_setup_without_given
+      _gvn_establish_befores
+    end
+
+    # Establish the before blocks
+    def _gvn_establish_befores
+      return if defined?(@_gvn_ran_befores) && @_gvn_ran_befores
+      @_gvn_ran_befores = true
+      _gvn_contexts.each do |context|
+        context._Gvn_before_blocks.each do |before_block|
+          instance_eval(&before_block)
+        end
+      end
+    end
+
+    # Lazy accessor for Given's before blocks
+    def self._Gvn_before_blocks
+      @_Gvn_before_blocks ||= []
+    end
+
+    # Define a Given style before block
+    def self._Gvn_before(&block)
+      _Gvn_before_blocks << block
+    end
+  end
+end

data/lib/given/minitest/configure.rb

@@ -0,0 +1,7 @@
+
+# Configure Minitest to use the Given extensions.
+
+Minitest::Spec.send(:extend,  Given::ClassExtensions)
+Minitest::Spec.send(:include, Given::FailureMethod)
+Minitest::Spec.send(:include, Given::InstanceExtensions)
+Given.use_natural_assertions if Given::NATURAL_ASSERTIONS_SUPPORTED

data/lib/given/minitest/context_extension.rb

@@ -0,0 +1,3 @@
+
+# Minitest Specs don't provide a context.
+alias :context :describe

data/lib/given/minitest/failure_must_raise.rb

@@ -0,0 +1,13 @@
+module Given
+
+  class Failure
+    # Minitest expectation method. Since Failure inherits from
+    # BasicObject, we need to add this method explicitly.
+    def must_raise(*args)
+      ::Minitest::Spec.current.assert_raises(*args) do
+        die
+      end
+    end
+  end
+
+end

data/lib/given/minitest/framework.rb

@@ -0,0 +1,37 @@
+
+module Minitest
+  module Given
+
+    # Framework adapter for Minitest/Given
+    #
+    class Framework
+      def start_evaluation
+        @starting_assertion_count = example.assertions
+      end
+
+      def explicit_assertions?
+        example.assertions > @starting_assertion_count
+      end
+
+      def count_assertion
+        example.assertions += 1
+      end
+
+      def fail_with(*args)
+        raise Minitest::Assertion, args.join(" ")
+      end
+
+      def pending_error
+        Minitest::Skip
+      end
+
+      private
+
+      def example
+        Minitest::Spec.current
+      end
+    end
+  end
+end
+
+Given.framework = Minitest::Given::Framework.new

data/lib/given/minitest/new_assertions.rb

@@ -0,0 +1,22 @@
+
+module Minitest
+  module Given
+
+    # If this version of Minitest does not support the #assertions and
+    # #assertions= methods, define a working version of them.
+    #
+    # This allows Minitest/Given to work with Minitest 4.x.
+    #
+    module NewAssertions
+      def assertions
+        _assertions
+      end
+
+      def assertions=(new_value)
+        self._assertions = new_value
+      end
+    end
+  end
+end
+
+Minitest::Spec.__send__(:include, Minitest::Given::NewAssertions)

data/lib/given/module_methods.rb

@@ -0,0 +1,83 @@
+
+module Given
+  # Does this platform support natural assertions?
+  RBX_IN_USE = (defined?(RUBY_ENGINE) && RUBY_ENGINE == 'rbx')
+  JRUBY_IN_USE = defined?(JRUBY_VERSION)
+  OLD_JRUBY_IN_USE = JRUBY_IN_USE && (JRUBY_VERSION < '1.7.5')
+
+  NATURAL_ASSERTIONS_SUPPORTED = ! (OLD_JRUBY_IN_USE || RBX_IN_USE)
+
+  def self.framework
+    @_gvn_framework
+  end
+
+  def self.framework=(framework)
+    @_gvn_framework = framework
+  end
+
+  def self.source_caching_disabled
+    @_gvn_source_caching_disabled
+  end
+
+  def self.source_caching_disabled=(value)
+    @_gvn_source_caching_disabled = value
+  end
+
+  # Globally enable/disable natural assertions.
+  #
+  # There is a similar function in Extensions that works at a
+  # describe or context scope.
+  def self.use_natural_assertions(enabled=true)
+    ok_to_use_natural_assertions(enabled)
+    @natural_assertions_enabled = enabled
+  end
+
+  # TRUE if natural assertions are globally enabled?
+  def self.natural_assertions_enabled?
+    @natural_assertions_enabled
+  end
+
+  # Is is OK to use natural assertions on this platform.
+  #
+  # An error is raised if the the platform does not support natural
+  # assertions and the flag is attempting to enable them.
+  def self.ok_to_use_natural_assertions(enabled)
+    if enabled && ! NATURAL_ASSERTIONS_SUPPORTED
+      fail ArgumentError, "Natural Assertions are disabled for JRuby"
+    end
+  end
+
+  # Return file and line number where the block is defined.
+  def self.location_of(block)
+    block.source_location
+  end
+
+  # Methods forwarded to the framework object.
+
+  # Fail an example with the given messages.
+  def self.fail_with(*args)
+    Given.framework.fail_with(*args)
+  end
+
+  # Mark the start of a Then assertion evaluation.
+  def self.start_evaluation(*args)
+    Given.framework.start_evaluation(*args)
+  end
+
+  # Were there any explicit framework assertions made during the
+  # execution of the Then block?
+  def self.explicit_assertions?(*args)
+    Given.framework.explicit_assertions?(*args)
+  end
+
+  # Increment the number of assertions made in the framework.
+  def self.count_assertion(*args)
+    Given.framework.count_assertion(*args)
+  end
+
+  # Error object used by the current framework to indicate a pending
+  # example.
+  def self.pending_error
+    Given.framework.pending_error
+  end
+end

data/lib/given/natural_assertion.rb

@@ -0,0 +1,191 @@
+require 'given/module_methods'
+require 'given/evaluator'
+require 'given/binary_operation'
+
+if Given::NATURAL_ASSERTIONS_SUPPORTED
+  require 'ripper'
+  require 'sorcerer'
+end
+
+module Given
+
+  InvalidThenError = Class.new(StandardError)
+
+  class NaturalAssertion
+
+    def initialize(clause_type, block, example, line_extractor)
+      @clause_type = clause_type
+      @evaluator = Evaluator.new(example, block)
+      @line_extractor = line_extractor
+      set_file_and_line(block)
+    end
+
+    VOID_SEXP = [:void_stmt]
+
+    def has_content?
+      assertion_sexp != VOID_SEXP
+    end
+
+    def message
+      @output = "#{@clause_type} expression failed at #{source_line}\n"
+      @output << "Failing expression: #{source.strip}\n" if @clause_type != "Then"
+      explain_failure
+      display_pairs(expression_value_pairs)
+      @output << "\n"
+      @output
+    end
+
+    private
+
+    def explain_failure
+      binary = BinaryOperation.parse(assertion_sexp)
+      if binary && binary.explain
+        @output << explain_expected("expected", binary.left, binary.explain, binary.right)
+      end
+    end
+
+    def explain_expected(expect_msg, expect_sexp, got_msg, got_sexp)
+      width = [expect_msg.size, got_msg.size].max
+      sprintf("%#{width}s: %s\n%#{width}s: %s\n",
+        expect_msg, eval_sexp(expect_sexp),
+        got_msg, eval_sexp(got_sexp))
+    end
+
+    def expression_value_pairs
+      assertion_subexpressions.map { |exp|
+        [exp, @evaluator.eval_string(exp)]
+      }
+    end
+
+    def assertion_subexpressions
+      Sorcerer.subexpressions(assertion_sexp).reverse.uniq.reverse
+    end
+
+    def assertion_sexp
+      @assertion_sexp ||= extract_test_expression(Ripper::SexpBuilder.new(source).parse)
+    end
+
+    def source
+      @source ||= @line_extractor.line(@code_file, @code_line)
+    end
+
+    def set_file_and_line(block)
+      @code_file, @code_line = @evaluator.location
+      @code_line = @code_line.to_i
+    end
+
+    def extract_test_expression(sexp)
+      brace_block = extract_brace_block(sexp)
+      extract_first_statement(brace_block)
+    end
+
+    def extract_brace_block(sexp)
+      unless then_block?(sexp)
+        source = Sorcerer.source(sexp)
+        fail InvalidThenError, "Unexpected code at #{source_line}\n#{source}"
+      end
+      sexp[1][2][2]
+    end
+
+    def then_block?(sexp)
+      program_sexp?(sexp) && method_with_block?(sexp) && has_block_sexp?(sexp)
+    end
+
+    def program_sexp?(sexp)
+      delve(sexp,0) == :program
+    end
+
+    def method_with_block?(sexp)
+      delve(sexp,1,0) == :stmts_add &&
+        delve(sexp,1,2,0) == :method_add_block
+    end
+
+    def has_block_sexp?(sexp)
+      delve(sexp,1,2,2,0) == :brace_block || delve(sexp,1,2,2,0) == :do_block
+    end
+
+    def extract_first_statement(block_sexp)
+      if contains_multiple_statements?(block_sexp)
+        source = Sorcerer.source(block_sexp)
+        fail InvalidThenError, "Multiple statements in Then block at #{source_line}\n#{source}"
+      end
+      extract_statement_from_block(block_sexp)
+    end
+
+    def contains_multiple_statements?(block_sexp)
+      stmts = block_statements(block_sexp)
+      !(delve(stmts,0) == :stmts_add &&
+        delve(stmts,1,0) == :stmts_new)
+    end
+
+    def extract_statement_from_block(block_sexp)
+      delve(block_statements(block_sexp),2)
+    end
+
+    # The statements of a block body. Modern Ripper wraps do_block
+    # bodies in a :bodystmt node; brace_block bodies (and older
+    # Ripper) expose the :stmts_add node directly.
+    def block_statements(block_sexp)
+      body = delve(block_sexp,2)
+      if body.is_a?(Array) && body[0] == :bodystmt
+        body[1]
+      else
+        body
+      end
+    end
+
+    # Safely dive into an array with a list of indicies. Return nil
+    # if the element doesn't exist, or if the intermediate result is
+    # not indexable.
+    def delve(ary, *indicies)
+      result = ary
+      while !indicies.empty? && result
+        return nil unless result.respond_to?(:[])
+        i = indicies.shift
+        result = result[i]
+      end
+      result
+    end
+
+    def eval_sexp(sexp)
+      expr_string = Sorcerer.source(sexp)
+      @evaluator.eval_string(expr_string)
+    end
+
+    WRAP_WIDTH = 20
+
+    def display_pairs(pairs)
+      width = suggest_width(pairs) + 4
+      pairs.each do |x, v|
+        v = adjust_indentation(v)
+        fmt = multi_line?(v) ?
+        "%-#{width}s\n#{' '*width} <- %s\n" :
+          "%-#{width}s <- %s\n"
+        @output << sprintf(fmt, v, x)
+      end
+    end
+
+    def adjust_indentation(string)
+      string.to_s.gsub(/^/, '  ')
+    end
+
+    def multi_line?(string)
+      (string.size > WRAP_WIDTH) || (string =~ /\n/)
+    end
+
+    def suggest_width(pairs)
+      pairs.map { |x,v|
+        max_line_length(v)
+      }.select { |n| n < WRAP_WIDTH }.max || 10
+    end
+
+    def max_line_length(string)
+      string.to_s.split(/\n/).map { |s| s.size }.max
+    end
+
+    def source_line
+      "#{@code_file}:#{@code_line}"
+    end
+  end
+
+end

data/lib/given/rspec/all.rb

@@ -0,0 +1,29 @@
+require 'rspec'
+require 'given'
+
+module RSpec
+  module Given
+  end
+end
+
+if Given::NATURAL_ASSERTIONS_SUPPORTED
+  require 'given/rspec/monkey'
+  raise "Unsupported version of RSpec (#{RSpec::Version::STRING}), unable to detect assertions" unless RSpec::Given::MONKEY
+end
+
+require 'given/rspec/have_failed'
+require 'given/rspec/before_extensions'
+require 'given/rspec/framework'
+require 'given/rspec/use_natural_assertions'
+require 'given/rspec/configure'
+
+module Given
+  def self.using_old_rspec?
+    defined?(Spec) &&
+      defined?(Spec::VERSION) &&
+      defined?(Spec::VERSION::SUMMARY) &&
+      Spec::VERSION::SUMMARY =~ /^rspec +1\./
+  end
+end
+
+raise "Unsupported version of RSpec" if Given.using_old_rspec?

data/lib/given/rspec/before_extensions.rb

@@ -0,0 +1,15 @@
+
+module RSpec
+  module Given
+    module BeforeHack
+
+      # Some frameworks don't support a robust before block, so we
+      # always use this one. In RSpec, we just delegate to the real
+      # before block handler.
+      def _Gvn_before(*args, &block)
+        before(*args, &block)
+      end
+
+    end
+  end
+end

data/lib/given/rspec/configure.rb

@@ -0,0 +1,20 @@
+require 'rspec'
+require 'rspec/given' unless defined?(RSpec::Given)
+
+RSpec.configure do |c|
+  c.extend(Given::ClassExtensions)
+  c.include(Given::InstanceExtensions)
+  c.include(Given::Fuzzy)
+  c.include(Given::FailureMethod)
+  c.extend(RSpec::Given::BeforeHack)
+  c.include(RSpec::Given::HaveFailed)
+
+  if c.respond_to?(:backtrace_exclusion_patterns)
+    c.backtrace_exclusion_patterns << /lib\/rspec\/given/
+  else
+    c.backtrace_clean_patterns << /lib\/rspec\/given/
+  end
+
+  Given.use_natural_assertions if Given::NATURAL_ASSERTIONS_SUPPORTED
+  Given.source_caching_disabled = false
+end

data/lib/given/rspec/framework.rb

@@ -0,0 +1,46 @@
+
+module RSpec
+  module Given
+
+    # Framework interface for RSpec/Given.
+    #
+    class Framework
+      def start_evaluation
+        @matcher_called = false
+      end
+
+      def explicit_assertions?
+        @matcher_called
+      end
+
+      def count_assertion
+      end
+
+      def explicitly_asserted
+        @matcher_called = true
+      end
+
+      def fail_with(*args)
+        ::RSpec::Expectations.fail_with(*args)
+      end
+
+      # Use the RSpec pending error if we can find it.
+      if defined?(RSpec::Core::Pending::PendingDeclaredInExample)
+        def pending_error
+          RSpec::Core::Pending::PendingDeclaredInExample
+        end
+      elsif defined?(RSpec::Core::Pending::SkipDeclaredInExample)
+        def pending_error
+          RSpec::Core::Pending::SkipDeclaredInExample
+        end
+      else
+        PendingError = Class.new(StandardError)
+        def pending_error
+          PendingError
+        end
+      end
+    end
+  end
+end
+
+Given.framework = RSpec::Given::Framework.new

data/lib/given/rspec/have_failed.rb

@@ -0,0 +1,37 @@
+
+# The implementation of RaiseError changed between RSpec 2.11 and 2.12.
+if RSpec::Matchers::BuiltIn::RaiseError.instance_methods.include?(:does_not_match?)
+  require 'given/rspec/have_failed_212.rb'
+else
+  require 'given/rspec/have_failed_pre212.rb'
+end
+
+module RSpec
+  module Given
+    module HaveFailed
+
+      # Specializes the RaiseError matcher to handle
+      # Failure/non-failure objects.
+
+      # Simular to raise_error(...), but reads a bit better when using
+      # a failure result from a when clause.
+      #
+      # Typical Usage:
+      #
+      #    When(:result) { fail "OUCH" }
+      #    Then { expect(result).to have_failed(StandardError, /OUCH/) }
+      #
+      #    When(:result) { good_code }
+      #    Then { expect(result).to_not have_failed }
+      #
+      # :call-seq:
+      #    have_failed([exception_class [, message_pattern]])
+      #    have_failed([exception_class [, message_pattern]]) { |ex| ... }
+      #
+      def have_failed(error=Exception, message=nil, &block)
+        HaveFailedMatcher.new(error, message, &block)
+      end
+      alias have_raised have_failed
+    end
+  end
+end