brine-dsl 0.7.0 → 0.8.0

data/features/assignment/parameter.feature

@@ -0,0 +1,20 @@
+Feature: A Parameter
+  An identifier can be assigned the value of the provided parameter.
+
+  Scenario: Parameter assignment.
+    Given a file named "features/parameter.feature" with:
+      """
+
+Feature: Parameter Assignment.
+  Scenario: Simple assignment.
+    Given `foo` is assigned `bar`
+    When the response body is assigned `{{ foo }}`
+    Then the value of the response body is equal to `bar`
+
+      """
+    When I run `cucumber --strict features/parameter.feature`
+    Then the output should contain:
+      """
+      1 passed
+      """
+    And it should pass

data/features/assignment/random.feature

@@ -0,0 +1,25 @@
+Feature: A Random String
+  An identifier can be assigned a random string with decent entropy.
+
+  Scenario: Random string assignment.
+    Given a file named "features/random.feature" with:
+      """
+
+Feature: Random Assignment.
+  Scenario: Several unique variables.
+    Given `v1` is assigned a random string
+    And `v2` is assigned a random string
+    And `v3` is assigned a random string
+    When the response body is assigned `[ "{{ v1 }}","{{ v2 }}","{{ v3 }}" ]`
+    Then the value of the response body does not have any element that is empty
+    And the value of the response body child `.[0]` is equal to `{{ v1 }}`
+    And the value of the response body children `.[1:2]` does not have any element that is equal to `{{ v1 }}`
+    And the value of the response body child `.[2]` is not equal to `{{ v2 }}`
+
+      """
+    When I run `cucumber --strict features/random.feature`
+    Then the output should contain:
+      """
+      8 passed
+      """
+    And it should pass

data/features/assignment/response_attribute.feature

@@ -0,0 +1,33 @@
+Feature: A Value From A Response Attribute.
+  An identifier can be assigned a value extracted from a response attribute.
+
+  Scenario: Assorted attribute extractions.
+    Given a file named "features/response_attribute.feature" with:
+      """
+
+Feature: Reponse Attribute Path Assignment.
+  Scenario: Response body.
+    Given the response body is assigned `foo`
+    When `myVar` is assigned the response body
+    And the response body is assigned `{{ myVar }}`
+    Then the value of the response body is equal to `foo`
+
+  Scenario: Response body child.
+    Given the response body is assigned `{"response": "foo"}`
+    When `myVar` is assigned the response body child `.response`
+    And the response body is assigned `{{ myVar }}`
+    Then the value of the response body is equal to `foo`
+
+  Scenario: Response body children.
+    Given the response body is assigned `{"response": "foo"}`
+    When `myVar` is assigned the response body children `.response`
+    And the response body is assigned `{{{ myVar }}}`
+    Then the value of the response body is equal to `["foo"]`
+
+      """
+    When I run `cucumber --strict features/response_attribute.feature`
+    Then the output should contain:
+      """
+      3 passed
+      """
+    And it should pass

data/features/assignment/timestamp.feature

@@ -0,0 +1,33 @@
+Feature: A Timestamp
+  An identifier can be assigned a current timestamp.
+
+  Scenario: Timestamp assignment.
+    Given a file named "features/timestamp.feature" with:
+      """
+
+Feature: Timestamp Assignment.
+  Scenario: Newer than some old date.
+    Given `v1` is assigned a timestamp
+    When the response body is assigned `{{ v1 }}`
+    Then value of the response body is greater than `2018-06-17T12:00:00Z`
+
+  Scenario: Values increase.
+    Given `v1` is assigned a timestamp
+    When the response body is assigned `{{ v1 }}`
+    Then the value of the response body is not empty
+
+    When `v2` is assigned a timestamp
+    And the response body is assigned `{{ v2 }}`
+    Then the value of the response body is greater than or equal to `{{ v1 }}`
+
+    When `v3` is assigned a timestamp
+    And the response body is assigned `{{ v3 }}`
+    Then the value of the response body is greater than or equal to `{{ v1 }}`
+    And the value of the response body is greater than or equal to `{{ v2 }}`
+
+      """
+    When I run `cucumber --strict features/timestamp.feature`
+    Then the output should contain:
+      """
+      2 passed
+      """

data/lib/brine/cleaner_upper.rb

@@ -1,23 +1,37 @@
-# cleaner_upper.rb -- clean up resources created during test run
+##
+# @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.
+# 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.
+# 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
-  attr_accessor :client, :path
 
-  def initialize(client, path,
-                 oks:[200,204],
-                 attempts: 3)
+  ##
+  # 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
@@ -33,29 +47,54 @@ class DeleteCommand
   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
 
-  # HTTP client object used to issue DELETE calls
-  # must support #delete(path)
-  # to be injected by calling code
+  ##
+  # 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 cleaned
+  ##
+  # 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
-  # Expected to be called after test run
+  ##
+  # Clean recorded resources (normally after a test run).
   def cleanup_created_resources
     created_resources.reverse.each{|it| it.cleanup}
   end
 
   private
 
-  # Lazily initialized array of resources to remove
+  ##
+  # 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

data/lib/brine/coercer.rb

@@ -1,13 +1,63 @@
-## coercer.rb::
+##
+# @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(->(l, r){[l, r]})
-    @map[[String, Time]] = ->(l, r){[Time.parse(l), r]}
+    @map = Hash.new(->(lhs, rhs){[lhs, rhs]})
+    @map[[String, Time]] = ->(lhs, rhs){[Time.parse(lhs), rhs]}
   end
 
-  def coerce(l, r)
-    @map[[l.class, r.class]].call(l, r)
+  ##
+  # 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
 

data/lib/brine/rest_steps.rb

@@ -4,23 +4,28 @@ require 'brine/selector'
 require 'jsonpath'
 
 # Chopping Block
-When(/^the request parameter `([^`]*)` is set to `([^`]*)`$/) do |param, value|
-  replaced_with('When', "the request query paramter `#{param}` is assigned `#{value}`", '0.6')
+Then(/^the response #{RESPONSE_ATTRIBUTES} has `([^`]*)` with a value that is not empty$/) do
+  |attribute, member|
+  replaced_with('Then', "the value of the response #{attribute} child `#{member}` is not empty", '0.9')
 end
-Then(/^the response body is the list:$/) do |table|
-  replaced_with('Then', "the value of the response body is equal to:\n\"\"\"#{table.hashes.to_json}\"\"\"", '0.6')
+
+Then(/^the response #{RESPONSE_ATTRIBUTES} includes? the entries:$/) do |attribute, table|
+  replaced_with('Then', "the value of the response #{attribute} is including:\n\"\"\"#{table.hashes.to_json}\"\"\"", '0.9')
 end
-Then(/^the raw response body is:$/) do |text|
-  warn 'DEPRECATION: This step will be removed in version 0.6'
-  expect(response.body).to eq text
+
+Then(/^the response body is a list of length (\d+)$/) do |length|
+  replaced_with('Then', "the value of the response body is of length #{length}", '0.9')
 end
-Then(/^the response body has `([^`]*)` with a value equal to `([^`]*)`$/) do |child, value|
-  replaced_with('Then', "the value of the response body child `#{child}` is equal to `#{value}`", '0.6')
+
+Then(/^the response body is a list (with|without) an entry containing:$/) do |with, data|
+  neg = (with == 'without') ? 'not ' : ''
+  replaced_with('Then', "the value of the response body does #{neg}have any element that is including:\n\"\"\"#{table.hashes.to_json}\"\"\"", '0.9')
 end
 
-Then(/^the response #{RESPONSE_ATTRIBUTES} has `([^`]*)` with a value including `([^`]*)`$/) do
-  |attribute, member, value|
-  replaced_with('Then', "the value of the response body child `#{child}` is including `#{value}`", '0.6')
+Then(/^the response body has `([^`]*)` which (in|ex)cludes? the entries:$/) do
+  |child, in_or_ex, table|
+  neg = (in_or_ex=='ex') ? 'not ' : ''
+  replaced_with('Then', "the value of the response body child `#{child}` is #{neg}including:\n\"\"\"#{table.hashes.to_json}\"\"\"", '0.9')
 end
 
 # This file is legacy or unsorted steps which will be deprecated or moved into
@@ -33,13 +38,13 @@ def kv_table(table)
   transform_table!(table).rows_hash
 end
 
+# TODO: Requires extensible is_a_valid for deprecation
 Then(/^the response body is a list which all are (\w+)$/) do |matcher|
   pass_it = method(matcher.to_sym).call
   expect(response_body_child.first).to all(pass_it)
 end
 
-#TODO: The binding environment should be able to be accessed directly
-# without requiring a custom step
+# FIXME: In the process of being deprecated
 When(/^`([^`]*)` is bound to `([^`]*)` from the response body$/) do |name, path|
   binding[name] = response_body_child(path).first
 end
@@ -47,15 +52,6 @@ end
 #
 # Response attribute (non-body) assertions
 #
-Then(/^the response #{RESPONSE_ATTRIBUTES} has `([^`]*)` with a value that is not empty$/) do
-  |attribute, member|
-  expect(response).to have_attributes(attribute.to_sym => include(member.to_sym => be_not_empty))
-end
-
-Then(/^the response #{RESPONSE_ATTRIBUTES} includes? the entries:$/) do |attribute, table|
-  expect(response).to have_attributes(attribute.to_sym => include(kv_table(table)))
-end
-
 Then(/^the response #{RESPONSE_ATTRIBUTES} contains? null fields:$/) do |attribute, table|
   expect(response)
     .to have_attributes(attribute.to_sym =>
@@ -71,21 +67,11 @@ end
 #
 # Response body assertions
 #
+# TODO: Write specifications around this
 Then(/^the response body does not contain fields:$/) do |table|
   expect(response_body_child.first.keys).to_not include(*table.raw.flatten)
 end
 
-Then(/^the response body has `([^`]*)` which (in|ex)cludes? the entries:$/) do
-  |child, in_or_ex, table|
-  expect(response_body_child(child).first)
-    .send(not_if(in_or_ex=='ex'),
-          include(kv_table(table)))
-end
-
-Then(/^the response body is a list of length (\d+)$/) do |length|
-  expect(response_body_child.first).to have_attributes(length: length)
-end
-
 #TODO: Maybe worth optimizing these 2 to O(n) after tests are in place
 Then(/^the response body is a list sorted by `([^`]*)` ascending$/) do |path|
   values = response_body_child(path)
@@ -97,11 +83,6 @@ Then(/^the response body is a list sorted by `([^`]*)` descending$/) do |path|
   expect(values).to eq values.sort{|a,b| b.to_s.downcase <=> a.to_s.downcase}
 end
 
-Then(/^the response body is a list (with|without) an entry containing:$/) do |with, data|
-  expect(response_body_child.first)
-    .send(not_if(with == 'without'),
-          include(include(kv_table(data))))
-end
 
 Then(/^the response body is (\w+)$/) do |matcher|
   pass_it = method(matcher.to_sym).call

data/lib/brine/step_definitions/assignment.rb

@@ -1,13 +1,41 @@
-# assignment.rb -- assignment related steps
-
-When(/^`([^`]*)` is assigned a random string$/) do |name|
-  bind(name, SecureRandom.uuid)
-end
+##
+# @file assignment.rb
+# Assignment related steps.
 
+##
+# Assign the provided parameter.
+#
+# @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)
 end
 
+##
+# Assign a random string (UUID).
+#
+# @param name - The identifier to which a random string will be bound.
+When(/^`([^`]*)` is assigned a random string$/) do |name|
+  bind(name, SecureRandom.uuid)
+end
+
+##
+# Assign a current timestamp.
+#
+# @param name - The identifier to which the current timestamp will be bound.
 When(/^`([^`]*)` is assigned a timestamp$/) do |name|
   bind(name, DateTime.now)
 end
+
+##
+# Assign a value extracted from a response attribute.
+#
+# @param name - The identifier to which the extracted value will be bound.
+# @param attribute - The response member from which the value will be extracted.
+# @param plural - When the path is provided,
+# @param path - The path within the member to extract.
+# 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?))
+end

data/lib/brine.rb

@@ -1,10 +1,12 @@
-# brine.rb -- loader file for the rest of brine
+##
+# @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, or similar.
-# Those types of changes should be done by [#brine_mix].
+# 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.
 
 require 'brine/cleaner_upper'
 require 'brine/mustache_binder'
@@ -13,7 +15,8 @@ require 'brine/util'
 require 'brine/selector'
 require 'brine/type_checks'
 
-# Modules to add to World
+##
+# Meta-module for modules to mix into World.
 module Brine
   include CleanerUpper
   include MustacheBinder
@@ -23,8 +26,10 @@ module Brine
   include TypeChecking
 end
 
-# Load the more side effecty files and return the Module,
-# expected to be called as `World(brine_mix)`
+##
+# Load the files with side effects and return @ref Brine.
+#
+# Expected to be called as `World(brine_mix)`
 def brine_mix
   require 'brine/step_definitions/assignment'
   require 'brine/step_definitions/request_construction'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: brine-dsl
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Matt Whipple
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-05-30 00:00:00.000000000 Z
+date: 2018-06-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cucumber
@@ -193,7 +193,7 @@ files:
 - Gemfile.lock
 - Guardfile
 - LICENSE
-- README.md
+- README.adoc
 - Rakefile
 - brine-dsl.gemspec
 - config/cucumber.yml
@@ -226,6 +226,10 @@ files:
 - features/assertions/is_including.feature
 - features/assertions/is_matching.feature
 - features/assertions/is_of_length.feature
+- features/assignment/parameter.feature
+- features/assignment/random.feature
+- features/assignment/response_attribute.feature
+- features/assignment/timestamp.feature
 - features/deprecations/replaced_with.feature
 - features/request_construction/basic.feature
 - features/request_construction/body.feature
@@ -298,6 +302,10 @@ test_files:
 - features/assertions/is_including.feature
 - features/assertions/is_matching.feature
 - features/assertions/is_of_length.feature
+- features/assignment/parameter.feature
+- features/assignment/random.feature
+- features/assignment/response_attribute.feature
+- features/assignment/timestamp.feature
 - features/deprecations/replaced_with.feature
 - features/request_construction/basic.feature
 - features/request_construction/body.feature

data/README.md

@@ -1,7 +0,0 @@
-Brine
-===
-
-> Cucumber DSL for testing REST APIs
-
-Documentation is hosted at:
-https://brightcove.github.io/brine/