brine-dsl 0.5.0

data/lib/brine/requester.rb

@@ -0,0 +1,125 @@
+# requester.rb - Provide request construction and response storage
+
+require 'oauth2'
+require 'faraday_middleware'
+
+# 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
+
+  def client_for_host(host, logging: ENV['BRINE_LOG_HTTP'])
+    Faraday.new(host) do |conn|
+      conn.request :json
+
+      if @oauth2
+        conn.request :oauth2, @oauth2.token, :token_type => @oauth2.token_type
+      end
+
+      if logging
+        conn.response :logger, nil, :bodies => (logging.casecmp('DEBUG') == 0)
+      end
+
+      conn.response :json, :content_type => /\bjson$/
+
+      conn.adapter Faraday.default_adapter
+    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((ENV['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/rest_steps.rb

@@ -0,0 +1,138 @@
+require 'rspec'
+require 'brine/util'
+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')
+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')
+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
+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')
+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')
+end
+
+# This file is legacy or unsorted steps which will be deprecated or moved into
+# more appropriate homes
+
+def not_if(val) val ? :not_to : :to end
+
+# Return a table that that is a key value pair in a format ready for consumption
+def kv_table(table)
+  transform_table!(table).rows_hash
+end
+
+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
+When(/^`([^`]*)` is bound to `([^`]*)` from the response body$/) do |name, path|
+  binding[name] = response_body_child(path).first
+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 =>
+                        include(table.raw.flatten.collect{|v| [v, be_nil]}.to_h))
+end
+
+Then(/^the response #{RESPONSE_ATTRIBUTES} contains? non null fields:$/) do |attribute, table|
+  expect(response)
+    .to have_attributes(attribute.to_sym =>
+                        include(table.raw.flatten.collect{|v| [v, be_not_nil]}.to_h))
+end
+
+#
+# Response body assertions
+#
+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)
+  expect(values).to eq values.sort{|a,b| a.to_s.downcase <=> b.to_s.downcase}
+end
+
+Then(/^the response body is a list sorted by `([^`]*)` descending$/) do |path|
+  values = response_body_child(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
+  expect(response_body_child.first).to pass_it
+end
+
+#
+# Polling assertions
+#
+Then(/^a non\-empty list is eventually returned at `([^`]*)`$/) do |path|
+  retry_for(120, 3) do
+    send_request(parse_method('GET'), path)
+    expect(response_body_child.first).to_not be_empty
+  end
+end
+
+Then(/^the resource is eventually available at `([^`]*)`$/) do |path|
+  retry_for(120, 3) do
+    send_request(parse_method('GET'), path)
+    expect(response).to have_attributes(:status => 200)
+  end
+end
+
+# TODO: Parameterize polling length
+Then(/^the property `([^`]*)` is eventually `([^`]*)` at `([^`]*)`$/) do |field, value, path|
+  retry_for(180) do
+    send_request(parse_method('GET'), path)
+    expect(response_body_child.first).to include(field => value)
+  end
+end
+
+def response_body_child(path="")
+  JsonPath.new("$.#{path}").on(response.body.to_json)
+end

data/lib/brine/selector.rb

@@ -0,0 +1,66 @@
+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/step_definitions/assertions.rb

@@ -0,0 +1,37 @@
+# assertions.rb - General assertions to be used with a Selector
+
+Then(/^it is equal to `([^`]*)`$/) do |value|
+  selector.assert_that(value) {|v| eq v}
+end
+Then(/^it is equal to:$/) do |value|
+  selector.assert_that(value) {|v| eq v}
+end
+Then(/^it is matching `([^`]*)`$/) do |value|
+  selector.assert_that(value) {|v| match v}
+end
+Then (/^it is matching:$/) do |value|
+  selector.assert_that(value) {|v| match v}
+end
+Then(/^it is greater than `([^`]*)`$/) do |value|
+  selector.assert_that(value) {|v| be > v}
+end
+Then(/^it is greater than or equal to `([^`]*)`$/) do |value|
+  selector.assert_that(value) {|v| be >= v}
+end
+Then(/^it is less than `([^`]*)`$/) do |value|
+  selector.assert_that(value) {|v| be < v}
+end
+Then(/^it is less than or equal to `([^`]*)`$/) do |value|
+  selector.assert_that(value) {|v| be <= v}
+end
+
+Then(/^it is including `([^`]*)`$/) do |value|
+  selector.assert_that(value) {|v| include v }
+end
+Then(/^it is including:$/) do |value|
+  selector.assert_that(value) {|v| include v }
+end
+
+Then(/^it is a valid `([^`]*)`$/) do |type|
+  selector.assert_that(type) {|t| type_check_for(t) }
+end

data/lib/brine/step_definitions/assignment.rb

@@ -0,0 +1,13 @@
+# assignment.rb -- assignment related steps
+
+When(/^`([^`]*)` is assigned a random string$/) do |name|
+  bind(name, SecureRandom.uuid)
+end
+
+When(/^`([^`]*)` is assigned `([^`]*)`$/) do |name, value|
+  bind(name, value)
+end
+
+When(/^`([^`]*)` is assigned a timestamp$/) do |name|
+  bind(name, DateTime.now)
+end

data/lib/brine/step_definitions/cleanup.rb

@@ -0,0 +1,4 @@
+# cleanup.rb - Track information needed for Resource Cleanup
+When(/^a resource is created at `([^`]*)`$/) do |path|
+  track_created_resource path
+end

data/lib/brine/step_definitions/request_construction.rb

@@ -0,0 +1,19 @@
+# request_construction.rb - Build and send requests
+
+When(/^the request body is assigned:$/) do |input|
+  set_request_body(input)
+end
+
+When(/^the request query parameter `([^`]*)` is assigned `([^`]*)`$/) do |param, value|
+  add_request_param(param, value)
+end
+
+When(/^the request header `([^`]*)` is assigned `([^`]*)`$/) do |header, value|
+  add_header(header, value)
+end
+
+When(/^an? (GET|POST|PATCH|PUT|DELETE|HEAD|OPTIONS) is sent to `([^`]*)`$/) do |method, url|
+  send_request(parse_method(method), URI.escape(url))
+  bind('response', response)
+  reset_request
+end

data/lib/brine/step_definitions/selection.rb

@@ -0,0 +1,37 @@
+#RESPONSE_ATTRIBUTES='(status|headers|body)'
+Then(/^the value of the response #{RESPONSE_ATTRIBUTES}(?: child(ren)? `([^`]*)`)? is( not)? (.*)(?<!:)$/) do
+  |attribute, plural, path, negated, assertion|
+  use_selector(Selector.new(dig_from_response(attribute, path, !plural.nil?), (!negated.nil?)))
+  step "it is #{assertion}"
+end
+
+Then(/^the value of the response #{RESPONSE_ATTRIBUTES}(?: child(ren)? `([^`]*)`)? is( not)? (.*)(?<=:)$/) do
+  |attribute, plural, path, negated, assertion, multi|
+  use_selector(Selector.new(dig_from_response(attribute, path, !plural.nil?), (!negated.nil?)))
+  step "it is #{assertion}", multi.to_json
+end
+
+Then(/^the value of the response #{RESPONSE_ATTRIBUTES}(?: child(ren)? `([^`]*)`)? does( not)? have any element that is (.*)(?<!:)$/) do
+  |attribute, plural, path, negated, assertion|
+  use_selector(AnySelector.new(dig_from_response(attribute, path, !plural.nil?), (!negated.nil?)))
+  step "it is #{assertion}"
+end
+
+Then(/^the value of the response #{RESPONSE_ATTRIBUTES}(?: child(ren)? `([^`]*)`)? does( not)? have any element that is (.*)(?<=:)$/) do
+  |attribute, plural, path, negated, assertion, multi|
+  use_selector(AnySelector.new(dig_from_response(attribute, path, !plural.nil?), (!negated.nil?)))
+  step "it is #{assertion}", multi.to_json
+end
+
+#Would be negated with `not all' which would be equivalent to any(not ) but that's not readily supported
+Then(/^the value of the response #{RESPONSE_ATTRIBUTES}(?: child(ren)? `([^`]*)`)? has elements which are all (.*)(?<!:)$/) do
+  |attribute, plural, path, assertion|
+  use_selector(AllSelector.new(dig_from_response(attribute, path, !plural.nil?), false))
+  step "it is #{assertion}"
+end
+
+Then(/^the value of the response #{RESPONSE_ATTRIBUTES}(?: child(ren)? `([^`]*)`)? has elements which are all (.*)(?<=:)$/) do
+  |attribute, plural, path, assertion, multi|
+  use_selector(AllSelector.new(dig_from_response(attribute, path, !plural.nil?), false))
+  step "it is #{assertion}", multi.to_json
+end

data/lib/brine/test_steps.rb

@@ -0,0 +1,138 @@
+require 'rspec'
+#
+# Steps used to test this library
+# Not loaded by default (except in the tests)
+#
+HTTP_METHOD='GET|POST|PATCH|PUT|DELETE|HEAD|OPTIONS'
+
+class StubResponse
+  attr_accessor :body, :status
+
+  def initialize
+    @body = ''
+    @status = 200
+  end
+end
+
+class StubRequest
+  attr_accessor :method, :path, :headers, :body
+
+  def initialize
+    @headers = {}
+  end
+
+  def method=(value)
+    @method=value.downcase.to_sym
+  end
+end
+
+class StubBuilder
+  attr_reader :request, :response
+
+  def initialize
+    @request = StubRequest.new
+    @response = StubResponse.new
+  end
+
+  def make_response()
+    [@response.status, {}, @response.body]
+  end
+
+  def build(stubs)
+    # Currently the Faraday stub code provides one method per HTTP method (which then
+    # calls a generalized protected method), so this block grabs the method to use
+    # and passes the right args based on the signature. The last arg is normally a block
+    # but we're using the make_response method to avoid duplication and allow overriding.
+    m = stubs.method(@request.method)
+    case m.parameters.length
+      when 3
+        m.call(@request.path, @request.headers, &method(:make_response))
+      when 4
+        m.call(@request.path, @request.body, @request.headers, &method(:make_response))
+      else
+        raise "I don't know how to call #{m}"
+    end
+  end
+end
+
+class ResponseStatusSequenceStubBuilder < StubBuilder
+  def initialize(stub, seq)
+    @request = stub.request
+    @response = stub.response
+    @enum = seq.to_enum
+  end
+
+  def make_response()
+    begin
+      @val = @enum.next
+    end
+    [@val, {}, @response.body]
+  end
+end
+  
+def stub
+  @stub ||= StubBuilder.new
+end
+
+def build_stub
+  stub.build($stubs)
+  @stub = nil
+end
+
+Before do
+  $stubs = Faraday::Adapter::Test::Stubs.new
+  @client = Faraday.new(url: ENV['ROOT_URL'] ||
+                        'http://localhost:8080') do |conn|
+    conn.response :logger, nil
+    conn.adapter :test, $stubs
+  end
+end
+
+Given(/^expected response status of `([^`]*)`$/) do |status|
+  stub.response.status = status
+end
+
+Given(/^expected response status sequence of `([^`]*)`$/) do |seq|
+  @stub = ResponseStatusSequenceStubBuilder.new(stub, seq)  
+end
+
+Given(/^expected request body:$/) do |body|
+  stub.request.body = body
+end
+
+Given(/^expected request headers:$/) do |headers|
+  stub.request.headers = headers
+end
+
+Given(/^expected (#{HTTP_METHOD}) sent to `([^`]*)`/) do |method, path|
+  stub.request.method = method
+  stub.request.path = path
+  build_stub
+end
+
+When(/^the response body is assigned:$/) do |input|
+    @response ||= StubResponse.new
+    @response.body = input
+end
+
+When(/^the response body is assigned `([^`]*)`/) do |input|
+    @response ||= StubResponse.new
+    @response.body = input
+end
+
+When(/^the response body is:$/) do |input|
+  replaced_with('When', 'the response body is assigned:', '1.0.0', input.to_json)
+end
+
+When /^the response status is assigned `([^`]*)`$/ do |status|
+  @response ||= StubResponse.new
+  @response.status = status.to_i    # this coercion isn't needed but is a guarantee
+end
+
+Then(/^the response body as JSON is:$/) do |text|
+  expect(response.body.to_json).to eq text
+end
+
+Then(/^expected calls are verified$/) do
+  $stubs.verify_stubbed_calls
+end

data/lib/brine/transforms.rb

@@ -0,0 +1,81 @@
+# = transformers.rb:: Argument Transforms for Brine
+#
+# The Transforms that convert provided inputs to support richer
+# functionaliy than the simple strings which Cucumber provides.
+
+# == Scalar transforms
+# Convert inputs into basic Ruby data types which represent a single value
+
+# Integers
+Transform /\A(-?\d+)\z/ do |number|
+  number.to_i
+end
+
+# Booleans
+Transform /\A(?:true|false)\z/ do |boolean|
+  boolean.to_s == "true"
+end
+
+# Regexp
+# This presently does not support flags after the closing slash, support for these should be added as needed
+Transform /\A\/(.*)\/\z/ do |pattern|
+  Regexp.new(pattern)
+end
+
+# Temporal
+DATE='\d{4}-\d{2}-\d{2}'
+TIME='\d{2}:\d{2}:\d{2}'
+MILLIS='(?:\.\d{3})?'
+TZ='(?:Z|(?:[+-]\d{2}:\d{2}))'
+Transform /^#{DATE}T#{TIME}#{MILLIS}#{TZ}$/ do |date|
+          Time.parse(date)
+end
+
+# == Structure transforms
+# Converts inputs to general data structures
+
+# Lists
+Transform /\A\[.*\]\z/m do |input|
+  JSON.parse(input)
+end
+
+# Objects
+# Rely on templates being registered later and therefore given higher priority.
+# Lookarounds could avoid the ambiguity but are a nastier pattern.
+Transform /\A{.*}\z$/m do |input|
+    JSON.parse(input)
+end
+
+# == Atypical transforms
+# Transforms for which data type is not the primary focus
+
+# Whitespace removal transforms
+# Handle stripping leading and trailing whitespace.
+# These are split out from the transforms to consolidate the behavior.
+# They call transform on the stripped value so that subsequent transforms no longer
+# have to deal with such whitespace.
+#
+# Note that these need to deal with multiline string arguments which require
+# the multiline flag and \A/\z anchors to properly operate on the full string rather than
+# being line oriented. The calls to +#strip+ are also not likely to properly clean up
+# multiline strings but is just meant as a (potentially ineffective) optimization over
+# recursive calls and capturing.
+Transform /\A\s+(.*)\z/m do |input|
+  Transform(input.strip)
+end
+Transform /\A(.*)\s+\z/m do |input|
+  Transform(input.strip)
+end
+
+# Quotes
+Transform /\A".*"\z/ do |quoted|
+  quoted[1..-2]
+end
+Transform /\A'.*'\z/ do |quoted|
+  quoted[1..-2]
+end
+
+# Template Expansion
+Transform /.*{{.*}}.*/ do |template|
+  Transform(shave_value(template))
+end

data/lib/brine/type_checks.rb

@@ -0,0 +1,35 @@
+# 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),
+      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