brine-dsl 0.11.0 → 0.12.0

data/lib/brine/coercing.rb

@@ -1,35 +1,35 @@
 ##
 # @file coering.rb
-# Type coercion to support assertions.
+# Coerce types to support assertions.
 ##
 
 module Brine
 
   ##
-  # A module which allows mixing in Corcer behavior.
+  # Provide type coercion.
   ##
   module Coercing
 
     ##
-    # Coerces the types of  provided objects to support desired assertions.
+    # Coerces the types of provided objects to support assertion evaluation.
     #
     # Coercion is used to support handling richer data types in Brine without
     # introducing noisy type information to the language.
-    # Argument Transforms can be used to convert input provided directly
+    # Transformation code can be used to convert input provided directly
     # to a Brine step, however data extracted from JSON will by default be
     # limited to the small amount of JSON supported data types. As normally
     # the data extracted from JSON will only be directly present on one side
     # of the assertion (most likely the left), the simpler JSON data types can
     # be coerced to a richer type based on the right hand side.
     #
-    # A standard example (and that which is defined at the moment here) is date/time
+    # A standard example (and one which is supported in this file) is date/time
     # values. When testing an API that returns such values it is likely desirable to
     # perform assertions with proper date/time semantics, and the coercer allows
     # such assertions against a value retrieved out of a JSON structure.
     #
-    # The combination of Argument Transforms and the Coercer can also effectively
-    # allow for user defined types to seemlessly exist within the Brine tests.
-    # The date/time implementation is an example of this.
+    # The combination of transforming of ParameterType inputs and the Coercer can
+    # also effectively allow for user defined types to seemlessly exist within the
+    # Brine tests.
     #
     # Implementation (Most of the non-implementation info should later be moved).
     # ---
@@ -62,9 +62,9 @@ module Brine
       #
       # Looks up and invokes the associated coercion function.
       #
-      # @param [Object] first The first operand.
-      # @param [Object] second The second operand.
-      # @return [Array] A pair of the potentially coerced [first, second] values.
+      # @param first [Object] Provide the first operand.
+      # @param second [Object] Provide the second operand.
+      # @return [Array] Return the coerced [first, second] values.
       ##
       def coerce(first, second)
         @map[[first.class, second.class]].call(first, second)
@@ -73,11 +73,11 @@ module Brine
     end
 
     ##
-    # The coercer instance mixed in as a property.
+    # Expose a Coercer as a property.
     #
-    # Will instantiate a Coercer if needed on first access.
+    # A Coercer will be instantiated as needed on first access.
     #
-    # @return [Coercer] The object which will be used to handle coercions.
+    # @return [Coercer] Return the object which will be used to handle coercions.
     ##
     def coercer
       @coercer ||= Coercer.new
@@ -86,7 +86,7 @@ module Brine
   end
 
   ##
-  # Include the Coercing module functionality into the main Brine module.
+  # Mix the Coercing module functionality into the main Brine module.
   ##
   include Coercing
 end

data/lib/brine/hooks.rb

@@ -1,6 +1,6 @@
 ##
 # @file hooks.rb
-# Cucumber hook callbacks used by Brine.
+# Register Brine callbacks for Cucumber hooks.
 ##
 
 ##

data/lib/brine/mustache_expanding.rb

@@ -1,19 +1,19 @@
 ##
 # @file mustache_expanding.rb
-# Support for expanding Mustache templates with a defined binding.
+# Support expanding Mustache templates with a provided binding.
 ##
 module Brine
 
   ##
-  # Provides a binding environment and template expansion that uses that environment.
+  # Provide a binding environment and template expansion that can use such an environment.
   ##
   module MustacheExpanding
     require 'mustache'
 
     ##
-    # Mutable hash which serves as binding environment.
+    # Furnish a mutable hash to serve as a binding environment.
     #
-    # @return [Hash<String, Object>] The active binding environment.
+    # @return [Hash<String, Object>] Return the active binding environment.
     ##
     def binding
       @binding ||= {}
@@ -22,8 +22,8 @@ module Brine
     ##
     # Assign `value' to `key' within binding,
     #
-    # @param [String] key The key in the binding to which `value` will be assigned.
-    # @param [Object] value The value to assign to ``key` within the binding.
+    # @param key [String] Specify the key in the binding to which `value` will be assigned.
+    # @param value [Object] Specify the value to assign to ``key` within the binding.
     ##
     def bind(key, value)
       STDERR.puts "Assigning #{value} to #{key}" if ENV['BRINE_LOG_BINDING']
@@ -31,32 +31,30 @@ module Brine
     end
 
     ##
-    # Expanded Mustache template using binding environment.
+    # Provide an expandable Mustache template using binding environment.
     #
     # This exists to support latent expansion and template retrieval.
-    #
-    # @param [String] template Template content to expand with binding.
-    # @return [String] The contents of `template` with any expansions done using `binding`.
     ##
     class BrineTemplate < Mustache
 
       ##
-      # Instantiate a Brine template.
+      # Instantiate a BrineTemplate.
       #
-      # @param tmpl [String] The string content of the template.
-      # @param binding [Hash] A reference to the (mutable) binding.
+      # @param tmpl [String] Define the string content of the template.
       ##
-      def initialize(tmpl, binding)
+      def initialize(tmpl)
         @template = tmpl
-        @binding = binding
       end
 
       ##
-      # Expand the template using the current bindings.
+      # Expand the template using the provided bindings.
+      #
+      # @param binding [Hash] Provide bound values to use within the template.
+      # @return [String] Return the contents of this template applied against `binding`.
       ##
-      def expand
+      def expand(binding)
         begin
-          context.push(@binding)
+          context.push(binding)
           render
         ensure
           context.pop
@@ -66,22 +64,55 @@ module Brine
       ##
       # Stringify as template contents.
       #
-      # This supports cases such as dynamic steps
-      # where a string is expected but the template should not yet
-      # be expanded.
+      # This supports cases such as dynamic steps where a string is expected
+      # but the template should not yet be expanded.
       ##
       def to_s
         @template
       end
     end
 
+    ##
+    # Allow retrieval of BrineTemplates for provided template content.
+    #
+    # @param str [String] Define the string contents for the returned template.
+    # @return [BrineTemplate] Return a BrineTemplate with the provided content.
+    ##
     def as_template(str)
-      BrineTemplate.new(str, binding)
+      BrineTemplate.new(str)
     end
   end
 
   ##
-  # Include the MustacheExpanding module functionality into the main Brine module.
+  # Mix the MustacheExpanding module functionality into the main Brine module.
   ##
   include MustacheExpanding
 end
+
+##
+# Assign the provided value to the specified identifier.
+#
+# @param name [Object] Specify the identifier to which the value will be bound.
+# @param value [Object} Provide the value to bind to the identifier.
+##
+When('{grave_param} is assigned {grave_param}') do |name, value|
+  perform { bind(expand(name, binding), value) }
+end
+
+##
+# Assign a random string (UUID) to the specified identifier.
+#
+# @param name [Object] Specify the identifier to which a random string will be bound.
+##
+When('{grave_param} is assigned a random string') do |name|
+  perform { bind(expand(name, binding), SecureRandom.uuid) }
+end
+
+##
+# Assign a current timestamp to the specified identifier.
+#
+# @param name [Object] Specify the identifier to which the timestamp will be bound.
+##
+When('{grave_param} is assigned a timestamp') do |name|
+  perform { bind(expand(name, binding), DateTime.now) }
+end

data/lib/brine/performing.rb

@@ -1,27 +1,26 @@
 ##
 # @file performing.rb
-# Performing of of potentially deferred actions.
+# Perform potentially deferred actions.
 ##
-
 module Brine
 
   ##
-  # A module supporting either immediate or defered evaluation of logic.
+  # Support either immediate or defered evaluation of logic.
   ##
   module Performing
 
     ##
-    # A passthrough performer which immediately invokes provided actions.
+    # Immediately invoke provided actions.
     #
     # This has no instance state and therefore a Flyweight could be used,
-    # but too few instances are expected to warrant even the minor divergence.
+    # but too few instances are expected to warrant even the minor specialization.
     ##
     class ImmediatePerformer
 
       ##
       # Perform the provided actions immediately.
       #
-      # @param [Proc] A thunk of actions to be performed.
+      # @param [Proc] Provide actions to be performed.
       ##
       def perform(actions)
         actions.call
@@ -29,7 +28,7 @@ module Brine
     end
 
     ##
-    # A Peformer which collects rather than evaluating actions.
+    # Collect actions to be evaluated later.
     ##
     class CollectingPerformer
 
@@ -41,9 +40,9 @@ module Brine
       end
 
       ##
-      # Collect provided actions for later evaluation.
+      # Collect provided actions.
       #
-      # @param [Proc] A thunk of actions to be performed.
+      # @param actions [Proc] Provide actions to collect.
       ##
       def perform(actions)
         @actions << actions
@@ -59,11 +58,11 @@ module Brine
     end
 
     ##
-    # The currently active Performer instance exposed as a property.
+    # Expose the currently active Performer as a property.
     #
     # The default implementation will be wired as needed upon first access.
     #
-    # @return [Performer, #perform] The Performer to which actions will be sent.
+    # @return [Performer, #perform] Return the Performer to which actions will be sent.
     ##
     def performer
       @performer || reset_performer
@@ -72,16 +71,16 @@ module Brine
     ##
     # Reset the Performer instance to the default implementation.
     #
-    # @return [Performer, #perform] The default implementation which will now be the `performer`.
+    # @return [Performer, #perform] Return the default implementation which will now be the active Performer.
     ##
     def reset_performer
       @performer = ImmediatePerformer.new
     end
 
     ##
-    # Pass the actions to the current Performer instance.
+    # Pass the actions to the active Performer instance.
     #
-    # @param [Proc] The thunk of the actions to be performed.
+    # @param actions [Proc] The actions to pass to the Performer.
     ##
     def perform(&actions)
       performer.perform(actions)
@@ -95,12 +94,12 @@ module Brine
     end
 
     ##
-    # The number of seconds between polling attempts.
+    # Determine the number of seconds between polling attempts.
     #
-    # Can be provided by the `BRINE_POLL_INTERVAL_SECONDS` environment variable.
-    # Defaults to `0.5`.
+    # This can be provided by the `BRINE_POLL_INTERVAL_SECONDS` environment variable
+    # (defaults to `0.5`).
     #
-    # @return [Number] The number of seconds to sleep between poll attempts.
+    # @return [Number] Return the number of seconds to sleep between poll attempts.
     ##
     def poll_interval_seconds
       ENV['BRINE_POLL_INTERVAL_SECONDS'] || 0.25
@@ -113,11 +112,11 @@ module Brine
     # will be returned, if any exception is thrown it will be
     # retried until the period elapses.
     #
-    # @param [Number] seconds The period (in seconds) during which the block will be retried.
-    # @param [Number] interval How long to sleep between polling attempts, defaults to `#poll_interval_seconds`.
-    # @param [Block] The logic to retry within the defined period.
+    # @param seconds [Number] Define the period (in seconds) for which the block will be retried.
+    # @param interval [Number] Define how long to sleep between polling attempts (defaults to `#poll_interval_seconds`).
+    # @param [Block] Provide the logic to retry within the defined period.
     # @return [Object] The result of the block if successfully evaluated.
-    # @throws [Exception] The most recent exception thrown from the block if never successfully evaluated.
+    # @throws [Exception] Re-throws the most recent exception thrown from the block if never successfully evaluated.
     ##
     def poll_for(seconds, interval=poll_interval_seconds)
       failure = nil
@@ -134,13 +133,13 @@ module Brine
     end
 
     ##
-    # The duration in seconds for the given handle.
+    # Retrieve the duration in seconds for the given handle.
     #
     # Currently this only supports values provided through environment variables
     # of the format BRINE_DURATION_SECONDS_{handle}.
     #
-    # @param[String] duration The handle/name of the duration whose length should be returned.
-    # @return [Number] The number of seconds to poll for the requested duration.
+    # @param duration [String] Identify the duration whose length should be returned.
+    # @return [Number] Return the number of seconds defined for the requested duration.
     ##
     def retrieve_duration(duration)
       if ENV["BRINE_DURATION_SECONDS_#{duration}"]
@@ -157,3 +156,30 @@ module Brine
   ##
   include Performing
 end
+
+require 'brine/selecting.rb'
+
+##
+# Collect actions rather than immediately evaluating them.
+##
+When('actions are defined such that') do
+  collect_actions
+end
+
+##
+# Evaluate collected actions for the provided period.
+#
+# This will pass if any evaluation is successful within the specified time.
+#
+# @param negated [Boolean] Specify whether the assertion should be expected to fail.
+# @param period [Object] Specify the period length as returned by #retrieve_duration.
+##
+Then('the actions are{maybe_not} successful within a {grave_param} period') do |negated, period|
+  method = negated ? :to : :to_not
+  expect do
+    poll_for(retrieve_duration(expand(period, binding))) do
+      performer.evaluate
+    end
+  end.send(method, raise_error)
+  reset_performer
+end

data/lib/brine/requesting.rb

@@ -1,19 +1,18 @@
 ##
 # @file requesting.rb
-# Request construction and response storage.
+# Provide request construction and response storage.
 ##
-
 module Brine
 
   ##
-  # Module in charge of constructing requests and saving responses.
+  # Support constructing requests and saving responses.
   ##
   module Requesting
     require 'faraday_middleware'
     require 'brine/client_building'
 
     ##
-    # The root url to which Brine will send requests.
+    # Retrieve 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
@@ -21,7 +20,7 @@ module Brine
     #
     # @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.
+    # @return [String] Return the root URL to use or nil if none is provided.
     ##
     def brine_root_url
       if @brine_root_url
@@ -37,8 +36,8 @@ module Brine
     ##
     # 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.
+    # @param method [String] Provide a text representation of the HTTP method.
+    # @return [Symbol] Return `method` in a form potentially usable by the HTTP client library.
     ##
     def parse_method(method)
       method.downcase.to_sym
@@ -49,19 +48,19 @@ module Brine
     #
     # 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.
+    # @param client [Faraday::Connection, #run_request] Provide 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.
+    # Return 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.
+    # @return [Faraday::Connection, #run_request] Return the active HTTP client.
     ##
     def client
       @client ||= client_for_host(brine_root_url)
@@ -82,7 +81,7 @@ module Brine
     #
     # This will override any previous body value.
     #
-    # @param [Object] The new data to be placed in the request body.
+    # @param obj [Object] Provide the data to place in the request body.
     ##
     def set_request_body(obj)
       @body = obj
@@ -99,9 +98,8 @@ module Brine
     # 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.
+    # @param method [Symbol] Provide the HTTP method for the request such as returned by #parse_method.
+    # @param url [String] Specify the url to which the request will be sent.
     ##
     def send_request(method, url)
       @response = client.run_request(method, url, @body, headers) do |req|
@@ -110,21 +108,21 @@ module Brine
     end
 
     ##
-    # The response for the last sent request.
+    # Return the response for the last sent request.
     #
-    # @return [Faraday::Response] The most recent response.
+    # @return [Faraday::Response] Return the most recent response.
     ##
     def response
       @response
     end
 
     ##
-    # The headers for the request currently being built.
+    # Expose the headers for the request currently being built.
     #
-    # Will be initialized as needed on first access,
+    # This 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.
+    # @return [Hash] Return the headers to use for the constructed request.
     ##
     def headers
       @headers ||= {content_type: 'application/json'}
@@ -133,8 +131,8 @@ module Brine
     ##
     # 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.
+    # @param k [String] Specify the name of the header whose value will be set.
+    # @param v [Object] Provide 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)
@@ -142,11 +140,11 @@ module Brine
     end
 
     ##
-    # The query parameters which will be attached to the constructeed request.
+    # Expose the query parameters which will be attached to the constructeed request.
     #
-    # Will be initialized to an empty hash as needed upon first access.
+    # This will be initialized to an empty hash as needed upon first access.
     #
-    # @return [Hash] The query parameters to use for request construction.
+    # @return [Hash] Return the query parameters to use for the constructed request.
     ##
     def request_params
       @request_params ||= {}
@@ -155,8 +153,8 @@ module Brine
     ##
     # 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).
+    # @param k [String] Specify the name of the query parameter whose value is being assigned.
+    # @param v [Object] Provide the value to assign the query parameter (normally a String).
     ##
     def set_request_param(k, v)
       request_params[k] = v
@@ -169,3 +167,76 @@ module Brine
   ##
   include Requesting
 end
+
+require 'brine/selecting'
+require 'brine/transforming'
+
+##
+# Define a body for the request currently under construction.
+#
+# @param input [String] Define the body contents to use in the request.
+##
+When('the request body is assigned:') do |input|
+  perform { set_request_body(input) }
+end
+
+##
+# Define the indicated query parameter value for the request currently under construction.
+#
+# @param param [Object] Specify the name of the query parameter whose value will be set.
+# @param value [Object] Specify the value to set for the named query parameter.
+##
+When('the request query parameter {grave_param} is assigned {grave_param}') do |param, value|
+  perform { set_request_param(param, value) }
+end
+
+##
+# Define the indicated header value for the request currently under construction.
+#
+# @param header [Object] Specify the name of the header whose value will be set.
+# @param value [Object] Specify the value to set for the named header.
+##
+When('the request header {grave_param} is assigned {grave_param}') do |header, value|
+  perform { set_header(header, value) }
+end
+
+##
+# Issue a request with the provided method to the specified url.
+#
+# Bind the returned response.
+#
+# @param method [String] Specify the HTTP method to use for the request.
+# @param url [Object] Specify the URL to which the request will be sent.
+##
+When('a(n) {http_method} is sent to {grave_param}') do |method, url|
+  perform do
+    send_request(parse_method(method), URI.escape(expand(url, binding)))
+    bind('response', response)
+    reset_request
+  end
+end
+
+##
+# Attach a HTTP Basic Auth header to the request currently under construction.
+#
+# @param user [Object] Specify the user with which to generate the header.
+# @param password [Object] Specify the password with which to generate the header.
+##
+When('the request credentials are set for basic auth user {grave_param} and password {grave_param}') do |user, password|
+  perform do
+    base64_combined = Base64.strict_encode64("#{expand(user, binding)}:#{expand(password, binding)}")
+    set_header('Authorization', "Basic #{base64_combined}")
+  end
+end
+
+##
+# Assign a value extracted from a response attribute to the specified identifier.
+#
+# @param name [Object] Specify the identifier to which the value will be bound.
+# @param attribute [String] Specify the attribute from which the value will be retrieved.
+# @param traversal [Traversal] Provide a traversal to fetch the value out of the attribute.
+##
+When('{grave_param} is assigned the response {response_attribute}{traversal}') do
+  |name, attribute, traversal|
+  perform { bind(expand(name, binding), traversal.visit(response_attribute(attribute))) }
+end