brine-dsl 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 90f218b8154747a97c408360872b4dd8ba4a3be9
-  data.tar.gz: cd5eefa092fd1177ee60feb2960c234f29c079b1
+  metadata.gz: 690350fecddec6e5978bcb684189f2ac742a7918
+  data.tar.gz: 6a37f34f8424ac9422517f3cc0282cb8eb5b321d
 SHA512:
-  metadata.gz: 182d3f8d311d2fa0b3c9dda73e6538de268492d1b0610b1f4cd826402e949f8d55d85e52216cedd3e1673e6ecc599aefb4b16e2a017070b000b59178ea4c5d82
-  data.tar.gz: 1645d45e940081720a945904248cb647e5296a032e01b04ded450e8b6612cb0c8060d4f68ec2966ca8c661ef2c5078cb24a8c69b4f6384993b431ecc1b88d025
+  metadata.gz: 41b4ddf87394b647485b3ae8f77c517742661330583650eebf980e52050b2b8878f6d27c150613682e4da04b3ad0c109c62d97018a36effcb698e4f5bda3caae
+  data.tar.gz: 786aa5afef5cca973ac32c12b5fac728810da1d1eeface795254ac9d61f2b1f14b6fb4978c7f14463616f7342f45e30aabe02b566e32af09b64e9e2687a9e326

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    brine-dsl (0.9.0)
+    brine-dsl (0.10.2.pre.SNAPSHOT)
       cucumber (~> 2.4)
       faraday (~> 0.12)
       faraday_middleware (~> 0.12)

data/Rakefile

@@ -2,7 +2,7 @@
 require 'bundler'
 require 'cucumber/rake/task'
 
- Cucumber::Rake::Task.new(:check) do |t|
+Cucumber::Rake::Task.new(:check) do |t|
   # Cucumber needs some help to deal with the features and support being split.
   t.libs = "#{__dir__}"
 end

data/brine-dsl.gemspec

@@ -2,8 +2,7 @@
 raise 'VERSION must be specified in environment' unless ENV['VERSION']
 Gem::Specification.new do |s|
   s.name         = 'brine-dsl'
-  s.version      = '0.9.0'
-#  s.version      = ENV['VERSION']
+  s.version      = ENV['VERSION'][1..-1]
   s.platform     = Gem::Platform::RUBY
   s.authors      = ["Matt Whipple"]
   s.email        = ["mwhipple@brightcove.com"]

data/lib/brine/cleaning_up.rb

@@ -0,0 +1,120 @@
+##
+# @file cleaning_up.rb
+# Clean up resources created during test run.
+#
+# Will issue DELETE call for all tracked URLs which will normally be triggered
+# in a hook.
+#
+# The present approach for this is to explicitly track created resources to
+# which DELETE calls will be sent. Cleaning up of resources will be given some
+# further attention in the future, but this functionality should be preserved.
+##
+
+module Brine
+
+  ##
+  # A module providing resource cleanup.
+  #
+  # Exposes methods to keep a stack of DeleteCommands corresponding to each
+  # created resource which are then popped and invoked to perform the cleanup.
+  #
+  # LIFO behavior is adopted as it is more likely to preserve integrity,
+  # such as removing children added to parents or similar dependencies.
+  ##
+  module CleaningUp
+
+    ##
+    # A command object for the delete which will be executed as part of cleaning up.
+    #
+    # The command will be retried a specified number of times if an unsuccessful status code is received.
+    ##
+    class DeleteCommand
+
+      ##
+      # Construct a command with the required paramters to perform the delete.
+      #
+      # @param [Faraday::Connection, #delete] client The Faraday client which will send the delete message.
+      # @param [String] path The path of the resource to be deleted.
+      # @param [Array<Integer>] oks The response status codes which will be considered successful.
+      # @param [Integer] attempts The number of times this command should be tried.
+      ##
+      def initialize(client, path, oks: [200,204], attempts: 3)
+        @client = client
+        @path = path
+        @oks = oks
+        @attempts = attempts
+      end
+
+      ##
+      # Issue the delete based on the parameters provided during construction.
+      #
+      # @return [Boolean] true if a successful response is obtained, otherwise false.
+      ##
+      def cleanup
+        for _ in 1..@attempts
+          begin
+            resp=@client.delete(@path)
+            return true if @oks.include?(resp.status)
+          rescue ex
+            STDERR.puts "WARNING: #{ex}"
+          end
+        end
+        STDERR.puts "ERROR: Could not DELETE #{@path}"
+        false
+      end
+    end
+
+    ##
+    # Set the Faraday HTTP client object used to issue DELETE calls.
+    #
+    # The client provided will be subsequently used to create DeleteCommands.
+    # This can be called multiple times where each DeleteCommand will use the
+    # most recently set value. In most use cases this will also be the client
+    # used to issue the creation requests and could therefore be passed to this
+    # method prior to use.
+    #
+    # @param [Faraday::Connection, #delete] client The client to use to DELETE subsequently tracked resources.
+    ##
+    def set_cleaning_client(client)
+      @client = client
+    end
+
+    ##
+    # Record resource to be later cleaned (pushes a DeleteCommand).
+    #
+    # @param [String] path The path for the created resource; will be issued a DELETE.
+    ##
+    def track_created_resource(path)
+      cleanup_commands << DeleteCommand.new(@client, path)
+    end
+
+    ##
+    # Clean recorded resources (normally after a test run).
+    #
+    # @return [Boolean] true if all commands succeeded successfully, otherwise false.
+    ##
+    def cleanup_created_resources
+      # Avoid the use of any short circuiting folds.
+      cleanup_commands.reverse.inject(true) { |accum, x| accum && x.cleanup }
+    end
+
+    private
+
+    ##
+    # The array which serves as the stack of DeleteCommands.
+    #
+    # Provides the property mixed in by the module.
+    #
+    # @return [Array<DeleteCommand>]
+    ##
+    def cleanup_commands
+      @cleanup_commands ||= []
+    end
+
+  end
+
+  ##
+  # Mix the CleaningUp module functionality into the main Brine module.
+  ##
+  include CleaningUp
+end

data/lib/brine/client_building.rb

@@ -0,0 +1,123 @@
+##
+# @file client_building.rb
+# Construction of a Faraday connection.
+##
+
+module Brine
+
+  ##
+  # Supports construction of a Faraday connection with some common middleware.
+  ##
+  module ClientBuilding
+    require 'oauth2'
+
+    ##
+    # Parameter object used to configure OAuth2 middleware
+    #
+    # This is essentially a thin wrapper around `https://github.com/oauth-xx/oauth2`
+    # to provide a mini-DSL and to facilitate the middleware configuration.
+    ##
+    class OAuth2Params
+
+      ##
+      # A token which has been retrieved from the authorization server.
+      ##
+      attr_accessor :token
+
+      ##
+      # The type of OAuth2 token which will be retrieved.
+      #
+      # Currently only `bearer` is supported.
+      ##
+      attr_accessor :token_type
+
+      ##
+      # Instantiate a new object with default attributes.
+      ##
+      def initialize
+        @token_type = 'bearer'
+      end
+
+      ##
+      # Fetch an OAuth2 token based on configuration and store as `token`.
+      #
+      # The parameters are forwarded to OAuth2::Client.new which is used to
+      # retrieve the token.
+      #
+      # @param [String] id The login id to send to request authorization.
+      # @param [String] secret The secret to send to request authorization.
+      # @param [Hash] opts Options with which to create a client,
+      #                   see `https://github.com/oauth-xx/oauth2/blob/master/lib/oauth2/client.rb` for full details,
+      #                   common options will be duplicated here.
+      # @option opts [String] :site The OAuth2 authorization server from which to request a token.
+      # @option opts [String] :token_url The absolute or relative path to the Token endpoint on the authorization server.
+      # @option opts [Hash] :ssl SSL options to pass through to the transport client,
+      #                     `{verify: false}` may be useful for self-signed certificates.
+      ##
+      def fetch_from(id, secret, opts)
+        @token = OAuth2::Client.new(id, secret, opts)
+          .client_credentials.get_token.token
+      end
+    end
+
+    ##
+    # Acquire an OAuth2 token within provided configuration block.
+    #
+    # @param [Block] Logic to execute with an OAuth2Params receiver;
+    #               this will normally involve an OAuth2Params#fetch_from call.
+    ##
+    def use_oauth2_token(&block)
+      @oauth2 = OAuth2Params.new
+      @oauth2.instance_eval(&block)
+    end
+
+    ##
+    # The handlers/middleware that will be wired while constructing a client.
+    #
+    # This is represented as list of functions so that it can be more easily customized for
+    # unexpected use cases.
+    # It should likely be broken up a bit more sensibly and more useful insertion commands added...
+    # but it's likely enough of a power feature and platform specific to leave pretty raw.
+    ##
+    def connection_handlers
+      @connection_handlers ||= [
+        proc do |conn|
+          conn.request :json
+          if @oauth2
+            conn.request :oauth2, @oauth2.token, :token_type => @oauth2.token_type
+          end
+        end,
+        proc do |conn|
+          if @logging
+            conn.response :logger, nil, :bodies => (@logging.casecmp('DEBUG') == 0)
+          end
+          conn.response :json, :content_type => /\bjson$/
+        end,
+        proc{|conn| conn.adapter Faraday.default_adapter }
+      ]
+    end
+
+    ##
+    # Construct a new client to send requests to `host`.
+    #
+    # Will configure the client using `#connection_handlers`.
+    #
+    # @param [String] host The hostname to which this client will send requests.
+    # @param [String] logging Indicate the desired logging level for this client.
+    # @return [Faraday::Connection] The configured client connection.
+    ##
+    def client_for_host(host, logging: ENV['BRINE_LOG_HTTP'])
+      @logging = logging
+      Faraday.new(host) do |conn|
+        connection_handlers.each{|h| h.call(conn) }
+      end
+    end
+
+  end
+
+  ##
+  # Mix the ClientBuilding module functionality into the main Brine module.
+  ##
+  include ClientBuilding
+
+end

data/lib/brine/coercing.rb

@@ -0,0 +1,91 @@
+##
+# @file coering.rb
+# Type coercion to support assertions.
+##
+
+module Brine
+
+  ##
+  # A module which allows mixing in Corcer behavior.
+  ##
+  module Coercing
+
+    ##
+    # Coerces the types of  provided objects to support desired assertions.
+    #
+    # 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
+    # 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
+    # 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.
+    #
+    # Implementation (Most of the non-implementation info should later be moved).
+    # ---
+    # Internally the Coercer is a wrapper around a map of coercion functions
+    # where the keys are the pairs of classes for the operands and the
+    # values are the functions which accept a pair of instances (ostensibly) of the
+    # classes and return a pair of transformed values. The default coercion function
+    # returns the inputs unmodified (a nop), so any pair of classes which does not
+    # have a key will pass through unchanged.
+    #
+    # Note that this relies solely on the hash lookup and does not attempt any kind
+    # of inheritance lookup or similar. The current thinking is that there should be
+    # few expected types and lineage could be covered through explicit keys so the
+    # simple, dumb approach is likely sufficient.
+    ##
+    class Coercer
+
+      ##
+      # Instantiate a new Coercer.
+      #
+      # Initialize the standard map of coercion functions.
+      ##
+      def initialize
+        @map = Hash.new(->(lhs, rhs){[lhs, rhs]})
+        @map[[String, Time]] = ->(lhs, rhs){[Time.parse(lhs), rhs]}
+      end
+
+      ##
+      # Coerce the provided inputs as needed.
+      #
+      # 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.
+      ##
+      def coerce(first, second)
+        @map[[first.class, second.class]].call(first, second)
+      end
+    end
+
+    ##
+    # The coercer instance mixed in as a property.
+    #
+    # Will instantiate a Coercer if needed on first access.
+    #
+    # @return [Coercer] The object which will be used to handle coercions.
+    ##
+    def coercer
+      @coercer ||= Coercer.new
+    end
+
+  end
+
+  ##
+  # Include the Coercing module functionality into the main Brine module.
+  ##
+  include Coercing
+end

data/lib/brine/hooks.rb

@@ -1,4 +1,11 @@
-# Call CleanerUpper after test run
+##
+# @file hooks.rb
+# Cucumber hook callbacks used by Brine.
+##
+
+##
+# Call CleanerUpper after the test run.
+##
 After do
   cleanup_created_resources
 end

data/lib/brine/mustache_expanding.rb

@@ -0,0 +1,51 @@
+##
+# @file mustache_expanding.rb
+# Support for expanding Mustache templates with a defined binding.
+##
+
+module Brine
+
+  ##
+  # Provides a binding environment and template expansion that uses that environment.
+  ##
+  module MustacheExpanding
+    require 'mustache'
+
+    ##
+    # Mutable hash which serves as binding environment.
+    #
+    # @return [Hash<String, Object>] The active binding environment.
+    ##
+    def binding
+      @binding ||= {}
+    end
+
+    ##
+    # 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.
+    ##
+    def bind(key, value)
+      STDERR.puts "Assigning #{value} to #{key}" if ENV['BRINE_LOG_BINDING']
+      binding[key] = value
+    end
+
+    ##
+    # Expanded Mustache template using binding environment.
+    # Mustache in...no Mustache out.
+    #
+    # @param [String] template Template content to expand with binding.
+    # @return [String] The contents of `template` with any expansions done using `binding`.
+    ##
+    def shave_value(template)
+      Mustache.render(template, binding)
+    end
+
+  end
+
+  ##
+  # Include the MustacheExpanding module functionality into the main Brine module.
+  ##
+  include MustacheExpanding
+end

data/lib/brine/performing.rb

@@ -0,0 +1,159 @@
+##
+# @file performing.rb
+# Performing of of potentially deferred actions.
+##
+
+module Brine
+
+  ##
+  # A module supporting either immediate or defered evaluation of logic.
+  ##
+  module Performing
+
+    ##
+    # A passthrough performer which immediately invokes 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.
+    ##
+    class ImmediatePerformer
+
+      ##
+      # Perform the provided actions immediately.
+      #
+      # @param [Proc] A thunk of actions to be performed.
+      ##
+      def perform(actions)
+        actions.call
+      end
+    end
+
+    ##
+    # A Peformer which collects rather than evaluating actions.
+    ##
+    class CollectingPerformer
+
+      ##
+      # Construct an instance with an empty collection of actions.
+      ##
+      def initialize
+        @actions = []
+      end
+
+      ##
+      # Collect provided actions for later evaluation.
+      #
+      # @param [Proc] A thunk of actions to be performed.
+      ##
+      def perform(actions)
+        @actions << actions
+      end
+
+      ##
+      # Evaluate the collected actions in sequence.
+      ##
+      def evaluate
+        @actions.each { |it| it.call }
+      end
+
+    end
+
+    ##
+    # The currently active Performer instance exposed 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.
+    ##
+    def performer
+      @performer || reset_performer
+    end
+
+    ##
+    # Reset the Performer instance to the default implementation.
+    #
+    # @return [Performer, #perform] The default implementation which will now be the `performer`.
+    ##
+    def reset_performer
+      @performer = ImmediatePerformer.new
+    end
+
+    ##
+    # Pass the actions to the current Performer instance.
+    #
+    # @param [Proc] The thunk of the actions to be performed.
+    ##
+    def perform(&actions)
+      performer.perform(actions)
+    end
+
+    ##
+    # Begin collecting, rather than immediately performing, actions.
+    ##
+    def collect_actions
+      @performer = CollectingPerformer.new
+    end
+
+    ##
+    # The number of seconds between polling attempts.
+    #
+    # 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.
+    ##
+    def poll_interval_seconds
+      ENV['BRINE_POLL_INTERVAL_SECONDS'] || 0.25
+    end
+
+    ##
+    # Retry the provided block for the specified period.
+    #
+    # If the provided block is evaluated successfully the result
+    # 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.
+    # @return [Object] The result of the block if successfully evaluated.
+    # @throws [Exception] The most recent exception thrown from the block if never successfully evaluated.
+    ##
+    def poll_for(seconds, interval=poll_interval_seconds)
+      failure = nil
+      quit = Time.now + seconds
+      while (Time.now < quit)
+        begin
+          return yield
+        rescue Exception => ex
+          failure = ex
+          sleep interval
+        end
+      end
+      raise failure
+    end
+
+    ##
+    # 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.
+    ##
+    def retrieve_duration(duration)
+      if ENV["BRINE_DURATION_SECONDS_#{duration}"]
+        ENV["BRINE_DURATION_SECONDS_#{duration}"].to_f
+      else
+        STDERR.puts("Duration #{duration} not defined")
+      end
+    end
+
+  end
+
+  ##
+  # Mix the Performing module functionality into the main Brine module.
+  ##
+  include Performing
+end