File: syntax.rb

package info (click to toggle)
ruby-rspec-mocks 2.14.5-1
  • links: PTS, VCS
  • area: main
  • in suites: jessie, jessie-kfreebsd
  • size: 868 kB
  • ctags: 725
  • sloc: ruby: 8,227; makefile: 4
file content (349 lines) | stat: -rw-r--r-- 12,222 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
module RSpec
  module Mocks
    # @api private
    # Provides methods for enabling and disabling the available syntaxes
    # provided by rspec-mocks.
    module Syntax
      # @api private
      #
      # Common stubbing logic for both `stub` and `stub!`. This used to
      # live in `stub`, and `stub!` delegated to `stub`, but we discovered
      # that `stub!` was delegating to `RSpec::Mocks::ExampleMethods#stub`
      # (which declares a test double) when called with an implicit receiver,
      # which was a regression in 2.14.0.
      def self.stub_object(object, message_or_hash, opts = {}, &block)
        if ::Hash === message_or_hash
          message_or_hash.each {|message, value| stub_object(object, message).and_return value }
        else
          opts[:expected_from] = caller(1)[1]
          ::RSpec::Mocks.allow_message(object, message_or_hash, opts, &block)
        end
      end

      # @api private
      # Enables the should syntax (`dbl.stub`, `dbl.should_receive`, etc).
      def self.enable_should(syntax_host = default_should_syntax_host)
        return if should_enabled?(syntax_host)

        syntax_host.class_eval do
          def should_receive(message, opts={}, &block)
            opts[:expected_from] ||= caller(1)[0]
            ::RSpec::Mocks.expect_message(self, message.to_sym, opts, &block)
          end

          def should_not_receive(message, &block)
            opts = {:expected_from => caller(1)[0]}
            ::RSpec::Mocks.expect_message(self, message.to_sym, opts, &block).never
          end

          def stub(message_or_hash, opts={}, &block)
            ::RSpec::Mocks::Syntax.stub_object(self, message_or_hash, opts, &block)
          end

          def unstub(message)
            ::RSpec::Mocks.space.proxy_for(self).remove_stub(message)
          end

          def stub!(message_or_hash, opts={}, &block)
            ::RSpec.deprecate "stub!", :replacement => "stub"
            ::RSpec::Mocks::Syntax.stub_object(self, message_or_hash, opts, &block)
          end

          def unstub!(message)
            ::RSpec.deprecate "unstub!", :replacement => "unstub"
            unstub(message)
          end

          def stub_chain(*chain, &blk)
            ::RSpec::Mocks::StubChain.stub_chain_on(self, *chain, &blk)
          end

          def as_null_object
            @_null_object = true
            ::RSpec::Mocks.proxy_for(self).as_null_object
          end

          def null_object?
            defined?(@_null_object)
          end

          def received_message?(message, *args, &block)
            ::RSpec::Mocks.proxy_for(self).received_message?(message, *args, &block)
          end

          unless Class.respond_to? :any_instance
            Class.class_eval do
              def any_instance
                ::RSpec::Mocks.any_instance_recorder_for(self)
              end
            end
          end
        end
      end

      # @api private
      # Disables the should syntax (`dbl.stub`, `dbl.should_receive`, etc).
      def self.disable_should(syntax_host = default_should_syntax_host)
        return unless should_enabled?(syntax_host)

        syntax_host.class_eval do
          undef should_receive
          undef should_not_receive
          undef stub
          undef unstub
          undef stub!
          undef unstub!
          undef stub_chain
          undef as_null_object
          undef null_object?
          undef received_message?
        end

        Class.class_eval do
          undef any_instance
        end
      end

      # @api private
      # Enables the expect syntax (`expect(dbl).to receive`, `allow(dbl).to receive`, etc).
      def self.enable_expect(syntax_host = ::RSpec::Mocks::ExampleMethods)
        return if expect_enabled?(syntax_host)

        syntax_host.class_eval do
          def receive(method_name, &block)
            Matchers::Receive.new(method_name, block)
          end

          def allow(target)
            AllowanceTarget.new(target)
          end

          def expect_any_instance_of(klass)
            AnyInstanceExpectationTarget.new(klass)
          end

          def allow_any_instance_of(klass)
            AnyInstanceAllowanceTarget.new(klass)
          end
        end

        RSpec::Mocks::ExampleMethods::ExpectHost.class_eval do
          def expect(target)
            ExpectationTarget.new(target)
          end
        end
      end

      # @api private
      # Disables the expect syntax (`expect(dbl).to receive`, `allow(dbl).to receive`, etc).
      def self.disable_expect(syntax_host = ::RSpec::Mocks::ExampleMethods)
        return unless expect_enabled?(syntax_host)

        syntax_host.class_eval do
          undef receive
          undef allow
          undef expect_any_instance_of
          undef allow_any_instance_of
        end

        RSpec::Mocks::ExampleMethods::ExpectHost.class_eval do
          undef expect
        end
      end

      # @api private
      # Indicates whether or not the should syntax is enabled.
      def self.should_enabled?(syntax_host = default_should_syntax_host)
        syntax_host.method_defined?(:should_receive)
      end

      # @api private
      # Indicates whether or not the expect syntax is enabled.
      def self.expect_enabled?(syntax_host = ::RSpec::Mocks::ExampleMethods)
        syntax_host.method_defined?(:allow)
      end

      # @api private
      # Determines where the methods like `should_receive`, and `stub` are added.
      def self.default_should_syntax_host
        # JRuby 1.7.4 introduces a regression whereby `defined?(::BasicObject) => nil`
        # yet `BasicObject` still exists and patching onto ::Object breaks things
        # e.g. SimpleDelegator expectations won't work
        #
        # See: https://github.com/jruby/jruby/issues/814
        if defined?(JRUBY_VERSION) && JRUBY_VERSION == '1.7.4' && RUBY_VERSION.to_f > 1.8
          return ::BasicObject
        end

        # On 1.8.7, Object.ancestors.last == Kernel but
        # things blow up if we include `RSpec::Mocks::Methods`
        # into Kernel...not sure why.
        return Object unless defined?(::BasicObject)

        # MacRuby has BasicObject but it's not the root class.
        return Object unless Object.ancestors.last == ::BasicObject

        ::BasicObject
      end

      # @method should_receive
      # Sets an expectation that this object should receive a message before
      # the end of the example.
      #
      # @example
      #
      #     logger = double('logger')
      #     thing_that_logs = ThingThatLogs.new(logger)
      #     logger.should_receive(:log)
      #     thing_that_logs.do_something_that_logs_a_message
      #
      # @note This is only available when you have enabled the `should` syntax.

      # @method should_not_receive
      # Sets and expectation that this object should _not_ receive a message
      # during this example.

      # @method stub
      # Tells the object to respond to the message with the specified value.
      #
      # @example
      #
      #     counter.stub(:count).and_return(37)
      #     counter.stub(:count => 37)
      #     counter.stub(:count) { 37 }
      #
      # @note This is only available when you have enabled the `should` syntax.

      # @method unstub
      # Removes a stub. On a double, the object will no longer respond to
      # `message`. On a real object, the original method (if it exists) is
      # restored.
      #
      # This is rarely used, but can be useful when a stub is set up during a
      # shared `before` hook for the common case, but you want to replace it
      # for a special case.
      #
      # @note This is only available when you have enabled the `should` syntax.

      # @method stub_chain
      # @overload stub_chain(method1, method2)
      # @overload stub_chain("method1.method2")
      # @overload stub_chain(method1, method_to_value_hash)
      #
      # Stubs a chain of methods.
      #
      # ## Warning:
      #
      # Chains can be arbitrarily long, which makes it quite painless to
      # violate the Law of Demeter in violent ways, so you should consider any
      # use of `stub_chain` a code smell. Even though not all code smells
      # indicate real problems (think fluent interfaces), `stub_chain` still
      # results in brittle examples.  For example, if you write
      # `foo.stub_chain(:bar, :baz => 37)` in a spec and then the
      # implementation calls `foo.baz.bar`, the stub will not work.
      #
      # @example
      #
      #     double.stub_chain("foo.bar") { :baz }
      #     double.stub_chain(:foo, :bar => :baz)
      #     double.stub_chain(:foo, :bar) { :baz }
      #
      #     # Given any of ^^ these three forms ^^:
      #     double.foo.bar # => :baz
      #
      #     # Common use in Rails/ActiveRecord:
      #     Article.stub_chain("recent.published") { [Article.new] }
      #
      # @note This is only available when you have enabled the `should` syntax.

      # @method as_null_object
      # Tells the object to respond to all messages. If specific stub values
      # are declared, they'll work as expected. If not, the receiver is
      # returned.
      #
      # @note This is only available when you have enabled the `should` syntax.

      # @method null_object?
      # Returns true if this object has received `as_null_object`
      #
      # @note This is only available when you have enabled the `should` syntax.

      # @method any_instance
      # Used to set stubs and message expectations on any instance of a given
      # class. Returns a [Recorder](Recorder), which records messages like
      # `stub` and `should_receive` for later playback on instances of the
      # class.
      #
      # @example
      #
      #     Car.any_instance.should_receive(:go)
      #     race = Race.new
      #     race.cars << Car.new
      #     race.go # assuming this delegates to all of its cars
      #             # this example would pass
      #
      #     Account.any_instance.stub(:balance) { Money.new(:USD, 25) }
      #     Account.new.balance # => Money.new(:USD, 25))
      #
      # @return [Recorder]
      #
      # @note This is only available when you have enabled the `should` syntax.

      # @method expect
      # Used to wrap an object in preparation for setting a mock expectation
      # on it.
      #
      # @example
      #
      #   expect(obj).to receive(:foo).with(5).and_return(:return_value)
      #
      # @note This method is usually provided by rspec-expectations, unless
      #   you are using rspec-mocks w/o rspec-expectations, in which case it
      #   is only made available if you enable the `expect` syntax.

      # @method allow
      # Used to wrap an object in preparation for stubbing a method
      # on it.
      #
      # @example
      #
      #   allow(dbl).to receive(:foo).with(5).and_return(:return_value)
      #
      # @note This is only available when you have enabled the `expect` syntax.

      # @method expect_any_instance_of
      # Used to wrap a class in preparation for setting a mock expectation
      # on instances of it.
      #
      # @example
      #
      #   expect_any_instance_of(MyClass).to receive(:foo)
      #
      # @note This is only available when you have enabled the `expect` syntax.

      # @method allow_any_instance_of
      # Used to wrap a class in preparation for stubbing a method
      # on instances of it.
      #
      # @example
      #
      #   allow_any_instance_of(MyClass).to receive(:foo)
      #
      # @note This is only available when you have enabled the `expect` syntax.

      # @method receive
      # Used to specify a message that you expect or allow an object
      # to receive. The object returned by `receive` supports the same
      # fluent interface that `should_receive` and `stub` have always
      # supported, allowing you to constrain the arguments or number of
      # times, and configure how the object should respond to the message.
      #
      # @example
      #
      #   expect(obj).to receive(:hello).with("world").exactly(3).times
      #
      # @note This is only available when you have enabled the `expect` syntax.
    end
  end
end