brine-dsl 0.9.0 → 0.10.0

data/lib/brine/requesting.rb

@@ -0,0 +1,171 @@
+##
+# @file requesting.rb
+# Request construction and response storage.
+##
+
+module Brine
+
+  ##
+  # Module in charge of constructing requests and saving responses.
+  ##
+  module Requesting
+    require 'faraday_middleware'
+    require 'brine/client_building'
+
+    ##
+    # The root url to which Brine will send requests.
+    #
+    # This will normally be the value of ENV['BRINE_ROOT_URL'],
+    # and that value should be directly usable after older
+    # ENV['ROOT_URL'] is end-of-lifed (at which point this can be removed).
+    #
+    # @brine_root_url is used if set to allow setting this value more programmatically.
+    #
+    # @return [String] The root URL to use or nil if none is provided.
+    ##
+    def brine_root_url
+      if @brine_root_url
+        @brine_root_url
+      elsif ENV['BRINE_ROOT_URL']
+        ENV['BRINE_ROOT_URL']
+      elsif ENV['ROOT_URL']
+        deprecation_message('1.0', 'ROOT_URL is deprecated, replace with BRINE_ROOT_URL') if ENV['ROOT_URL']
+        ENV['ROOT_URL']
+      end
+    end
+
+    ##
+    # Normalize an HTTP method for the HTTP client library (to a lowercased symbol).
+    #
+    # @param [String] method A text representation of the HTTP method.
+    # @return [Symbol] A representation of `method` usable by the HTTP client library.
+    ##
+    def parse_method(method)
+      method.downcase.to_sym
+    end
+
+    ##
+    # Set the client which will be used to send HTTP requests.
+    #
+    # This will generally be a connection as created by the ClientBuilding module.
+    #
+    # @param [Faraday::Connection, #run_request] client The client which will be used to issue HTTP requests.
+    ##
+    def set_client(client)
+      @client = client
+    end
+
+    ##
+    # The currently active client which will be used to issue HTTP calls.
+    #
+    # This will be initialized as neded on first access
+    # to a default client constructed by the ClientBuilding module.
+    #
+    # @return [Faraday::Connection, #run_request] The currently active client object.
+    ##
+    def client
+      @client ||= client_for_host(brine_root_url)
+    end
+
+    ##
+    # Clear any previously built request state and set defaults.
+    #
+    # This should be called upon request completion or when constructing a new
+    # request so no extant state inadvertently pollutes the new construction.
+    ##
+    def reset_request
+      @params = @headers = @body = nil
+    end
+
+    ##
+    # Store the provided body in the request being built.
+    #
+    # This will override any previous body value.
+    #
+    # @param [Object] The new data to be placed in the request body.
+    ##
+    def set_request_body(obj)
+      @body = obj
+    end
+
+    ##
+    # Send a `method` request to `url` including any current builder options and store response.
+    #
+    # The response will be available as the `#response` property.
+    #
+    # For requests such as simple GETs that only require a url this method may
+    # be self-contained; for more complex requests the values collected through
+    # request building are likely required. Any data present from the builder
+    # methods will always be inclued in the request and therefore such data should
+    # be cleared using `#reset_request` if it is not desired.
+    #
+    # @param [Symbol] method The client friendly representation of the HTTP method for the request
+    #                        (@see #parse_method).
+    # @param [String] url The url to which the request will be sent.
+    ##
+    def send_request(method, url)
+      @response = client.run_request(method, url, @body, headers) do |req|
+        req.params = request_params
+      end
+    end
+
+    ##
+    # The response for the last sent request.
+    #
+    # @return [Faraday::Response] The most recent response.
+    ##
+    def response
+      @response
+    end
+
+    ##
+    # The headers for the request currently being built.
+    #
+    # Will be initialized as needed on first access,
+    # with a default specifying JSON content-type.
+    #
+    # @return [Hash] The headers to use for the constructed request.
+    ##
+    def headers
+      @headers ||= {content_type: 'application/json'}
+    end
+
+    ##
+    # Set the specified header to the provided value.
+    #
+    # @param [String] k The name of the header whose value will be set.
+    # @param [Object] v The value to set for the specified header.
+    #                   This should normally be a String, but some other types may work.
+    ##
+    def set_header(k, v)
+      headers[k] = v
+    end
+
+    ##
+    # The query parameters which will be attached to the constructeed request.
+    #
+    # Will be initialized to an empty hash as needed upon first access.
+    #
+    # @return [Hash] The query parameters to use for request construction.
+    ##
+    def request_params
+      @request_params ||= {}
+    end
+
+    ##
+    # Assign the provided value to the specified request query parameter.
+    #
+    # @param [String] k The name of the query parameter whose value is being assigned.
+    # @param [Object] v The value to assign the query parameter (normally a String).
+    ##
+    def set_request_param(k, v)
+      request_params[k] = v
+    end
+
+  end
+
+  ##
+  # Mix the Requesting module functionality into the main Brine module.
+  ##
+  include Requesting
+end

data/lib/brine/rest_steps.rb

@@ -1,6 +1,6 @@
 require 'rspec'
 require 'brine/util'
-require 'brine/selector'
+require 'brine/selecting'
 require 'jsonpath'
 
 # Chopping Block

data/lib/brine/selecting.rb

@@ -0,0 +1,166 @@
+##
+# @file selecting.rb
+# Selection of one or more values to be used by Brine (normally for assertion).
+##
+
+module Brine
+
+  ##
+  # A module providing assorted means to select particular values out of objects/graphs. 
+  ##
+  module Selecting
+
+    require 'brine/coercing'
+    require 'rspec/expectations'
+    require 'jsonpath'
+
+    ##
+    # An object responsible for selecting one or more values.
+    # This Selector will test whether the targeted value itself satisfies the assertion.
+    #
+    # RSpec is used within this implementation to perform assertions.
+    # The Selector ultimately perform this assertion by accepting an RSpec matcher
+    # which it applied against the targeted value.
+    ##
+    class Selector
+      include RSpec::Matchers
+
+      ##
+      # [Coercer] The Coercer that may modify values prior to performing assertions.
+      ##
+      attr_accessor :coercer
+
+      ##
+      # Construct a selector to perform assertions against a provided target.
+      #
+      # @param [Object] taret The value against which assertions will be performed.
+      # @param [Boolean] negated Whether the assertions from this selector should be negated.
+      #                          This is deprecated and should instead be passed to #assert_that.
+      ##
+      def initialize(target, negated=false)
+        @target = target
+	@negated = negated
+      end
+
+      ##
+      # Optionally perform some modification to the RSpec matcher prior to assertion.
+      #
+      # This is designed to allow subclassess to be able to modify the way
+      # in which matchers are applied against the values. This method is a pass-through in this class.
+      #
+      # @param [RSpec::Matcher] matcher The matcher originally passed to #assert_that.
+      # @return [RSpec::Matcher] The Matcher to be used while performing the assertion.
+      ##
+      def filter_matcher(matcher)
+        matcher
+      end
+
+      ##
+      # Perform the provided assertion against the instance target.
+      #
+      # The values will be coerced prior to evaluation.
+      #
+      # @param [Object] value The value/parameter against which the target will be compared.
+      #                       In cases where no parameter is needed for comparison, this may be nil.
+      # @param [Boolean] negated If true the assertion should be expected to _fail_, otherwise it should pass.
+      # @param [Block] A block which will be passed a coerced copy of `value` and which should return an
+      #                RSpec matcher which will be evaluated against the coerced target value.
+      ##
+      def assert_that(value, negated=nil)
+        # shim while moving negation to assertions.
+        negated = @negated if negated.nil?
+        target, value = coercer.coerce(@target, value)
+        message = negated ? :to_not : :to
+        matcher = filter_matcher(yield(value))
+        expect(target).send(message, matcher)
+      end
+
+    end
+
+    ##
+    # A Selector which will test whether any of the children of the targeted value satisfy the assertion.
+    ##
+    class AnySelector < Selector
+      def filter_matcher(matcher)
+        include(matcher)
+      end
+    end
+
+    ##
+    # A Selector which will test whether all of the children of the targeted value satisfy the assertion.
+    ##
+    class AllSelector < Selector
+      def filter_matcher(matcher)
+        all(matcher)
+      end
+    end
+
+    ##
+    # Activate a Selector for the provided target.
+    #
+    # @param [Object] target The value which the Selector should target.
+    # @param [Boolean] negated DEPRECATED If true the assertions should be expected to fail.
+    ##
+    def select(target, negated=nil)
+      use_selector(Selector.new(target, negated))
+    end
+
+    ##
+    # Activate a Selector for any of the children of the provided target.
+    #
+    # @param [Object] target The value which the Selector should target.
+    # @param [Boolean] negated DEPRECATED If true the assertions should be expected to fail.
+    ##
+    def select_any(target, negated=nil)
+      use_selector(AnySelector.new(target, negated))
+    end
+
+    ##
+    # Activate a Selector for all of the children of the provided target.
+    #
+    # @param [Object] target The value which the Selector should target.
+    # @param [Boolean] negated DEPRECATED If true the assertions should be expected to fail.
+    ##
+    def select_all(target, negated=nil)
+      use_selector(AllSelector.new(target, negated))
+    end
+
+    ##
+    # Configure selector and make it the active Selector.
+    #
+    # @param [Selector] selector The selector which will be activated.
+    ##
+    def use_selector(selector)
+      selector.coercer = coercer
+      @selector = selector
+    end
+
+    ##
+    # The currently active Selector.
+    #
+    # @return The Selector as set by #use_selector
+    ##
+    def selector
+      @selector
+    end
+
+  end
+
+  # Mix the Selecting module functionality into the main Brine module.
+  include Selecting
+end
+
+#
+# Steps
+#
+RESPONSE_ATTRIBUTES='(status|headers|body)'
+Then(/^the value of `([^`]*)` is( not)? (.*)$/) do |value, negated, assertion|
+  select(value, (!negated.nil?))
+  step "it is #{assertion}"
+end
+
+def dig_from_response(attribute, path=nil, plural=false)
+  root = response.send(attribute.to_sym)
+  return root if !path
+  JsonPath.new("$.#{path}").send(plural ? :on : :first, root)
+end

data/lib/brine/step_definitions/assertions.rb

@@ -1,50 +1,50 @@
 # assertions.rb - General assertions to be used with a Selector
 
 Then(/^it is equal to `([^`]*)`$/) do |value|
-  selector.assert_that(value) {|v| eq v}
+  perform { selector.assert_that(value) {|v| eq v} }
 end
 Then(/^it is equal to:$/) do |value|
-  selector.assert_that(value) {|v| eq v}
+  perform { selector.assert_that(value) {|v| eq v} }
 end
 Then(/^it is matching `([^`]*)`$/) do |value|
-  selector.assert_that(value) {|v| match v}
+  perform { selector.assert_that(value) {|v| match v} }
 end
 Then (/^it is matching:$/) do |value|
-  selector.assert_that(value) {|v| match v}
+  perform { selector.assert_that(value) {|v| match v} }
 end
 Then(/^it is greater than `([^`]*)`$/) do |value|
-  selector.assert_that(value) {|v| be > v}
+  perform { selector.assert_that(value) {|v| be > v} }
 end
 Then(/^it is greater than or equal to `([^`]*)`$/) do |value|
-  selector.assert_that(value) {|v| be >= v}
+  perform { selector.assert_that(value) {|v| be >= v} }
 end
 Then(/^it is less than `([^`]*)`$/) do |value|
-  selector.assert_that(value) {|v| be < v}
+  perform { selector.assert_that(value) {|v| be < v} }
 end
 Then(/^it is less than or equal to `([^`]*)`$/) do |value|
-  selector.assert_that(value) {|v| be <= v}
+  perform { selector.assert_that(value) {|v| be <= v} }
 end
 
 # Be a little smarter than default.
 Then(/^it is empty$/) do
-  selector.assert_that(nil) do
+  perform { selector.assert_that(nil) do
     satisfy{|i| i.nil? || (i.respond_to?(:empty?) && i.empty?) }
-  end
+  end }
 end
 
 Then(/^it is including `([^`]*)`$/) do |value|
-  selector.assert_that(value) {|v| include v }
+  perform { selector.assert_that(value) {|v| include v } }
 end
 Then(/^it is including:$/) do |value|
-  selector.assert_that(value) {|v| include v }
+  perform { selector.assert_that(value) {|v| include v } }
 end
 
 Then(/^it is a valid `([^`]*)`$/) do |type|
-  selector.assert_that(type) {|t| type_check_for(t) }
+  perform { selector.assert_that(type) {|t| type_check_for(t) } }
 end
 
 Then(/^it is of length `([^`]*)`$/) do |length|
-  selector.assert_that(length) do |l|
+  perform { selector.assert_that(length) do |l|
     satisfy{|i| i.respond_to?(:length) && i.length == l}
-  end
+  end }
 end

data/lib/brine/step_definitions/assignment.rb

@@ -1,6 +1,7 @@
 ##
 # @file assignment.rb
 # Assignment related steps.
+##
 
 ##
 # Assign the provided parameter.
@@ -8,7 +9,7 @@
 # @param name - The identifier to which the value will be bound.
 # @param value - The value to bind to the identifier.
 When(/^`([^`]*)` is assigned `([^`]*)`$/) do |name, value|
-  bind(name, value)
+  perform { bind(name, value) }
 end
 
 ##
@@ -16,7 +17,7 @@ end
 #
 # @param name - The identifier to which a random string will be bound.
 When(/^`([^`]*)` is assigned a random string$/) do |name|
-  bind(name, SecureRandom.uuid)
+  perform { bind(name, SecureRandom.uuid) }
 end
 
 ##
@@ -24,7 +25,7 @@ end
 #
 # @param name - The identifier to which the current timestamp will be bound.
 When(/^`([^`]*)` is assigned a timestamp$/) do |name|
-  bind(name, DateTime.now)
+  perform { bind(name, DateTime.now) }
 end
 
 ##
@@ -37,5 +38,5 @@ end
 # whether to extract a single match or a collection of all matching.
 When(/^`([^`]*)` is assigned the response #{RESPONSE_ATTRIBUTES}(?: child(ren)? `([^`]*)`)?$/) do
   |name, attribute, plural, path|
-  bind(name, dig_from_response(attribute, path, !plural.nil?))
+  perform { bind(name, dig_from_response(attribute, path, !plural.nil?)) }
 end

data/lib/brine/step_definitions/cleanup.rb

@@ -1,4 +1,4 @@
 # cleanup.rb - Track information needed for Resource Cleanup
 When(/^a resource is created at `([^`]*)`$/) do |path|
-  track_created_resource path
-end
+  perform { track_created_resource path }
+end

data/lib/brine/step_definitions/perform.rb

@@ -0,0 +1,16 @@
+##
+# @file perform.rb
+# Steps related to performing actions
+##
+
+When /^actions are defined such that$/ do
+  collect_actions
+end
+
+Then /^the actions are( not)? successful within a `([^`]*)` period$/ do |negated, period|
+  method = negated ? :to : :to_not
+  expect { poll_for(retrieve_duration(period)) {
+    performer.evaluate
+  } }.send(method, raise_error)
+  reset_performer
+end

data/lib/brine/step_definitions/request_construction.rb

@@ -1,24 +1,28 @@
 # request_construction.rb - Build and send requests
 
 When(/^the request body is assigned:$/) do |input|
-  set_request_body(input)
+  perform { set_request_body(input) }
 end
 
 When(/^the request query parameter `([^`]*)` is assigned `([^`]*)`$/) do |param, value|
-  add_request_param(param, value)
+  perform { set_request_param(param, value) }
 end
 
 When(/^the request header `([^`]*)` is assigned `([^`]*)`$/) do |header, value|
-  add_header(header, value)
+  perform { set_header(header, value) }
 end
 
 When(/^the request credentials are set for basic auth user `([^`]*)` and password `([^`]*)`$/) do |user, password|
-  base64_combined = Base64.strict_encode64("#{user}:#{password}")
-  add_header('Authorization', "Basic #{base64_combined}")
+  perform do
+    base64_combined = Base64.strict_encode64("#{user}:#{password}")
+    set_header('Authorization', "Basic #{base64_combined}")
+  end
 end
 
 When(/^an? (GET|POST|PATCH|PUT|DELETE|HEAD|OPTIONS) is sent to `([^`]*)`$/) do |method, url|
-  send_request(parse_method(method), URI.escape(url))
-  bind('response', response)
-  reset_request
+  perform do
+    send_request(parse_method(method), URI.escape(url))
+    bind('response', response)
+    reset_request
+  end
 end

data/lib/brine/step_definitions/selection.rb

@@ -1,37 +1,49 @@
 #RESPONSE_ATTRIBUTES='(status|headers|body)'
 Then(/^the value of the response #{RESPONSE_ATTRIBUTES}(?: child(ren)? `([^`]*)`)? is( not)? (.*)(?<!:)$/) do
   |attribute, plural, path, negated, assertion|
-  use_selector(Selector.new(dig_from_response(attribute, path, !plural.nil?), (!negated.nil?)))
-  step "it is #{assertion}"
+  perform do
+    select(dig_from_response(attribute, path, !plural.nil?), (!negated.nil?))
+    step "it is #{assertion}"
+  end
 end
 
 Then(/^the value of the response #{RESPONSE_ATTRIBUTES}(?: child(ren)? `([^`]*)`)? is( not)? (.*)(?<=:)$/) do
   |attribute, plural, path, negated, assertion, multi|
-  use_selector(Selector.new(dig_from_response(attribute, path, !plural.nil?), (!negated.nil?)))
-  step "it is #{assertion}", multi.to_json
+  perform do
+    select(dig_from_response(attribute, path, !plural.nil?), (!negated.nil?))
+    step "it is #{assertion}", multi.to_json
+  end
 end
 
 Then(/^the value of the response #{RESPONSE_ATTRIBUTES}(?: child(ren)? `([^`]*)`)? does( not)? have any element that is (.*)(?<!:)$/) do
   |attribute, plural, path, negated, assertion|
-  use_selector(AnySelector.new(dig_from_response(attribute, path, !plural.nil?), (!negated.nil?)))
-  step "it is #{assertion}"
+  perform do
+    select_any(dig_from_response(attribute, path, !plural.nil?), (!negated.nil?))
+    step "it is #{assertion}"
+  end
 end
 
 Then(/^the value of the response #{RESPONSE_ATTRIBUTES}(?: child(ren)? `([^`]*)`)? does( not)? have any element that is (.*)(?<=:)$/) do
   |attribute, plural, path, negated, assertion, multi|
-  use_selector(AnySelector.new(dig_from_response(attribute, path, !plural.nil?), (!negated.nil?)))
-  step "it is #{assertion}", multi.to_json
+  perform do
+    select_any(dig_from_response(attribute, path, !plural.nil?), (!negated.nil?))
+    step "it is #{assertion}", multi.to_json
+  end
 end
 
 #Would be negated with `not all' which would be equivalent to any(not ) but that's not readily supported
 Then(/^the value of the response #{RESPONSE_ATTRIBUTES}(?: child(ren)? `([^`]*)`)? has elements which are all (.*)(?<!:)$/) do
   |attribute, plural, path, assertion|
-  use_selector(AllSelector.new(dig_from_response(attribute, path, !plural.nil?), false))
-  step "it is #{assertion}"
+  perform do
+    select_all(dig_from_response(attribute, path, !plural.nil?), false)
+    step "it is #{assertion}"
+  end
 end
 
 Then(/^the value of the response #{RESPONSE_ATTRIBUTES}(?: child(ren)? `([^`]*)`)? has elements which are all (.*)(?<=:)$/) do
   |attribute, plural, path, assertion, multi|
-  use_selector(AllSelector.new(dig_from_response(attribute, path, !plural.nil?), false))
-  step "it is #{assertion}", multi.to_json
+  perform do
+    select_all(dig_from_response(attribute, path, !plural.nil?), false)
+    step "it is #{assertion}", multi.to_json
+  end
 end

data/lib/brine/test_steps.rb

@@ -5,6 +5,9 @@ require 'rspec'
 #
 HTTP_METHOD='GET|POST|PATCH|PUT|DELETE|HEAD|OPTIONS'
 
+ENV['BRINE_DURATION_SECONDS_short'] = '3'
+ENV['BRINE_DURATION_SECONDS_long'] = '6'
+
 class StubResponse
   attr_accessor :body, :status, :headers
 
@@ -15,6 +18,19 @@ class StubResponse
   end
 end
 
+class DelayedStubResponse < StubResponse
+
+  def initialize(delay)
+    super()
+    @activation = Time.now + delay
+  end
+
+  def body
+    Time.now < @activation ? nil : @body
+  end
+
+end
+
 class StubRequest
   attr_accessor :method, :path, :headers, :body
 
@@ -135,6 +151,10 @@ When /^the response status is assigned `([^`]*)`$/ do |status|
   @response.status = status.to_i    # this coercion isn't needed but is a guarantee
 end
 
+When /^the response is delayed `([^`]*)` seconds$/ do |seconds|
+   @response = DelayedStubResponse.new(seconds)
+end
+
 Then(/^the response body as JSON is:$/) do |text|
   expect(response.body.to_json).to eq text
 end

data/lib/brine/transforms.rb

@@ -1,10 +1,14 @@
-# = transformers.rb:: Argument Transforms for Brine
+##
+# @file  transformers.rb
+# Argument Transforms for Brine.
 #
 # The Transforms that convert provided inputs to support richer
 # functionaliy than the simple strings which Cucumber provides.
 
-# == Scalar transforms
+##
+# @defgroup Scalar transforms
 # Convert inputs into basic Ruby data types which represent a single value
+##
 
 # Integers
 Transform /\A(-?\d+)\z/ do |number|
@@ -31,8 +35,10 @@ Transform /^#{DATE}T#{TIME}#{MILLIS}#{TZ}$/ do |date|
           Time.parse(date)
 end
 
-# == Structure transforms
+##
+# @defgroup Structure transforms
 # Converts inputs to general data structures
+##
 
 # Lists
 Transform /\A\[.*\]\z/m do |input|
@@ -46,8 +52,10 @@ Transform /\A{.*}\z$/m do |input|
     JSON.parse(input)
 end
 
-# == Atypical transforms
+##
+# @defgroup Atypical transforms
 # Transforms for which data type is not the primary focus
+##
 
 # Whitespace removal transforms
 # Handle stripping leading and trailing whitespace.