Browse files

updated the readme

  • Loading branch information...
1 parent 31035ae commit 4303b0e71fd0c265bd3c5a0a4ddcf058d8ad4260 @rubiii rubiii committed Sep 28, 2011
Showing with 111 additions and 76 deletions.
  1. +111 −76 README.md
View
187 README.md
@@ -1,115 +1,150 @@
-Savon::Spec
+Savon::Spec [![Build Status](https://secure.travis-ci.org/rubiii/savon_spec.png)](http://travis-ci.org/rubiii/savon_spec)
===========
-Savon testing library
+Savon testing library.
+
Installation
------------
Savon::Spec is available through [Rubygems](http://rubygems.org/gems/savon_spec) and can be installed via:
- $ gem install savon_spec
+```
+$ gem install savon_spec
+```
-Dependencies
-------------
-Currently, the dependencies are very strict. Savon::Spec is meant to be used with:
+Expects
+-------
+
+Include the `Savon::Spec::Macros` module into your specs:
+
+``` ruby
+RSpec.configure do |config|
+ config.include Savon::Spec::Macros
+end
+```
+
+By including the module you get a `savon` method to mock SOAP requests. Here's a very simple example:
+
+``` ruby
+let(:client) do
+ Savon::Client.new do
+ wsdl.endpoint = "http://example.com"
+ wsdl.namespace = "http://users.example.com"
+ end
+end
+
+before do
+ savon.expects(:get_user)
+end
+
+it "mocks a SOAP request" do
+ client.request(:get_user)
+end
+```
+
+This sets up an expectation for Savon to call the `:get_user` action and the specs should pass without errors.
+Savon::Spec does not execute a POST request to your service, but uses [Savon hooks](http://savonrb.com/#hook_into_the_system) to return a fake response:
+
+``` ruby
+{ :code => 200, :headers => {}, :body => "" }
+```
-* [Savon](http://rubygems.org/gems/savon) ~> 0.8.0.beta.3
-* [RSpec](http://rubygems.org/gems/rspec) ~> 2.0.0
-* [Mocha](http://rubygems.org/gems/mocha) ~> 0.9.8
+To further isolate your specs, I'd suggest setting up [FakeWeb](http://rubygems.org/gems/fakeweb) to disallow any HTTP requests.
-Note to self: the required versions for RSpec and Mocha could probably be lower.
-Getting started
----------------
+With
+----
-### Macros
+Mocking SOAP requests is fine, but what you really need to do is verify whether you're sending the right
+parameters to your service.
-Include the `Savon::Spec::Macros` module:
+``` ruby
+before do
+ savon.expects(:get_user).with(:id => 1)
+end
- RSpec.configure do |config|
- config.include Savon::Spec::Macros
- end
+it "mocks a SOAP request" do
+ client.request(:get_user) do
+ soap.body = { :id => 1 }
+ end
+end
+```
-### Mock
+This checks whether Savon uses the SOAP body Hash you expected and raises a `Savon::Spec::ExpectationError` if it doesn't.
-By including the macros, you have access to the `savon` method in your specs. It returns a `Savon::Spec::Mock` instance to set up your expectations. It's based on Mocha and comes with similiar methods:
+```
+Failure/Error: client.request :get_user, :body => { :name => "Dr. Who" }
+Savon::Spec::ExpectationError:
+ expected { :id => 1 } to be sent, got: { :name => "Dr. Who" }
+```
- #expects(soap_action) # mocks SOAP request to a given SOAP action
- #stubs(soap_action) # stubs SOAP requests to a given SOAP action
- #with(soap_body) # expects Savon to send a given SOAP body
- #raises_soap_fault # raises or acts like there was a SOAP fault
- #returns(response) # returns the given response
+You can also pass a block to the `#with` method and receive the `Savon::SOAP::Request` before the POST request is executed.
+Here's an example of a custom expectation:
-### Fixtures
+``` ruby
+savon.expects(:get_user).with do |request|
+ request.soap.body.should include(:id)
+end
+```
-Savon::Spec works best with SOAP response fixtures (simple XML files) and a conventional folder structure:
- ~ spec
- ~ fixtures
- ~ get_user
- - single_user.xml
- - multiple_users.xml
- + models
- + controllers
- + helpers
- + views
+Returns
+-------
-When used inside a Rails 3 application, Savon::Spec uses the command `Rails.root.join("spec", "fixtures")` to locate your fixture directory. In any other case, you have to manually set the fixture path via:
+Instead of the default fake response, you can return a custom HTTP response by passing a Hash to the `#returns` method.
+If you leave out any of these values, Savon::Spec will add the default values for you.
- Savon::Spec::Fixture.path = File.expand_path("../fixtures", __FILE__)
+``` ruby
+savon.expects(:get_user).returns(:code => 500, :headers => {}, :body => "save the unicorns")
+```
-The directories inside the fixture directory should map to SOAP actions and the XML fixtures inside those directories should describe the SOAP response. Please take a look at the following examples to better understand this convention.
+Savon::Spec also works with SOAP response fixtures (simple XML files) and a conventional folder structure:
-An example
-----------
+```
+~ spec
+ ~ fixtures
+ ~ get_user
+ - single_user.xml
+ - multiple_users.xml
+ + models
+ + controllers
+ + helpers
+ + views
+```
-user.rb
+When used inside a Rails 3 application, Savon::Spec uses `Rails.root.join("spec", "fixtures")` to locate your fixture directory.
+In any other case, you have to manually set the fixture path via:
- class User
+``` ruby
+Savon::Spec::Fixture.path = File.expand_path("../fixtures", __FILE__)
+```
- def self.all
- response = client.request :get_all_users
- response.to_hash.map { |user_hash| new user_hash }
- end
+Directory names inside the fixtures directory map to SOAP actions and contain actual SOAP responses from your service(s).
+You can use one of those fixtures for the HTTP response body like in the following example:
- def self.find(user_id)
- response = client.request :get_user do
- soap.body = { :id => user_id }
- end
-
- new response.to_hash
- end
+``` ruby
+savon.expects(:get_user).with(:id => 1).returns(:single_user)
+```
- end
+As you can see, Savon::Spec uses the name of your SOAP action and the Symbol passed to the `#returns` method to navigate inside
+your fixtures directory and load the requested XML files.
-user_spec.rb
- describe User do
+Never
+-----
- describe ".all" do
- before do
- savon.expects(:get_all_users).returns(:multiple_users)
- end
+Savon::Spec can also verify that a certain SOAP request was not executed:
- it "should return an Array of Users" do
- User.all.each { |user| user.should be_a(User) }
- end
+``` ruby
+savon.expects(:get_user).never
+```
- it "should return exactly 7 Users" do
- User.all.should have(7).items
- end
- end
- describe ".find" do
- before do
- savon.expects(:get_user).with(:id => 1).returns(:single_user)
- end
+RSpec
+-----
- it "should return a User for a given :id" do
- User.find(1).should be_a(User)
- end
- end
+This library is optimized to work with RSpec, but it could be tweaked to work with any other testing library.
+Savon::Spec installs an after filter to clear out its Savon hooks after each example.
- end

0 comments on commit 4303b0e

Please sign in to comment.