WebStub

What if WebMock and NSURLProtocol had a baby?

Features

Supports most any HTTP library that is built on NSURLConnection / NSURLSession
Request matching based upon HTTP method, URI, and body
Optionally, disable real network access
Familiar, delicious syntax
Bacon integration

Installation

Update your Gemfile:

gem "webstub"

Bundle:

$ bundle install

Usage

Add the following line to the top-most describe block in your spec:

extend WebStub::SpecHelpers
Use the following methods to control the use of request stubbing:
- disable_network_access!
- enable_network_access!
- stub_request
- reset_stubs

Example Spec

describe "Example" do
  extend WebStub::SpecHelpers

  describe "Stubbing a GET request to return a simple response after a delay" do
    it "retrieves the front page" do
      stub_request(:get, "http://example.com/").
        to_return(body: "Hello!", content_type: "text/plain", delay: 0.3)

      @body = nil
      @api.get_index do |body, error|
        @body = body
        resume
      end

      wait_max 1.0 do
        @body.should.be == "Hello!"
      end
    end
  end

  describe "Stubbing a GET request to return JSON" do
    it "retrieves suggestions" do
      stub_request(:get, "https://example.com/suggestions?q=mu").
        to_return(json: { suggestions: ["muse"] })

      @suggestions = nil
      @api.get_suggestions("mu") do |results, error|
        @suggestions = results
        resume
      end

      wait_max 1.0 do
        @suggestions.should.not.be.empty
      end
    end
  end

  describe "Stubbing a POST request to return JSON" do
    it "handles a POST request" do
      stub_request(:post, "https://example.com/action").
        with(body: { q: "unsustainable" }).
        to_return(json: [ { album: "The 2nd Law", release_date: "2012-10-01", artist: "Muse" } ])

      @results = nil
      @api.get_album_info_for_track("unsustainable") do |results, error|
        @results = results
        resume
      end

      wait_max 1.0 do
        @results.should.not.be.empty
      end
    end
  end

  describe "Stubbing a GET request to fail" do
    it "returns an NSError with the NSURLError domain" do
      stub_request(:get, "https://example.com/action").
        to_fail(code: NSURLErrorNotConnectedToInternet)

      @error = nil
      @api.get_albums do |results, error|
        @error = error
        resume
      end

      wait_max 1.0 do
        @error.code.should == NSURLErrorNotConnectedToInternet
      end
    end
  end
end

Conventions

The URL is matched exactly as is right now (hence query parameters need to be included and encoded)
The with method's body option accepts either a Hash or a String:
- Hashes are assumed to be form data (with a application/x-www-form-urlencoded content type)
- Strings are matched as is
The to_return method accepts a few options:
- json: accepts either a Hash, Array or a String. If a Hash or Array is provided, it will be converted to JSON. Strings are returned as is, with the Content-Type set to application/json.
- body: accepts a String, and returns it as-is
- content_type: sets the Content-Type when using the body parameter
- status_code: sets the integer Status Code of the response. Defaults to 200.
The to_redirect method accepts:
- url: String of the URL to redirect to (required)
- All options supported by to_return except for status_code
The to_fail method accepts one of the following options:
- code: NSURLErrorDomain error code
- error: NSError to fail the request with

Expectations

Sometimes, you may just want to check that the request has been made to a given URL. In this case, you can use the requested? method of the stub returned by stub_request:

describe Elevate::HTTP do
  extend WebStub::SpecHelpers

  describe ".get" do
    it "synchronously issues a HTTP GET request" do
      stub = stub_request(:get, "http://www.example.com/")

      Elevate::HTTP.get("http://www.example.com/")

      stub.should.be.requested
    end
  end
end

Callbacks

Sometimes, you may want to inspect the request made for a given URL. In this case, you can use the with_callback method of the stub returned by stub_request to add a callback hook:

describe Elevate:HTTP do
  extend WebStub::SpecHelpers

  describe ".post" do
    it "synchronously issues an HTTP POST request" do
      stub = stub_request(:post, "http://www.example.com/")

      stub.with_callback do |headers, body|
        headers.kind_of?(Hash).should == true
        body.kind_of?(Hash).should == true
        body.should == {"key" => "value"}
      end

      Elevate::HTTP.post("http://www.example.com/", json: {key: "value"})
    end
  end
end

Caveats

While WebStub supports NSURLSession, it does not support background sessions, as they don't allow the use of custom NSURLProtocol classes.

TODO

Handle query params similarly to form data

webstub

Development