Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

docs

  • Loading branch information...
commit 6551f1acd4794038784ca20b31f352c25aa7442a 1 parent 4b6774d
@dchelimsky dchelimsky authored
Showing with 76 additions and 28 deletions.
  1. +44 −4 features/README.markdown
  2. +32 −24 features/method_stubs/README.md
View
48 features/README.markdown
@@ -1,10 +1,46 @@
-rspec-mocks is used to create dynamic "doubles", which stand in for real
-objects in examples. You can stub return values and/or set message
-expectations:
+rspec-mocks helps to control the context in a code example by letting you set
+known return values, fake implementations of methods, and even expectations
+that specific messages are received by an object.
+
+You can do these three things on test doubles that rspec-mocks creates for you
+on the fly, or you can do them on objects that are part of your system.
+
+## Messages and Methods
+
+_Message_ and _method_ are metaphors that we use somewhat interchangeably, but
+they are subtly different. In Object Oriented Programming, objects communicate
+by sending _messages_ to one another. When an object receives a message, it
+invokes a _method_ with the same name as the message.
+
+## Test Doubles
+
+A test double is an object that stands in for another object in your system
+during a code example. Use the `double` method to create one:
+
+ double_account = double("Account")
+
+You can also use the `mock` and `stub` methods to create test doubles, however
+these methods are there for backward compatibility only and will likely be
+deprecated and then removed from future versions.
+
+## Method Stubs
+
+A method stub is an instruction to an object (real or test double) to return a
+known value in response to a message:
+
+ die.stub(:roll) { 3 }
+
+This tells the `die` object to return the value `3` when it receives the `roll`
+message.
+
+## Message Expectations
+
+A message expectation is an expectation that an object should receive a
+specific message during the course of a code example:
describe Account do
context "when closed" do
- it "logs an account closed message" do
+ it "logs an 'account closed' message" do
logger = double()
account = Account.new
account.logger = logger
@@ -16,6 +52,10 @@ expectations:
end
end
+This example specifies that the `account` object sends the `logger` the
+`account_closed` message (with itself as an argument) when it receives the
+`close` message.
+
## Issues
The documentation for rspec-mocks is a work in progress. We'll be adding
View
56 features/method_stubs/README.md
@@ -1,39 +1,47 @@
-### Basics
+### Stub return values
- # create a double
- obj = double()
+ obj.stub(:message).and_return('this is the value to return')
+ obj.stub(:message) { 'this is the value to return' }
- # stub a method
- obj.stub(:message) # returns obj
+These two forms are somewhat interchangeable. The difference is that the
+argument to `and_return` is evaluated immediately, whereas the block contents
+are evaluated lazily when the `obj` receives the `message` message.
- # specify a return value
- obj.stub(:message) { 'this is the value to return' }
+The block format is generally preferred as it is more terse and more consistent
+with other forms described below, but lazy evaluation can be confusing because
+things aren't evaluated in the order in which they are declared.
+
+### Fake implementation
+
+ obj.stub(:message) do |arg1, arg2|
+ # set expectations about the args in this block
+ # and/or set a return value
+ end
+
+### Raising/Throwing
+
+ obj.stub(:message).and_raise("this error")
+ obj.stub(:message).and_throw(:this_symbol)
+
+You can also use the block format, for consistency with other stubs:
+
+ obj.stub(:message) { raise "this error" }
+ obj.stub(:message) { throw :this_symbol }
### Argument constraints
#### Explicit arguments
- obj.stub(:message).with('an argument')
- obj.stub(:message).with('more_than', 'one_argument')
+ obj.stub(:message).with('an argument') { ... }
+ obj.stub(:message).with('more_than', 'one_argument') { ... }
#### Argument matchers
- obj.stub(:message).with(anything())
- obj.stub(:message).with(an_instance_of(Money))
- obj.stub(:message).with(hash_including(:a => 'b'))
+ obj.stub(:message).with(anything()) { ... }
+ obj.stub(:message).with(an_instance_of(Money)) { ... }
+ obj.stub(:message).with(hash_including(:a => 'b')) { ... }
#### Regular expressions
- obj.stub(:message).with(/abc/)
-
-### Raising/Throwing
+ obj.stub(:message).with(/abc/) { ... }
- obj.stub(:message) { raise "this error" }
- obj.stub(:message) { throw :this_symbol }
-
-### Arbitrary handling
-
- obj.stub(:message) do |arg1, arg2|
- # set expectations about the args in this block
- # and set a return value
- end
Please sign in to comment.
Something went wrong with that request. Please try again.