rspec-core 2.99.0 → 3.0.0

data/lib/rspec/core/memoized_helpers.rb

@@ -1,5 +1,9 @@
 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:
@@ -41,13 +45,13 @@ module RSpec
       #   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
@@ -115,7 +119,7 @@ module RSpec
         expect(subject)
       end
 
-      private
+    private
 
       # @private
       def __memoized
@@ -123,99 +127,76 @@ 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)
-          hash_type = self
+      class ContextHookMemoizedHash
+        def self.isolate_for_context_hook(example_group_instance)
+          hash = self
 
-          example_group_instance.instance_eval do
-            @__memoized = hash_type.new(example_group_instance)
+          example_group_instance.instance_exec do
+            @__memoized = hash
 
             begin
               yield
             ensure
-              @__memoized.preserve_accessed_lets
               @__memoized = nil
             end
           end
         end
 
-        def initialize(example_group_instance)
-          @example_group_instance = example_group_instance
-          @hash = {}
-        end
-
-        def fetch(key, &block)
+        def self.fetch(key, &block)
           description = if key == :subject
             "subject"
           else
             "let declaration `#{key}`"
           end
 
-          ::RSpec.warn_deprecation <<-EOS
-DEPRECATION: #{description} accessed in #{article} #{hook_expression} hook at:
+          raise <<-EOS
+#{description} accessed in #{article} #{hook_expression} hook at:
   #{CallerFilter.first_non_rspec_line}
 
 `let` and `subject` declarations are not intended to be called
 in #{article} #{hook_expression} hook, as they exist to define state that
 is reset between each example, while #{hook_expression} exists to
 #{hook_intention}.
-
-This is deprecated behavior that will not be supported in RSpec 3.
 EOS
-          @hash.fetch(key, &block)
-        end
-
-        def []=(key, value)
-          @hash[key] = value
-        end
-
-        def preserve_accessed_lets
-          hash = @hash
-
-          @example_group_instance.class.class_eval do
-            hash.each do |key, value|
-              undef_method(key) if method_defined?(key)
-              define_method(key) { value }
-            end
-          end
         end
 
+        # @private
         class Before < self
-          def hook_expression
-            "`before(:all)`"
+          def self.hook_expression
+            "`before(:context)`"
           end
 
-          def article
+          def self.article
             "a"
           end
 
-          def hook_intention
+          def self.hook_intention
             "define state that is shared across examples in an example group"
           end
         end
 
+        # @private
         class After < self
-          def hook_expression
-            "`after(:all)`"
+          def self.hook_expression
+            "`after(:context)`"
           end
 
-          def article
+          def self.article
             "an"
           end
 
-          def hook_intention
+          def self.hook_intention
             "cleanup state that is shared across examples in an example group"
           end
         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
@@ -230,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
         #
@@ -253,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.
@@ -289,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 }
@@ -331,7 +310,7 @@ EOS
         # implicitly in one-liners and explicitly using an intention revealing
         # name.
         #
-        # @param [String,Symbol] name used to define an accessor with an
+        # @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
         #
@@ -352,12 +331,14 @@ EOS
         #   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
@@ -390,7 +371,7 @@ EOS
         #   end
         #
         #   describe Thing do
-        #     after(:each) { Thing.reset_count }
+        #     after(:example) { Thing.reset_count }
         #
         #     context "using subject" do
         #       subject { Thing.new }
@@ -422,101 +403,9 @@ EOS
           subject(name, &block)
           before { subject }
         end
-
-        # Creates a nested example group named by the submitted `attribute`,
-        # and then generates an example using the submitted block.
-        #
-        # @example
-        #
-        #   # This ...
-        #   describe Array do
-        #     its(:size) { should eq(0) }
-        #   end
-        #
-        #   # ... generates the same runtime structure as this:
-        #   describe Array do
-        #     describe "size" do
-        #       it "should eq(0)" do
-        #         subject.size.should eq(0)
-        #       end
-        #     end
-        #   end
-        #
-        # The attribute can be a `Symbol` or a `String`. Given a `String`
-        # with dots, the result is as though you concatenated that `String`
-        # onto the subject in an expression.
-        #
-        # @example
-        #
-        #   describe Person do
-        #     subject do
-        #       Person.new.tap do |person|
-        #         person.phone_numbers << "555-1212"
-        #       end
-        #     end
-        #
-        #     its("phone_numbers.first") { should eq("555-1212") }
-        #   end
-        #
-        # When the subject is a `Hash`, you can refer to the Hash keys by
-        # specifying a `Symbol` or `String` in an array.
-        #
-        # @example
-        #
-        #   describe "a configuration Hash" do
-        #     subject do
-        #       { :max_users => 3,
-        #         'admin' => :all_permissions }
-        #     end
-        #
-        #     its([:max_users]) { should eq(3) }
-        #     its(['admin']) { should eq(:all_permissions) }
-        #
-        #     # You can still access to its regular methods this way:
-        #     its(:keys) { should include(:max_users) }
-        #     its(:count) { should eq(2) }
-        #   end
-        #
-        # Note that this method does not modify `subject` in any way, so if you
-        # refer to `subject` in `let` or `before` blocks, you're still
-        # referring to the outer subject.
-        #
-        # @example
-        #
-        #   describe Person do
-        #     subject { Person.new }
-        #     before { subject.age = 25 }
-        #     its(:age) { should eq(25) }
-        #   end
-        def its(attribute, &block)
-          RSpec.deprecate("Use of rspec-core's `its` method", :replacement => 'the rspec-its gem')
-
-          describe(attribute.to_s) do
-            if Array === attribute
-              let(:__its_subject) { subject[*attribute] }
-            else
-              let(:__its_subject) do
-                attribute_chain = attribute.to_s.split('.')
-                attribute_chain.inject(subject) do |inner_subject, attr|
-                  inner_subject.send(attr)
-                end
-              end
-            end
-
-            def should(matcher=nil, message=nil)
-              RSpec::Expectations::PositiveExpectationHandler.handle_matcher(__its_subject, matcher, message)
-            end
-
-            def should_not(matcher=nil, message=nil)
-              RSpec::Expectations::NegativeExpectationHandler.handle_matcher(__its_subject, matcher, message)
-            end
-
-            example(&block)
-          end
-        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.
@@ -541,13 +430,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
@@ -560,7 +449,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