Class: Kookaburra::APIDriver

Inherits:
Object
  • Object
show all
Defined in:
lib/kookaburra/api_driver.rb

Overview

Communicate with a Web Services API

You will create a subclass of APIDriver in your testing implementation to be used with you subclass of GivenDriver. While the GivenDriver implements the "business domain" DSL for setting up your application state, the APIDriver maps discreet operations to your application's web service API and can (optionally) handle encoding input data and decoding response bodies to and from your preferred serialization format.

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(configuration, http_client = RestClient) ⇒ APIDriver

Create a new Kookaburra::APIDriver instance

Parameters:

  • configuration (Kookaburra::Configuration)
  • http_client (RestClient) (defaults to: RestClient) —

    (optional) Generally only overriden when testing Kookaburra itself



95
96
97
98
 
# File 'lib/kookaburra/api_driver.rb', line 95

def initialize(configuration, http_client = RestClient)
  @configuration = configuration
  @http_client = http_client
end

Class Method Details

.decode_with {|data| ... } ⇒ Object

Deserialize response body

If specified, the response bodies of all requests made using this Kookaburra::APIDriver will be processed through this function prior to being returned.

Examples:

class MyAPIDriver < Kookaburra::APIDriver
  decode_with { |data| JSON.parse(data) }
  # ...
end

Yield Parameters:

  • data (String) —

    The response body sent by the HTTP server

Yield Returns:

  • (Object) —

    The result of parsing the response body through this function



57
58
59
60
61
 
# File 'lib/kookaburra/api_driver.rb', line 57

def decode_with(&block)
  define_method(:decode) do |data|
    block.call(data)
  end
end

.encode_with {|data| ... } ⇒ Object

Serializes input data

If specified, any input data provided to #post, #put or #request will be processed through this function prior to being sent to the HTTP server.

Examples:

class MyAPIDriver < Kookaburra::APIDriver
  encode_with { |data| JSON.dump(data) }
  # ...
end

Yield Parameters:

  • data (Object) —

    The data parameter that was passed to the request method

Yield Returns:

  • (String) —

    The text to be used as the request body



33
34
35
36
37
38
 
# File 'lib/kookaburra/api_driver.rb', line 33

def encode_with(&block)
  define_method(:encode) do |data|
    return if data.nil?
    block.call(data)
  end
end

.header(name, value) ⇒ Object

Set custom HTTP headers

Can be called multiple times to set HTTP headers that will be provided with every request made by the Kookaburra::APIDriver.

Examples:

class MyAPIDriver < Kookaburra::APIDriver
  header 'Content-Type', 'application/json'
  header 'Accept', 'application/json'
  # ...
end

Parameters:

  • name (String) —

    The name of the header, e.g. 'Content-Type'

  • value (String) —

    The value to which the header is set



77
78
79
 
# File 'lib/kookaburra/api_driver.rb', line 77

def header(name, value)
  headers[name] = value
end

Instance Method Details

#delete(path, data = nil, headers = {}) ⇒ Object

Convenience method to make a DELETE request

See Also:



125
126
127
128
 
# File 'lib/kookaburra/api_driver.rb', line 125

def delete(path, data = nil, headers = {})
  path = add_querystring_to_path(path, data)
  request(:delete, path, nil, headers)
end

#get(path, data = nil, headers = {}) ⇒ Object

Convenience method to make a GET request

See Also:



117
118
119
120
 
# File 'lib/kookaburra/api_driver.rb', line 117

def get(path, data = nil, headers = {})
  path = add_querystring_to_path(path, data)
  request(:get, path, nil, headers)
end

#post(path, data = nil, headers = {}) ⇒ Object

Convenience method to make a POST request

See Also:



103
104
105
 
# File 'lib/kookaburra/api_driver.rb', line 103

def post(path, data = nil, headers = {})
  request(:post, path, data, headers)
end

#put(path, data = nil, headers = {}) ⇒ Object

Convenience method to make a PUT request

See Also:



110
111
112
 
# File 'lib/kookaburra/api_driver.rb', line 110

def put(path, data = nil, headers = {})
  request(:put, path, data, headers)
end

#request(method, path, data, headers) ⇒ Object

Make an HTTP request

If you need to make a request other than the typical GET, POST, PUT and DELETE, you can use this method directly.

This will follow redirects when the server's response code is in the 3XX range. If the response is a 303, the request will be transformed into a GET request.

Parameters:

  • method (Symbol) —

    The HTTP verb to use with the request

  • path (String) —

    The path to request. Will be joined with the Configuration#app_host setting to build the URL unless a full URL is specified here.

  • data (Object) —

    The data to be posted in the request body. If an encoder was specified, this can be any type of object as long as the encoder can serialize it into a String. If no encoder was specified, then this can be one of:

    • a String - will be passed as is
    • a Hash - will be encoded as normal HTTP form params
    • a Hash containing references to one or more Files - will set the content type to multipart/form-data

Returns:

  • (Object) —

    The response body returned by the server. If a decoder was specified, this will return the result of parsing the response body through the decoder function.

Raises:

  • (Kookaburra::UnexpectedResponse) —

    Raised if the HTTP response received is not in the 2XX-3XX range.

See Also:



167
168
169
170
171
172
173
174
 
# File 'lib/kookaburra/api_driver.rb', line 167

def request(method, path, data, headers)
  data = encode(data)
  headers = global_headers.merge(headers)
  response = @http_client.send(method, url_for(path), *[data, headers].compact)
  decode(response.body)
rescue RestClient::Exception => e
  raise_unexpected_response(e)
end