brine-dsl 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 906c5a5791f773d74511eb23f0dd53a1ee25f29d3e7b4318f8b1b2f4299c5696
-  data.tar.gz: 06d1b4ffc9d6a745f06b2ebb7c6164b650d3c5fa6d6cd918dcb9c406a1b98656
+  metadata.gz: a06ae7bee936f1179d45feff647eba71a2bb10832bba886861e0da74b81b68d5
+  data.tar.gz: 35dcc3f58a97e4ff814e84bed8e40d091405eb4a05f5b321212f3d0ed16b2a67
 SHA512:
-  metadata.gz: d94513fc23ac9e9d5d21e45641821c1e90e9b06245947d68007277e033efff64fc6bc2054750e0d451c8455c8088614a52621cd63e45f3b925ef20171f8be7c0
-  data.tar.gz: 3395d12a8fd7c8ee1b3df7e86474807ec3c666e49a3d6c974f77dad51d5175b87ece0ecbc016cd823e1beb7feba8357ec2067a4a2167400405478e444cffab6a
+  metadata.gz: 5105f8cd19c33eaf6f31d4daf366cb5219e5000452c50754a9fe570cc388ea9b3d2a42b51ee704bb8da70534822c86faa253461a7892172faa1f0961f53119d7
+  data.tar.gz: 15a09e7bd10ae9bfc4692ae7d35bf31a0a0f51e15b599b4c2d67184fe7a6e7742537b4da41922a1951c642b7a01e097dbf6f4f60cc885faa717cc2946a624a6e

data/.ruby-version

@@ -1 +1 @@
-2.3.1
+2.5.5

data/Gemfile.lock

@@ -1,8 +1,8 @@
 PATH
   remote: .
   specs:
-    brine-dsl (0.11.0)
-      cucumber (~> 2.4)
+    brine-dsl (0.12.0)
+      cucumber (= 4.0.0.rc.1)
       faraday (~> 0.12)
       faraday_middleware (~> 0.12)
       jsonpath (~> 0.8)
@@ -13,24 +13,42 @@ PATH
 GEM
   remote: http://rubygems.org/
   specs:
+    backports (3.15.0)
     builder (3.2.3)
-    cucumber (2.99.0)
+    c21e (1.1.9)
+    cucumber (4.0.0.rc.1)
       builder (>= 2.1.2)
-      cucumber-core (~> 1.5.0)
-      cucumber-wire (~> 0.0.1)
-      diff-lcs (>= 1.1.3)
-      gherkin (~> 4.0)
+      cucumber-core (~> 4.0)
+      cucumber-expressions (~> 6.0, >= 6.0.1)
+      cucumber-formatter-dots (~> 1.0)
+      cucumber-wire (~> 1.0)
+      diff-lcs (~> 1.3)
+      gherkin (~> 6.0)
       multi_json (>= 1.7.5, < 2.0)
       multi_test (>= 0.1.2)
-    cucumber-core (1.5.0)
-      gherkin (~> 4.0)
-    cucumber-wire (0.0.1)
+    cucumber-core (4.0.0)
+      backports (>= 3.8.0)
+      cucumber-tag_expressions (~> 1.1.0)
+      gherkin (~> 6.0)
+    cucumber-expressions (6.6.2)
+    cucumber-formatter-dots (1.1.0)
+      cucumber-messages
+      os
+    cucumber-messages (2.1.2)
+      google-protobuf (>= 3.2, <= 3.7)
+    cucumber-tag_expressions (1.1.1)
+    cucumber-wire (1.0.0)
+      cucumber-core (~> 4.0)
+      cucumber-expressions (~> 6.0)
     diff-lcs (1.3)
-    faraday (0.15.4)
+    faraday (0.16.2)
       multipart-post (>= 1.2, < 3)
     faraday_middleware (0.13.1)
       faraday (>= 0.7.4, < 1.0)
-    gherkin (4.1.3)
+    gherkin (6.0.17)
+      c21e (~> 1.1.9)
+      cucumber-messages (~> 2.1.2)
+    google-protobuf (3.7.0)
     jsonpath (0.9.9)
       multi_json
       to_regexp (~> 0.2.1)
@@ -40,27 +58,28 @@ GEM
     multi_xml (0.6.0)
     multipart-post (2.1.1)
     mustache (1.1.0)
-    oauth2 (1.4.1)
-      faraday (>= 0.8, < 0.16.0)
+    oauth2 (1.4.2)
+      faraday (>= 0.8, < 2.0)
       jwt (>= 1.0, < 3.0)
       multi_json (~> 1.3)
       multi_xml (~> 0.5)
       rack (>= 1.2, < 3)
+    os (1.0.1)
     rack (2.0.7)
-    rake (12.3.2)
+    rake (12.3.3)
     rspec (3.8.0)
       rspec-core (~> 3.8.0)
       rspec-expectations (~> 3.8.0)
       rspec-mocks (~> 3.8.0)
-    rspec-core (3.8.1)
+    rspec-core (3.8.2)
       rspec-support (~> 3.8.0)
-    rspec-expectations (3.8.4)
+    rspec-expectations (3.8.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.8.0)
-    rspec-mocks (3.8.1)
+    rspec-mocks (3.8.2)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.8.0)
-    rspec-support (3.8.2)
+    rspec-support (3.8.3)
     to_regexp (0.2.1)
 
 PLATFORMS

data/brine-dsl.gemspec

@@ -13,15 +13,15 @@ Gem::Specification.new do |s|
 
   s.required_ruby_version = '>= 2.3.0'
 
-  s.add_runtime_dependency     'cucumber',           '~> 2.4'
-  s.add_runtime_dependency     'mustache',           '~> 1.0'
-  s.add_runtime_dependency     'oauth2',             '~> 1.4'
-  s.add_runtime_dependency     'rspec',              '~> 3.7'
-  s.add_runtime_dependency     'jsonpath',           '~> 0.8'
-  s.add_runtime_dependency     'faraday',            '~> 0.12'
-  s.add_runtime_dependency     'faraday_middleware', '~> 0.12'
+  s.add_runtime_dependency     'cucumber',            '4.0.0.rc.1'
+  s.add_runtime_dependency     'mustache',            '~> 1.0'
+  s.add_runtime_dependency     'oauth2',              '~> 1.4'
+  s.add_runtime_dependency     'rspec',               '~> 3.7'
+  s.add_runtime_dependency     'jsonpath',            '~> 0.8'
+  s.add_runtime_dependency     'faraday',             '~> 0.12'
+  s.add_runtime_dependency     'faraday_middleware',  '~> 0.12'
 
-  s.add_development_dependency 'rake',               '~> 12.3'
+  s.add_development_dependency 'rake',                '~> 12.3'
 
   s.files        = `git ls-files`.split("\n")
   s.test_files   = `git ls-files -- {test,spec,features}/*`.split("\n")

data/lib/brine.rb

@@ -1,37 +1,24 @@
 ##
 # @file brine.rb
-# Loader file for the rest of brine.
-#
-# 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.
-# Those types of changes should be done by @ref #brine_mix.
+# Support loading Brine into the World.
 ##
 
-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.
+# Load all Brine files into the World.
 #
 # Expected to be called as `World(brine_mix)`
-# @return [module] The `Brine` module.
+#
+# @return [module] Return 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/transforming'
+  require 'brine/assertions'
+  require 'brine/cleaning_up'
   require 'brine/hooks'
-
+  require 'brine/mustache_expanding'
+  require 'brine/performing'
+  require 'brine/requesting'
+  require 'brine/selecting'
+  require 'brine/transforming'
+  require 'brine/type_checking'
   Brine
 end

data/lib/brine/assertions.rb

@@ -0,0 +1,123 @@
+##
+# @file assertions.rb
+# Define assertion steps to be used with a Selector
+##
+
+require 'brine/transforming'
+
+##
+# Assert that the selected value is equal to the parameter.
+#
+# @param value [Object] Specify the value which the selection should equal.
+##
+Then('it is equal to {grave_param}') do |value|
+  perform { selector.assert_that(value, binding) {|v| eq v} }
+end
+
+##
+# Assert that the selected value is equal to the docstring.
+#
+# @param multi [String] Specify the value which the selection should equal.
+##
+Then('it is equal to:') do |value|
+  perform { selector.assert_that(transformed_parameter(value), binding) {|v| eq v} }
+end
+
+##
+# Assert that the selected value matches the parameter.
+#
+# @param value [Object] Specify the pattern which the selection should match.
+##
+Then('it is matching {grave_param}') do |value|
+  perform { selector.assert_that(value, binding) {|v| match v} }
+end
+
+##
+# Assert that the selected value matches the docstring.
+#
+# @param value [String] Specify the pattern which the selection should match.
+##
+Then('it is matching:') do |value|
+  perform { selector.assert_that(transformed_parameter(value), binding) {|v| match v} }
+end
+
+##
+# Assert that the selected value is greater than the parameter.
+#
+# @param value [Object] Specify the value which the selection should be greater than.
+##
+Then('it is greater than {grave_param}') do |value|
+  perform { selector.assert_that(value, binding) {|v| be > v} }
+end
+
+##
+# Assert that the selected value is greater than or equal to the parameter.
+#
+# @param value [Object] Specify the value which the selection should be greater than or equal to.
+##
+Then('it is greater than or equal to {grave_param}') do |value|
+  perform { selector.assert_that(value, binding) {|v| be >= v} }
+end
+
+##
+# Assert that the selected value is less than the parameter.
+#
+# @param value [Object] Specify the value which the selection should be less than.
+##
+Then('it is less than {grave_param}') do |value|
+  perform { selector.assert_that(value, binding) {|v| be < v} }
+end
+
+##
+# Assert that the selected value is less than or equal to the parameter.
+#
+# @param value [Object] Specify the value which the selection should be less than or equal to.
+##
+Then('it is less than or equal to {grave_param}') do |value|
+  perform { selector.assert_that(value, binding) {|v| be <= v} }
+end
+
+##
+# Assert that the selected value is empty.
+#
+# This will be satisfied by nil or any object which returns a truthy #empty?
+##
+Then('it is empty') do
+  perform { selector.assert_that(nil, binding) do
+    satisfy{|i| i.nil? || (i.respond_to?(:empty?) && i.empty?) }
+  end }
+end
+
+##
+# Assert that the selected value includes the parameter.
+#
+# @param value [Object] Specify content which should be within the selection.
+##
+Then('it is including {grave_param}') do |value|
+  perform { selector.assert_that(value, binding) {|v| include v } }
+end
+
+##
+# Assert that the selected value includes the docstring.
+#
+# @param value [String] Specify content which should be within the selection.
+##
+Then('it is including:') do |value|
+  perform { selector.assert_that(transformed_parameter(value), binding) {|v| include v } }
+end
+
+##
+# Asserted that the selected value has a length equal to the parameter.
+#
+# TODO: It may be better to support selection of the length attribute, maybe
+# chain to another dynamic step such as `is of lenth that is ...`
+#
+# @param length [Object] Specify the length which the selection should have.
+##
+Then('it is of length {grave_param}') do |length|
+  perform do
+    selector.assert_that(length, binding) do |l|
+      satisfy{|i| i.respond_to?(:length) && i.length == l}
+    end
+  end
+end

data/lib/brine/cleaning_up.rb

@@ -2,8 +2,7 @@
 # @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.
+# Issue DELETE calls for all tracked URLs: 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
@@ -13,9 +12,9 @@
 module Brine
 
   ##
-  # A module providing resource cleanup.
+  # Provide resource cleanup.
   #
-  # Exposes methods to keep a stack of DeleteCommands corresponding to each
+  # Expose 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,
@@ -24,7 +23,7 @@ module Brine
   module CleaningUp
 
     ##
-    # A command object for the delete which will be executed as part of cleaning up.
+    # Capture the delete command 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.
     ##
@@ -33,10 +32,11 @@ module Brine
       ##
       # 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.
+      # @param client [Faraday::Connection, #delete] Provide the Faraday client which will send the delete message.
+      # @param path [String] Specify the path of the resource to be deleted.
+      # @param oks [Array<Integer>] Indicate response status codes which should be considered successful)
+      #                             (defaults to [200,204]).
+      # @param attempts [Integer] Specify the number of times this command should be tried (defaults to 3).
       ##
       def initialize(client, path, oks: [200,204], attempts: 3)
         @client = client
@@ -48,14 +48,14 @@ module Brine
       ##
       # Issue the delete based on the parameters provided during construction.
       #
-      # @return [Boolean] true if a successful response is obtained, otherwise false.
+      # @return [Boolean] Return 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
+          rescue Exception => ex
             STDERR.puts "WARNING: #{ex}"
           end
         end
@@ -73,7 +73,7 @@ module Brine
     # 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.
+    # @param client [Faraday::Connection, #delete] Provide the client to DELETE subsequently tracked resources.
     ##
     def set_cleaning_client(client)
       @client = client
@@ -82,7 +82,7 @@ module Brine
     ##
     # Record resource to be later cleaned (pushes a DeleteCommand).
     #
-    # @param [String] path The path for the created resource; will be issued a DELETE.
+    # @param path [String] Specify the path for the created resource: will be issued a DELETE.
     ##
     def track_created_resource(path)
       cleanup_commands << DeleteCommand.new(@client, path)
@@ -91,7 +91,7 @@ module Brine
     ##
     # Clean recorded resources (normally after a test run).
     #
-    # @return [Boolean] true if all commands succeeded successfully, otherwise false.
+    # @return [Boolean] Return true if all commands succeeded successfully, otherwise false.
     ##
     def cleanup_created_resources
       # Avoid the use of any short circuiting folds.
@@ -101,11 +101,9 @@ module Brine
     private
 
     ##
-    # The array which serves as the stack of DeleteCommands.
+    # Return the array which serves as the stack of DeleteCommands.
     #
-    # Provides the property mixed in by the module.
-    #
-    # @return [Array<DeleteCommand>]
+    # @return [Array<DeleteCommand>] Return the existing or new list of commands to execute for cleanup.
     ##
     def cleanup_commands
       @cleanup_commands ||= []
@@ -118,3 +116,15 @@ module Brine
   ##
   include CleaningUp
 end
+
+require 'brine/transforming'
+
+##
+# Record a resource path which should be cleaned up.
+#
+# @param path [Object] Specify the path which should be DELETED.
+#                      This should be a String or a Template.
+##
+When('a resource is created at {grave_param}') do |path|
+  perform { track_created_resource(path) }
+end

data/lib/brine/client_building.rb

@@ -1,18 +1,18 @@
 ##
 # @file client_building.rb
-# Construction of a Faraday connection.
+# Construct a Faraday connection.
 ##
 
 module Brine
 
   ##
-  # Supports construction of a Faraday connection with some common middleware.
+  # Allow construction of a Faraday connection with some common middleware.
   ##
   module ClientBuilding
     require 'oauth2'
 
     ##
-    # Parameter object used to configure OAuth2 middleware
+    # Define OAuth2 middleware configuration.
     #
     # This is essentially a thin wrapper around `https://github.com/oauth-xx/oauth2`
     # to provide a mini-DSL and to facilitate the middleware configuration.
@@ -20,12 +20,12 @@ module Brine
     class OAuth2Params
 
       ##
-      # A token which has been retrieved from the authorization server.
+      # Store the token which has been retrieved from the authorization server.
       ##
       attr_accessor :token
 
       ##
-      # The type of OAuth2 token which will be retrieved.
+      # Specify the type of OAuth2 token which will be retrieved.
       #
       # Currently only `bearer` is supported.
       ##
@@ -44,14 +44,14 @@ module Brine
       # 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,
+      # @param id [String] Provide the login id credential with which to request authorization.
+      # @param secret [String] Provide the secret credential with which to request authorization.
+      # @param opts [Hash] Define 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 Specify the OAuth2 authorization server from which to request a token.
+      # @option opts [String] :token_url Specify the absolute or relative path to the Token endpoint on the authorization server.
+      # @option opts [Hash] :ssl Provide SSL options to pass through to the transport client,
       #                     `{verify: false}` may be useful for self-signed certificates.
       ##
       def fetch_from(id, secret, opts)
@@ -61,10 +61,10 @@ module Brine
     end
 
     ##
-    # Acquire an OAuth2 token within provided configuration block.
+    # Acquire an OAuth2 token with the provided configuration block.
     #
-    # @param [Block] Logic to execute with an OAuth2Params receiver;
-    #               this will normally involve an OAuth2Params#fetch_from call.
+    # @param [Block] Provide logic to execute with an OAuth2Params receiver;
+    #                this will normally involve an OAuth2Params#fetch_from call.
     ##
     def use_oauth2_token(&block)
       @oauth2 = OAuth2Params.new
@@ -72,7 +72,7 @@ module Brine
     end
 
     ##
-    # The handlers/middleware that will be wired while constructing a client.
+    # Expose 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.
@@ -98,13 +98,13 @@ module Brine
     end
 
     ##
-    # Construct a new client to send requests to `host`.
+    # Return a client which will send requests to `host`.
     #
-    # Will configure the client using `#connection_handlers`.
+    # This 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.
+    # @param host [String] Specify the hostname to which this client will send requests.
+    # @param logging [String] Indicate the desired logging level for this client.
+    # @return [Faraday::Connection] Return the configured client connection.
     ##
     def client_for_host(host, logging: ENV['BRINE_LOG_HTTP'])
       @logging = logging