brine-dsl 0.9.0 → 0.10.0

data/lib/brine/type_checking.rb

@@ -0,0 +1,88 @@
+##
+# @file type_checking.rb
+# Checks whether provided values are instances of a specified type.
+#
+# Provides validation for an extended set of types supported byJSON.
+##
+
+module Brine
+
+  ##
+  # Module which adds functionality to check the type of values.
+  ##
+  module TypeChecking
+
+    require 'rspec/expectations'
+ 
+    ##
+    # A registry of checks for types which can return a Matcher for provided types.
+    ##
+    class TypeChecks
+      include RSpec::Matchers
+
+      ##
+      # Initialize an instance with default checks or those provided.
+      #
+      # @param [Hash<String, Matcher>] A hash of Matchers by type, where the Matcher value will be
+      #                                used as the Matcher for the specified type.
+      #                                It is expected that no map will be provided and the default
+      #                                mapping will therefore be used.
+      ##
+      def initialize(map={Object: be_a_kind_of(Hash),
+                          String: be_a_kind_of(String),
+                          Number: be_a_kind_of(Numeric),
+                          Integer: be_a_kind_of(Integer),
+                          Array: be_a_kind_of(Array),
+                          DateTime: be_a_kind_of(Time),
+                          Boolean: satisfy{|it| it == true || it == false } })
+        @map = map
+      end
+
+      ##
+      # Return the Matcher for the specified type or die if not present.
+      #
+      # @param [Class] type The type whose Matcher should be returned.
+      # @return [RSpec::Matcher] The Matcher configured for `type`.
+      # @throw Exception if no Matcher exists for `type`.
+      ##
+      def for_type(type)
+        @map[type.to_sym] || raise("Unsupported type #{type}")
+      end
+
+      ##
+      # Register the provided matcher for the specified type.
+      #
+      # @param[Class] type The type for which the Matcher will be registered.
+      # @param[RSpec::Matcher] matcher A matcher to verify that input is an instance of type.
+      ##
+      def register_matcher(type, matcher)
+        @map[type.to_sym] = matcher
+      end
+    end
+
+    ##
+    # The currently active TypeCheck instance as a property, instantiating as needed.
+    ##
+    def type_checks
+      @type_check ||= TypeChecks.new
+    end
+
+    ##
+    # Return the Matcher for the specified type.
+    #
+    # This is the primary interface for type_checking to the rest of the system,
+    # and is the only one expected to be used during test execution.
+    #
+    # @param [Class] type The type for which a Matcher should be returned.
+    # @return [RSpec::Matcher] The Matcher currently registered for the type.
+    ##
+    def type_check_for(type)
+      type_checks.for_type(type)
+    end
+  end
+
+  ##
+  # Mix the TypeChecking module functionality into the main Brine module.
+  ##
+  include TypeChecking
+end

data/lib/brine/util.rb

@@ -1,4 +1,5 @@
 # Assorted utility functions
+# The deprecation piece should be extracted and the rest considered dead.
 module BrineUtil
   # reevaluate passed block until it returns without throwing an exception
   # or `time` elapses; retry every `interval`

data/lib/brine.rb

@@ -5,40 +5,33 @@
 # The primary goal of this file is to load all resources needed to use brine.
 # A secondary goal which should inform how that is done is that loading this
 # file by itself should provide new objects but not otherwise impact existing
-# state such as by  modifying the World or defining any Steps, Transforms, etc.
+# state such as by modifying the World or defining any Steps, Transforms, etc.
 # Those types of changes should be done by @ref #brine_mix.
-
-require 'brine/cleaner_upper'
-require 'brine/mustache_binder'
-require 'brine/requester'
-require 'brine/util'
-require 'brine/selector'
-require 'brine/type_checks'
-
 ##
-# Meta-module for modules to mix into World.
-module Brine
-  include CleanerUpper
-  include MustacheBinder
-  include Requesting
-  include BrineUtil
-  include Selection
-  include TypeChecking
-end
+
+require 'brine/cleaning_up'
+require 'brine/mustache_expanding'
+require 'brine/performing'
+require 'brine/requesting'
+require 'brine/selecting'
+require 'brine/type_checking'
 
 ##
-# Load the files with side effects and return @ref Brine.
+# Load the files with side effects.
 #
 # Expected to be called as `World(brine_mix)`
+# @return [module] The `Brine` module.
+##
 def brine_mix
   require 'brine/step_definitions/assignment'
   require 'brine/step_definitions/request_construction'
   require 'brine/step_definitions/assertions'
   require 'brine/step_definitions/cleanup'
+  require 'brine/step_definitions/perform'
   require 'brine/step_definitions/selection'
 
   require 'brine/transforms'
-  require 'brine/rest_steps'
   require 'brine/hooks'
+
   Brine
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: brine-dsl
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Matt Whipple
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-05-28 00:00:00.000000000 Z
+date: 2019-05-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cucumber
@@ -137,21 +137,24 @@ files:
 - brine-dsl.gemspec
 - feature_setup.rb
 - lib/brine.rb
-- lib/brine/cleaner_upper.rb
-- lib/brine/coercer.rb
+- lib/brine/cleaning_up.rb
+- lib/brine/client_building.rb
+- lib/brine/coercing.rb
 - lib/brine/hooks.rb
-- lib/brine/mustache_binder.rb
-- lib/brine/requester.rb
+- lib/brine/mustache_expanding.rb
+- lib/brine/performing.rb
+- lib/brine/requesting.rb
 - lib/brine/rest_steps.rb
-- lib/brine/selector.rb
+- lib/brine/selecting.rb
 - lib/brine/step_definitions/assertions.rb
 - lib/brine/step_definitions/assignment.rb
 - lib/brine/step_definitions/cleanup.rb
+- lib/brine/step_definitions/perform.rb
 - lib/brine/step_definitions/request_construction.rb
 - lib/brine/step_definitions/selection.rb
 - lib/brine/test_steps.rb
 - lib/brine/transforms.rb
-- lib/brine/type_checks.rb
+- lib/brine/type_checking.rb
 - lib/brine/util.rb
 homepage: http://github.com/brightcove/brine
 licenses:
@@ -173,7 +176,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.2.3
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: Cucumber@REST in Brine

data/lib/brine/cleaner_upper.rb

@@ -1,101 +0,0 @@
-##
-# @file cleaner_upper.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.
-
-##
-# A command object for the delete which will be executed as part of cleaning up.
-class DeleteCommand
-
-  ##
-  # Construct a command with the required paramters to perform the delete.
-  #
-  # @param client The Faraday client which will send the delete message.
-  # @param path The path of the resource to be deleted.
-  # @param oks The response status codes which will be considered successful.
-  # @param attempts The number of times this command should be tried,
-  # retrying if an unsuccessful status code is received.
-  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.
-  #
-  # @returns true if a successful response is obtained, otherwise false.
-  def cleanup
-    while @attempts > 0
-      begin
-        resp=@client.delete(@path)
-        return true if @oks.include?(resp.status)
-      rescue ex
-        puts "WARNING: #{ex}"
-      end
-      @attempts -= 1
-    end
-    puts "ERROR: Could not DELETE #{@path}"
-    false
-  end
-end
-
-##
-# A mixin which provides 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.
-#
-# The LIFO behavior is adopted as it is more likely to preserve integrity,
-# such as removing children added to parents or similar dependencies.
-module CleanerUpper
-
-  ##
-  # 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 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 path - The path for the created resource, will be issued a DELETE.
-  def track_created_resource(path)
-    created_resources << DeleteCommand.new(@client, path)
-  end
-
-  ##
-  # Clean recorded resources (normally after a test run).
-  def cleanup_created_resources
-    created_resources.reverse.each{|it| it.cleanup}
-  end
-
-  private
-
-  ##
-  # The array which serves as the stack of DeleteCommands.
-  #
-  # Works as a "module provided property" which is a name I
-  # may have just made up.
-  #
-  # TODO: Find proper term for module provided property
-  # TODO: The name of this property seems sloppy as it contains commands.
-  def created_resources
-    @created_resources ||= []
-  end
-end

data/lib/brine/coercer.rb

@@ -1,68 +0,0 @@
-##
-# @file coercer.rb
-# Type coercion to support assertions.
-
-##
-# 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.
-# TODO: Document this in a friendlier place, with a contrived example.
-# TODO: Having the default Time stuff should likely be removed for v2.
-#
-# 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 lhs - The left hand side input.
-  # @param rhs - The right hand side input.
-  # @returns A pair (2 element array) of potentially coerced values.
-  def coerce(lhs, rhs)
-    @map[[lhs.class, rhs.class]].call(lhs, rhs)
-  end
-end
-
-module Coercion
-  def coercer
-    @coercer ||= Coercer.new
-  end
-end

data/lib/brine/mustache_binder.rb

@@ -1,25 +0,0 @@
-require 'mustache'
-
-# Provides a binding environment and template expansion functions that use that
-# environment
-module MustacheBinder
-
-  # getter for mutable hash which serves as binding environment
-  def binding
-    @binding ||= {}
-  end
-
-  # assign `value' to `key' within binding
-  # defined in a method to allow observability/interception
-  def bind(key, value)
-    puts "Assigning #{value} to #{key}" if ENV['BRINE_LOG_BINDING']
-    binding[key] = value
-  end
-
-  # return value as expanded Mustache template using binding environment
-  # Mustache in...no Mustache out
-  def shave_value(val)
-    Mustache.render(val, binding)
-  end
-
-end

data/lib/brine/requester.rb

@@ -1,161 +0,0 @@
-##
-# @file requester.rb
-# Request construction and response storage
-##
-
-require 'oauth2'
-require 'faraday_middleware'
-require 'brine/util'
-
-##
-# 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.
-#
-# @return [String] The root URL to use or nil if none is provided.
-##
-def brine_root_url
-  if 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
-
-##
-# Parameter object used to configure OAuth2 middleware
-#
-# Also used to provide basic DSL for configuration
-##
-class OAuth2Params
-  attr_accessor :token, :token_type
-
-  def initialize
-    @token_type = 'bearer'
-  end
-
-  def fetch_from(id, secret, opts)
-    @token = OAuth2::Client.new(id, secret, opts)
-      .client_credentials.get_token.token
-  end
-end
-
-# Construct a Faraday client to be used to send built requests
-module ClientBuilding
-
-  # authenticate using provided info and save token for use in later requests
-  def use_oauth2_token(&block)
-    @oauth2 = OAuth2Params.new
-    @oauth2.instance_eval(&block)
-  end
-  
-  def with_oauth2_token(&block)
-    use_oauth2_token(&block)
-    self
-  end
-
-  # 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
-
-  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
-
-class ClientBuilder
-  include ClientBuilding
-end
-
-# Module in charge of constructing requests and saving responses
-module Requesting
-  include ClientBuilding
-
-  # Utility Methods
-  #
-  # Normalize an HTTP method passed from a specification into a form
-  # expected by the HTTP client library (lowercased symbol)
-  def parse_method(method)
-    method.downcase.to_sym
-  end
-
-  def set_client(client)
-    @client = client
-  end
-
-  # return Faraday client object so that it could be used directly
-  # or passed to another object
-  def client
-    @client ||= client_for_host(brine_root_url || 'http://localhost:8080',
-                                logging: ENV['BRINE_LOG_HTTP'])
-  end
-
-  # clear out any previously built request state and set defaults
-  def reset_request
-    @params = @headers = @body = nil
-  end
-
-  # store the provided body in the request options being built
-  # overriding any previously provided object
-  def set_request_body(obj)
-    @body = obj
-  end
-
-  # send a request using method to url using whatever options
-  # have been built for the present request
-  def send_request(method, url)
-    @response = client.run_request(method, url, @body, headers) do |req|
-      req.params = params
-    end
-  end
-
-  # getter for the latest response returned
-  def response
-    @response
-  end
-
-  def headers
-    @headers ||= {content_type: 'application/json'}
-  end
-
-  def add_header(k, v)
-    headers[k] = v
-  end
-
-  def params
-    @params ||= {}
-  end
-
-  def add_request_param(k, v)
-    params[k] = v
-  end
-
-end
-
-class Requester
-  include Requesting
-end

data/lib/brine/selector.rb

@@ -1,66 +0,0 @@
-require 'brine/coercer'
-require 'rspec/expectations'
-require 'jsonpath'
-
-# Selectors here are small wrappers around RSpec
-# expectation behavior to encapsulate variations in
-# some expecation associated behavior in classes.
-class Selector
-  include RSpec::Matchers
-  attr_accessor :coercer
-
-  def initialize(target, negated)
-    @target = target
-    @message = negated ? :to_not : :to
-  end
-
-  def filter_matcher(matcher)
-    matcher
-  end
-
-  def assert_that(value)
-    target, value = coercer.coerce(@target, value)
-    matcher = filter_matcher(yield(value))
-    expect(target).send(@message, matcher)
-  end
-end
-
-class AnySelector < Selector
-  def filter_matcher(matcher)
-    include(matcher)
-  end
-end
-
-class AllSelector < Selector
-  def filter_matcher(matcher)
-    all(matcher)
-  end
-end
-
-#
-# Module
-#
-module Selection
-  include Coercion
-  attr_reader :selector
-
-  def use_selector(selector)
-    selector.coercer = coercer
-    @selector = selector
-  end
-end
-
-#
-# Steps
-#
-RESPONSE_ATTRIBUTES='(status|headers|body)'
-Then(/^the value of `([^`]*)` is( not)? (.*)$/) do |value, negated, assertion|
-  use_selector(Selector.new(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/type_checks.rb

@@ -1,36 +0,0 @@
-# type_checks.rb -- checks whether provided is a valid instance of a specified type
-#
-# Provides validation for standard JSON type
-
-require 'rspec/expectations'
-
-# This will be made extensible so it can replace current domain specific check logic
-class TypeChecks
-  include RSpec::Matchers
-
-  def initialize
-    @map = {
-      Object: be_a_kind_of(Hash),
-      String: be_a_kind_of(String),
-      Number: be_a_kind_of(Numeric),
-      Integer: be_a_kind_of(Integer),
-      Array: be_a_kind_of(Array),
-      DateTime: be_a_kind_of(Time),
-      Boolean: satisfy{|it| it == true || it == false }
-    }
-  end
-
-  def for_type(type)
-    @map[type.to_sym] || raise("Unsupported type #{type}")
-  end
-end
-
-module TypeChecking
-  def type_checks
-    @type_check ||= TypeChecks.new
-  end
-
-  def type_check_for(type)
-    type_checks.for_type(type)
-  end
-end