docs/rspec.md in evil-client-1.0.0 vs docs/rspec.md in evil-client-1.1.0

@@ -1,15 +1,18 @@
 When you provide a client to remote API, you would provide some means for its users to test their operations.
 
-Surely, they could use [webmock] to check the ultimate requests that are sent to the server. But doing this, they would inadvertedly specify not their own code, but your client's code too. What do they actually need is a means to check calls of your client's operations. This way they would back on correctness of your client, and take its interface as an endpoint.
+Surely, they could use [webmock] to check the ultimate requests that are sent to the server. But doing this, they would inadvertedly specify not their own code, but your client's code too. What do they actually need is a means to stub and check invocations of your client's operations. This way they would back on correctness of your client, and take its interface as an endpoint.
 
-For this reason, we support a special RSpec matcher `perform_operation`. It checks, what operations are called via evil-client, and what options are used in there.
+For this reason, we support a special RSpec stubs and expectations. sThey are not loaded by default, so you must require it first, and then include the module:
 
-The matcher isn't loaded by default, so you must require it first:
-
 ```ruby
 require "evil/client/rspec"
+
+RSpec.describe CatsClient, "cats.fetch" do
+  include Evil::Client::RSpec
+  # ...
+end
 ```
 
 Providing that you defined some client...
 
 ```ruby
@@ -35,62 +38,89 @@
 RSpec.describe CatsClient, "cats.fetch" do
   let(:client) { CatsClient.new(token: "foo") }
   let(:scope)  { client.cats(version: 1) }
 
   it "fetches a cat by id" do
-    expect { scope.fetch(id: 8) }
-      .to perform_operation("CatsClient.client.fetch")
+    stub_client_operation(CatsClient, "cats.fetch")
+      .with(token: "foo", version: 1, id: 8) # full hash of collected options
+      .to_return 8 # returned value by operation
+
+    expect(scope.fetch(id: 8)).to eq 8
+    expect_client_operation(CatsClient, "cats.fetch")
+      .to_have_been_performed
   end
 end
 ```
 
-You can add chaining using one of 3 additional methods: `with`, `with_exactly`, or `without`.
+## Selection
 
-## with
+To select stubbed operations you can specify client class:
 
-This method checks that the operation **includes some options**:
+```ruby
+stub_client_operation(CatsClient)
+```
 
+or its superclass
+
 ```ruby
-expect { scope.fetch(id: 8) }
-  .to perform_operation("CatsClient.client.fetch")
-  .with token: "foo"
+stub_client_operation(Evil::Client)
 ```
 
-## with_exactly
+or leave it for default `Evil::Client`:
 
-This time you can check the full list of options given to operation:
+```ruby
+stub_client_operation()
+```
 
+or add a fully qualified name of the operation (for **exact** matching):
+
 ```ruby
-expect { scope.fetch(id: 8) }
-  .to perform_operation("CatsClient.client.fetch")
-  .with_exactly token: "foo", version: 1, id: 8
+stub_client_operation(CatsClient, "cats.fetch")
 ```
 
-## without
+or regexp for partial matching:
 
-You can also check that some keys are absent:
+```ruby
+stub_client_operation(CatsClient, /fetch/)
+```
 
+or use method `with` to check options exactly:
+
 ```ruby
-expect { scope.fetch(id: 8) }
-  .to perform_operation("CatsClient.client.fetch")
-  .without :name, :email
+stub_client_operation(CatsClient, "cats.fetch").with(token: "foo", version: 1, id: 8)
 ```
 
-This can be useful to check a behaviour of the client with optional attributes.
+or partially:
 
-All checks can be negated as well:
+```ruby
+stub_client_operation(CatsClient, "cats.fetch").with(hash_including(id: 8))
+```
 
+or via block:
+
 ```ruby
-expect { scope.fetch(id: 8) }
-  .not_to perform_operation("CatsClient.client.fetch")
-  .with token: "foo"
+stub_client_operation(CatsClient, "cats.fetch").with { |opts| opts[:id] == 8 }
 ```
 
-**Notice**: Under the hood the matcher doesn't stub the request, so its better to stub all requests by hand:
+## Return value
 
+You **must** define some value returned by a stub:
+
 ```ruby
-require "webmock/rspec"
+stub_client_operation(CatsClient, "cats.fetch").to_return(8)
+```
 
-before { stub_request :any, // }
+or fall back to original implementation:
+
+```ruby
+stub_client_operation(CatsClient, "cats.fetch").to_call_original
 ```
+
+or raise an exception:
+
+```ruby
+stub_client_operation(CatsClient, "cats.fetch").to_raise StandardError, "Wrong id"
+```
+
+## Some Hint
 
 [webmock]: https://github.com/bblimke/webmock
\ No newline at end of file