opal-rspec 0.4.3 → 0.5.0.beta1

data/{vendor_lib → rspec-core/lib}/rspec/core/memoized_helpers.rb

@@ -1,10 +1,16 @@
 module RSpec
   module Core
+    # This module is included in {ExampleGroup}, making the methods
+    # available to be called from within example blocks.
+    #
+    # @see ClassMethods
     module MemoizedHelpers
       # @note `subject` was contributed by Joe Ferris to support the one-liner
       #   syntax embraced by shoulda matchers:
       #
       #       describe Widget do
+      #         it { is_expected.to validate_presence_of(:name) }
+      #         # or
       #         it { should validate_presence_of(:name) }
       #       end
       #
@@ -31,23 +37,25 @@ module RSpec
       #     end
       #   end
       #
-      #   # one-liner syntax - should is invoked on subject
+      #   # one-liner syntax - expectation is set on the subject
       #   describe Person do
+      #     it { is_expected.to be_eligible_to_vote }
+      #     # or
       #     it { should be_eligible_to_vote }
       #   end
       #
       # @note Because `subject` is designed to create state that is reset between
-      #   each example, and `before(:all)` is designed to setup state that is
+      #   each example, and `before(:context)` is designed to setup state that is
       #   shared across _all_ examples in an example group, `subject` is _not_
-      #   intended to be used in a `before(:all)` hook. RSpec 2.13.1 prints
-      #   a warning when you reference a `subject` from `before(:all)` and we plan
-      #   to have it raise an error in RSpec 3.
+      #   intended to be used in a `before(:context)` hook.
       #
       # @see #should
+      # @see #should_not
+      # @see #is_expected
       def subject
         __memoized.fetch(:subject) do
           __memoized[:subject] = begin
-            described = described_class || self.class.description
+            described = described_class || self.class.metadata.fetch(:description_args).first
             Class === described ? described.new : described
           end
         end
@@ -64,6 +72,11 @@ module RSpec
       #   end
       #
       # @see #subject
+      # @see #is_expected
+      #
+      # @note This only works if you are using rspec-expectations.
+      # @note If you are using RSpec's newer expect-based syntax you may
+      #       want to use `is_expected.to` instead of `should`.
       def should(matcher=nil, message=nil)
         RSpec::Expectations::PositiveExpectationHandler.handle_matcher(subject, matcher, message)
       end
@@ -78,11 +91,35 @@ module RSpec
       #   end
       #
       # @see #subject
+      # @see #is_expected
+      #
+      # @note This only works if you are using rspec-expectations.
+      # @note If you are using RSpec's newer expect-based syntax you may
+      #       want to use `is_expected.to_not` instead of `should_not`.
       def should_not(matcher=nil, message=nil)
         RSpec::Expectations::NegativeExpectationHandler.handle_matcher(subject, matcher, message)
       end
 
-      private
+      # Wraps the `subject` in `expect` to make it the target of an expectation.
+      # Designed to read nicely for one-liners.
+      #
+      # @example
+      #
+      #   describe [1, 2, 3] do
+      #     it { is_expected.to be_an Array }
+      #     it { is_expected.not_to include 4 }
+      #   end
+      #
+      # @see #subject
+      # @see #should
+      # @see #should_not
+      #
+      # @note This only works if you are using rspec-expectations.
+      def is_expected
+        expect(subject)
+      end
+
+    private
 
       # @private
       def __memoized
@@ -90,14 +127,14 @@ module RSpec
       end
 
       # Used internally to customize the behavior of the
-      # memoized hash when used in a `before(:all)` hook.
+      # memoized hash when used in a `before(:context)` hook.
       #
       # @private
-      class AllHookMemoizedHash
-        def self.isolate_for_all_hook(example_group_instance)
+      class ContextHookMemoizedHash
+        def self.isolate_for_context_hook(example_group_instance)
           hash = self
 
-          example_group_instance.instance_eval do
+          example_group_instance.instance_exec do
             @__memoized = hash
 
             begin
@@ -108,12 +145,12 @@ module RSpec
           end
         end
 
-        def self.fetch(key, &block)
+        def self.fetch(key, &_block)
           description = if key == :subject
-            "subject"
-          else
-            "let declaration `#{key}`"
-          end
+                          "subject"
+                        else
+                          "let declaration `#{key}`"
+                        end
 
           raise <<-EOS
 #{description} accessed in #{article} #{hook_expression} hook at:
@@ -126,9 +163,10 @@ is reset between each example, while #{hook_expression} exists to
 EOS
         end
 
+        # @private
         class Before < self
           def self.hook_expression
-            "`before(:all)`"
+            "`before(:context)`"
           end
 
           def self.article
@@ -140,9 +178,10 @@ EOS
           end
         end
 
+        # @private
         class After < self
           def self.hook_expression
-            "`after(:all)`"
+            "`after(:context)`"
           end
 
           def self.article
@@ -155,10 +194,9 @@ EOS
         end
       end
 
-      def self.included(mod)
-        mod.extend(ClassMethods)
-      end
-
+      # This module is extended onto {ExampleGroup}, making the methods
+      # available to be called from within example group blocks.
+      # You can think of them as being analagous to class macros.
       module ClassMethods
         # Generates a method whose return value is memoized after the first
         # call. Useful for reducing duplication between examples that assign
@@ -173,11 +211,9 @@ EOS
         #   though we have yet to see this in practice. You've been warned.
         #
         # @note Because `let` is designed to create state that is reset between
-        #   each example, and `before(:all)` is designed to setup state that is
+        #   each example, and `before(:context)` is designed to setup state that is
         #   shared across _all_ examples in an example group, `let` is _not_
-        #   intended to be used in a `before(:all)` hook. RSpec 2.13.1 prints
-        #   a warning when you reference a `let` from `before(:all)` and we plan
-        #   to have it raise an error in RSpec 3.
+        #   intended to be used in a `before(:context)` hook.
         #
         # @example
         #
@@ -196,7 +232,7 @@ EOS
           # We have to pass the block directly to `define_method` to
           # allow it to use method constructs like `super` and `return`.
           raise "#let or #subject called without a block" if block.nil?
-          MemoizedHelpers.module_for(self).send(:define_method, name, &block)
+          MemoizedHelpers.module_for(self).__send__(:define_method, name, &block)
 
           # Apply the memoization. The method has been defined in an ancestor
           # module so we can use `super` here to get the value.
@@ -232,7 +268,7 @@ EOS
         #   end
         #
         #   describe Thing do
-        #     after(:each) { Thing.reset_count }
+        #     after(:example) { Thing.reset_count }
         #
         #     context "using let" do
         #       let(:thing) { Thing.new }
@@ -265,15 +301,18 @@ EOS
           before { __send__(name) }
         end
 
-        # Declares a `subject` for an example group which can then be the
-        # implicit receiver (through delegation) of calls to `should`.
+        # Declares a `subject` for an example group which can then be wrapped
+        # with `expect` using `is_expected` to make it the target of an expectation
+        # in a concise, one-line example.
         #
         # Given a `name`, defines a method with that name which returns the
         # `subject`. This lets you declare the subject once and access it
         # implicitly in one-liners and explicitly using an intention revealing
         # name.
         #
-        # @param [String,Symbol] name used to define an accessor with an
+        # When given a `name`, calling `super` in the block is not supported.
+        #
+        # @param name [String,Symbol] used to define an accessor with an
         #   intention revealing name
         # @param block defines the value to be returned by `subject` in examples
         #
@@ -281,25 +320,27 @@ EOS
         #
         #   describe CheckingAccount, "with $50" do
         #     subject { CheckingAccount.new(Money.new(50, :USD)) }
-        #     it { should have_a_balance_of(Money.new(50, :USD)) }
-        #     it { should_not be_overdrawn }
+        #     it { is_expected.to have_a_balance_of(Money.new(50, :USD)) }
+        #     it { is_expected.not_to be_overdrawn }
         #   end
         #
         #   describe CheckingAccount, "with a non-zero starting balance" do
         #     subject(:account) { CheckingAccount.new(Money.new(50, :USD)) }
-        #     it { should_not be_overdrawn }
+        #     it { is_expected.not_to be_overdrawn }
         #     it "has a balance equal to the starting balance" do
         #       account.balance.should eq(Money.new(50, :USD))
         #     end
         #   end
         #
         # @see MemoizedHelpers#should
+        # @see MemoizedHelpers#should_not
+        # @see MemoizedHelpers#is_expected
         def subject(name=nil, &block)
           if name
             let(name, &block)
             alias_method :subject, name
 
-            self::NamedSubjectPreventSuper.send(:define_method, name) do
+            self::NamedSubjectPreventSuper.__send__(:define_method, name) do
               raise NotImplementedError, "`super` in named subjects is not supported"
             end
           else
@@ -332,7 +373,7 @@ EOS
         #   end
         #
         #   describe Thing do
-        #     after(:each) { Thing.reset_count }
+        #     after(:example) { Thing.reset_count }
         #
         #     context "using subject" do
         #       subject { Thing.new }
@@ -366,7 +407,7 @@ EOS
         end
       end
 
-      # @api private
+      # @private
       #
       # Gets the LetDefinitions module. The module is mixed into
       # the example group and is used to hold all let definitions.
@@ -391,13 +432,13 @@ EOS
         end
       end
 
-      # @api private
+      # @private
       def self.define_helpers_on(example_group)
-        example_group.send(:include, module_for(example_group))
+        example_group.__send__(:include, module_for(example_group))
       end
 
       if Module.method(:const_defined?).arity == 1 # for 1.8
-        # @api private
+        # @private
         #
         # Gets the named constant or yields.
         # On 1.8, const_defined? / const_get do not take into
@@ -410,7 +451,7 @@ EOS
           end
         end
       else
-        # @api private
+        # @private
         #
         # Gets the named constant or yields.
         # On 1.9, const_defined? / const_get take into account the