brine-dsl 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2a3988772e5439b101fa2d3d9ab87034c04bb8a9
-  data.tar.gz: c1491585ad2734877fb636a0f0880b02960e9172
+  metadata.gz: f3a218b02acd1fc90e2ca605c74ce54a37b9b05a
+  data.tar.gz: 7919bf69e899db000df3bdb3c682875e02d1df32
 SHA512:
-  metadata.gz: 72aa061fc15c4f629f74fc2ce37aa8c2818570591647dd33e8a7b0dde906f3daf735a2b22845210bb90636a3c04c2961e89b19b2cb463f198b8bd806779f8755
-  data.tar.gz: 8888baf7504c251f3011660bdb96eebb66f2f3abe3ae206b6418cc7d0f9d8048bcf1a2fd2ccdf84a22c9c016b2be6c01500419deffca8ab4341976f271f1a421
+  metadata.gz: 52d2907d296a7794f619adbd6dfafabe45aa6d572c50d0520edea5310c47fbc91eed1c937b73551960ef1f89da8d35a7239bfa7f618e44bf9c095eec6c197430
+  data.tar.gz: 31b7748a12f98aa942d21e6e58ac7c26ed014bbf3c66bc9bb19308568fc52b70b8d62209fa8ab5fdfe6ed3d7b0743da889ad1910264a2761526c92ba0f2e7e14

data/.gitignore

@@ -1,4 +1,3 @@
 pkg/
 tmp
 .gradle
-*~

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    brine-dsl (0.5.0)
+    brine-dsl (0.6.0.pre.SNAPSHOT)
       cucumber (~> 2.4)
       faraday
       faraday_middleware
@@ -59,8 +59,9 @@ GEM
       cucumber (~> 2.0)
       guard-compat (~> 1.0)
       nenv (~> 0.1)
-    jsonpath (0.8.10)
+    jsonpath (0.8.11)
       multi_json
+      to_regexp (~> 0.2.1)
     jwt (1.5.6)
     listen (3.1.5)
       rb-fsevent (~> 0.9, >= 0.9.4)
@@ -86,7 +87,7 @@ GEM
     pry (0.11.3)
       coderay (~> 1.1.0)
       method_source (~> 0.9.0)
-    rack (2.0.3)
+    rack (2.0.4)
     rake (12.3.0)
     rb-fsevent (0.10.2)
     rb-inotify (0.9.10)
@@ -95,7 +96,7 @@ GEM
       rspec-core (~> 3.7.0)
       rspec-expectations (~> 3.7.0)
       rspec-mocks (~> 3.7.0)
-    rspec-core (3.7.0)
+    rspec-core (3.7.1)
       rspec-support (~> 3.7.0)
     rspec-expectations (3.7.0)
       diff-lcs (>= 1.2.0, < 2.0)
@@ -107,6 +108,7 @@ GEM
     ruby_dep (1.5.0)
     shellany (0.0.1)
     thor (0.20.0)
+    to_regexp (0.2.1)
 
 PLATFORMS
   ruby

data/README.md

@@ -3,135 +3,5 @@ Brine
 
 > Cucumber DSL for testing REST APIs
 
-Motivation
----
-REpresentational State Transfer APIs expose their functionality
-through combinations of fairly coarse primitives that generally
-revolve around the use of transferring data in a standard exchange
-format (such as JSON) using HTTP methods and other aspects of the very
-simple HTTP protocol. Tests for such an API can therefore be defined
-using a domain specific language (DSL) built around those higher level
-ideas rather than requiring a general purpose language (the equivalent
-of scripted `curl` commands with some glue code and assertions).
-This project provides such a DSL by using select libraries
-integrated into Cucumber, where Cucumber provides a test-oriented
-framework for DSL creation.
-
-Sample Usage
----
-The general usage pattern revolves around construction of a request
-and performing assertions against the received response.
-
-```gherkin
-When the request body is assigned:
-  """
-  {"first_name": "John",
-   "last_name": "Smith"}
-  """
-And a POST is sent to `/users`
-Then the value of the response status is equal to `200`
-And the value of the response body is including:
-  """
-  {"first_name": "John",
-   "last_name": "Smith"}
-  """
-```
-
-Disclaimer
----
-Right now this project is new and features are being implemented as
-needed rather than speculatively. Some of the info here may be more
-optimistic than realistic until things are smoothed out or hopes abandoned.
-
-Features
----
-
-### Variable Binding/Expansion
-
-In cases where dynamic data is in the response or is desired for the
-request, then values can be bound to identifiers which can then be
-expanded using [Mustache](mustache.github.io) templates in your
-feature files.
-
-### Type Transforms
-
-Different types of data can be expressed directly in the feature files
-or expanded into variables by using the appropriate syntax for that
-type.
-
-[Read More](https://github.com/brightcove/brine/wiki/Argument-Transforms)
-
-#### Type Coercion
-
-Related to transforms, a facility to coerce types is also provided. This allows
-more intelligent comparison of inputs which have been transformed to a 
-richer data type with those that have not been transformed (normally strings).
-As an example comparing a date/time value with a string will attempt to parse
-the string to a date/time so that the values can be compared using the proper semantics. 
-
-### Resource Cleanup
-
-Tests are likely to create resources which should then be cleaned up,
-restoring the pre-test state of the system: steps to facilitate this
-are provided.
-
-### Authentication
-
-Presently OAuth2 is supported to issue authenticated requests during a
-test (likely using a feature `Background`).
-
-### Division of Selection and Assertion
-
-To allow for a wider range of tests without an exploding code base
-(and keeping the assertions easier to write), Brine internall splits the
-selection of the value(s) to test from the assertion(s) that will be performed against it.
-
-[Read Mode](https://github.com/brightcove/brine/wiki/Selection-and-Assertion)
-
-### Request Construction and Response Assertion Step Definitions
-
-The previous features combined with the library of provide steps should
-cover all of the functionality needed to exercise and validate all of
-the functionality exposed by your REST API.
-
-
-Installation
----
-
-Presently the gem for this project isn't being published anywhere:
-primarily because tracking down a local gem repository seems scary. If
-this project is open sourced then this will probably change but in the
-meantime the project can be used off of GitHub by adding this to your
-`Gemfile` and performing the usual `bundle install` dance:
-
-```ruby
-git 'git@github.com:brightcove/brine.git', :branch => 'master' do
-  gem 'brine'
-end
-```
-
-Specific branches and refs can be targetted as
-documented [here](http://bundler.io/git.html). This should likely be
-done in any cases where you're not actively tracking Brine and don't want
-your tests to suddenly break because of changes to it.
-
-Brine can then be "mixed in" to your project (which adds assorted
-modules to the `World` and loads all the step definitions and other
-Cucumber magic) by adding the following to your `support/env.rb` or
-other ruby file:
-
-```ruby
-require 'brine'
-
-World(brine_mix)
-```
-
-Select pieces can also be loaded (to be documented). With the above,
-feature files should be able to be written and executed without
-requiring any additional ruby code.
-
-Questions? Comments?
----
-Check out the [wiki](https://github.com/brightcove/brine/wiki) for more information
-and search for related [issues](https://github.com/brightcove/brine/issues)
-or open one for anything not documented or implemented elsewhere.
+Documentation is hosted at:
+https://brightcove.github.io/brine/

data/Rakefile

@@ -1,6 +1,9 @@
 # encoding: utf-8
+require 'bundler'
 require 'cucumber/rake/task'
+
 Cucumber::Rake::Task.new
+Bundler::GemHelper.install_tasks
 
 task default: %w[check]
 

data/brine-dsl.gemspec

@@ -1,7 +1,7 @@
 # -*- encoding: utf-8 -*-
 Gem::Specification.new do |s|
   s.name         = 'brine-dsl'
-  s.version      = '0.5.0'
+  s.version      = '0.6.0'
   s.platform     = Gem::Platform::RUBY
   s.authors      = ["Matt Whipple"]
   s.email        = ["mwhipple@brightcove.com"]

data/docs/cookbook.html

@@ -427,13 +427,20 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <div id="toctitle">Table of Contents</div>
 <ul class="sectlevel1">
 <li><a href="#_overview">Overview</a></li>
-<li><a href="#__assurances">"Assurances"</a>
+<li><a href="#_intercepting_of_http_calls">Intercepting of HTTP Calls</a>
 <ul class="sectlevel2">
 <li><a href="#_context">Context</a></li>
 <li><a href="#_solution">Solution</a></li>
 <li><a href="#_recipe">Recipe</a></li>
 </ul>
 </li>
+<li><a href="#__assurances">"Assurances"</a>
+<ul class="sectlevel2">
+<li><a href="#_context_2">Context</a></li>
+<li><a href="#_solution_2">Solution</a></li>
+<li><a href="#_recipe_2">Recipe</a></li>
+</ul>
+</li>
 </ul>
 </div>
 </div>
@@ -447,14 +454,75 @@ Brine but are not considered part of Brine&#8217;s responsibility (at least pres
 Many of these are focused on simplicity and ease rather than robustness or elegance,
 and modification to address specific cases should be expected.</p>
 </div>
+<div class="paragraph">
+<p>Many of these will also be platform specific and be subject to further organization
+once platforms beyond ruby are supported.</p>
+</div>
 </div>
 </div>
 <div class="sect1">
-<h2 id="__assurances">"Assurances"</h2>
+<h2 id="_intercepting_of_http_calls">Intercepting of HTTP Calls</h2>
 <div class="sectionbody">
 <div class="sect2">
 <h3 id="_context">Context</h3>
 <div class="paragraph">
+<p>There may be cases where the request or reponse may need to be modified
+in some way before or after transmission, for example to add a custom header
+which is somehow specific to the testing configuration and therefore outside
+of anything that belongs in the specification.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_solution">Solution</h3>
+<div class="paragraph">
+<p>This can be done through the registration of custom Faraday middleware on
+the Brine client. All of the registered middleware attaches
+to the generated connection through an array of functions in
+<a href="https://github.com/brightcove/brine/blob/master/lib/brine/requester.rb">requester.rb</a>.
+Each function accepts the connection object as its single parameter. The array of functions
+is exposed as <code>connection_handlers</code>  and can be modified through getting that property
+from either the default <code>World</code> (for the default client) or from an appropriate <code>ClientBuilder</code>
+if creating custom clients and mutating it accordingly (setting the reference is not suported).
+You could just build your own client without the facilities provided by Brine.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_recipe">Recipe</h3>
+<div class="paragraph">
+<p>An example to add a custom header could be implemented as follows:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-ruby" data-lang="ruby">require 'faraday'
+class CustomHeaderAdder &lt; Faraday::Middleware
+  def initialize(app, key, val)
+    super(app)
+    @key = key
+    @val = val
+  end
+
+  def call(env)
+    env[:request_headers].merge!({@key =&gt; @val})
+    @app.call(env)
+  end
+end
+
+...
+
+connection_handlers.unshift(proc do |conn|
+  conn.use CustomHeaderAdder, 'x-header', 'I am a test'
+end)</code></pre>
+</div>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="__assurances">"Assurances"</h2>
+<div class="sectionbody">
+<div class="sect2">
+<h3 id="_context_2">Context</h3>
+<div class="paragraph">
 <p>Ideally all tests should be as self-contained and isolated as possible;
 when writing functional tests, however, there are cases where this isn&#8217;t
 feasible or possible. In some cases a system depends on another external
@@ -474,7 +542,7 @@ complete test isolation.</p>
 </div>
 </div>
 <div class="sect2">
-<h3 id="_solution">Solution</h3>
+<h3 id="_solution_2">Solution</h3>
 <div class="paragraph">
 <p>In such cases a standard solution is to designate certain resources to be reused for
 certain tests. These are analogous to the concept of "fixtures" in some test suites
@@ -517,7 +585,7 @@ up test runs through the use of parallelism/asynchronicity.</p>
 </div>
 </div>
 <div class="sect2">
-<h3 id="_recipe">Recipe</h3>
+<h3 id="_recipe_2">Recipe</h3>
 <div class="paragraph">
 <p>This can be done using standard cucumber tags. Assurances can be defined in designated
 <code>assure_*.feature</code> files where each Feature is appropriately tagged:</p>
@@ -560,7 +628,7 @@ Cucumber behavior so that the full test suite can be more stochastic
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2017-10-25 10:06:13 -04:00
+Last updated 2018-02-08 14:37:47 EST
 </div>
 </div>
 </body>

data/docs/guide.html

@@ -578,24 +578,18 @@ the functionality exposed by your REST API.</p>
 <h2 id="_installation">Installation</h2>
 <div class="sectionbody">
 <div class="paragraph">
-<p>Presently the gem for this project isn&#8217;t being published anywhere:
-primarily because tracking down a local gem repository seems scary. If
-this project is open sourced then this will probably change but in the
-meantime the project can be used off of GitHub by adding this to your
-<code>Gemfile</code> and performing the usual <code>bundle install</code> dance:</p>
+<p>Brine is published as <code>brine-dsl</code> on rubygems, the page for which is
+at <a href="https://rubygems.org/gems/brine-dsl" class="bare">https://rubygems.org/gems/brine-dsl</a>. The latest version and other
+gem metadata can be viewed on that page. Brine can be used by
+declaring that gem in your project Gemfile such as:</p>
 </div>
 <div class="listingblock">
 <div class="content">
-<pre class="highlightjs highlight"><code class="language-ruby" data-lang="ruby">git 'git@github.com:brightcove/brine.git', :branch =&gt; 'master' do
-  gem 'brine'
-end</code></pre>
+<pre class="highlightjs highlight"><code class="language-ruby" data-lang="ruby">gem 'brine-dsl', '~&gt; 1.0'</code></pre>
 </div>
 </div>
 <div class="paragraph">
-<p>Specific branches and refs can be targetted as
-documented <a href="http://bundler.io/git.html">here</a>. This should likely be
-done in any cases where you&#8217;re not actively tracking Brine and don&#8217;t want
-your tests to suddenly break because of changes to it.</p>
+<p>(after version 1.0 is released).</p>
 </div>
 <div class="paragraph">
 <p>Brine can then be "mixed in" to your project (which adds assorted
@@ -1105,6 +1099,12 @@ which the step was evaluated.</p>
 <dd>
 <p>Assert that the current select value includes/is a superset of <code>VALUE</code>.</p>
 </dd>
+<dt class="hdlist1"><code>Then it is empty</code></dt>
+<dd>
+<p>  Assert that value is empty or null. Any type which is not testable for emptiness
+(such as booleans or numbers) will always return false. Null is treated as an empty
+value so that it can be treated as such for endpoints that return null in place of empty collections, and non-null empty values can easily be tested for using conjunction.</p>
+</dd>
 <dt class="hdlist1"><code>Then it is a valid `$TYPE`</code></dt>
 <dd>
 <p>  Assert that the selected value is a valid instance of a <code>TYPE</code>. Presently this
@@ -1142,7 +1142,7 @@ wiring and documentation. The current supported types are:</p>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2017-11-15 22:28:26 -05:00
+Last updated 2018-02-08 12:09:12 EST
 </div>
 </div>
 </body>

data/docs/index.html

@@ -465,7 +465,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2017-10-25 10:06:13 -04:00
+Last updated 2017-10-17 16:14:35 EDT
 </div>
 </div>
 </body>

data/docs/specs.html

@@ -451,6 +451,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <li><a href="#__span_class_feature_name_equal_to_span"><span class="feature name">Equal to</span></a></li>
 <li><a href="#__span_class_feature_name_matching_span"><span class="feature name">Matching</span></a></li>
 <li><a href="#__span_class_feature_name_including_span"><span class="feature name">Including</span></a></li>
+<li><a href="#__span_class_feature_name_empty_span"><span class="feature name">Empty</span></a></li>
 <li><a href="#__span_class_feature_name_a_valid_span"><span class="feature name">A valid &#8230;&#8203;</span></a></li>
 </ul>
 </li>
@@ -1247,10 +1248,10 @@ Then the value of the response body children `..val` has elements which are all
 <div class="sect2">
 <h3 id="__span_class_feature_name_equal_to_span"><span class="feature name">Equal to</span></h3>
 <div class="paragraph">
-<p>It can be asserted that a value is equal to another value</p>
+<p>It can be asserted that a value is equal to another value.</p>
 </div>
 <div class="sect3">
-<h4 id="__span_class_scenario_name_assorted_positive_and_negative_assertions_span_3"><span class="scenario name">Assorted positive and negative assertions.</span></h4>
+<h4 id="__span_class_scenario_name_assorted_positive_and_negative_assertions_pass_span"><span class="scenario name">Assorted positive and negative assertions pass.</span></h4>
 <div class="ulist step-list">
 <ul>
 <li>
@@ -1334,10 +1335,10 @@ Examples:
 <div class="sect2">
 <h3 id="__span_class_feature_name_matching_span"><span class="feature name">Matching</span></h3>
 <div class="paragraph">
-<p>It can be asserted that a value matches another string or regex</p>
+<p>It can be asserted that a value matches another string or regex.</p>
 </div>
 <div class="sect3">
-<h4 id="__span_class_scenario_name_assorted_positive_and_negative_assertions_span_4"><span class="scenario name">Assorted positive and negative assertions.</span></h4>
+<h4 id="__span_class_scenario_name_assorted_positive_and_negative_assertions_span_3"><span class="scenario name">Assorted positive and negative assertions.</span></h4>
 <div class="ulist step-list">
 <ul>
 <li>
@@ -1347,8 +1348,8 @@ Examples:
 </div>
 <div class="listingblock">
 <div class="content">
-<pre class="highlightjs highlight"><code class="language-gherkin" data-lang="gherkin">Feature: Assert value matchiness
-Scenario: String in response body matched against a regex
+<pre class="highlightjs highlight"><code class="language-gherkin" data-lang="gherkin">Feature: Assert value matchiness.
+Scenario: String in response body is matched against a regex.
 When the response body is assigned:
 """
 http://www.github.com?var=val
@@ -1452,6 +1453,99 @@ And the value of the response body is not including:
 </div>
 </div>
 <div class="sect2">
+<h3 id="__span_class_feature_name_empty_span"><span class="feature name">Empty</span></h3>
+<div class="paragraph">
+<p>It can be asserted that a value is empty.</p>
+</div>
+<div class="sect3">
+<h4 id="__span_class_scenario_name_assorted_positive_and_negative_assertions_pass_span_2"><span class="scenario name">Assorted positive and negative assertions pass.</span></h4>
+<div class="ulist step-list">
+<ul>
+<li>
+<p><strong>Given</strong> a file named "features/is_empty.feature" with:</p>
+</li>
+</ul>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-gherkin" data-lang="gherkin">Feature: Assert emptiness for multiple types.
+Scenario: Empty body is empty.
+When the response body is assigned ``
+Then the value of the response body is empty
+
+Scenario: Whitespace-only body is empty.
+When the response body is assigned:
+"""
+
+"""
+Then the value of the response body is empty
+
+Scenario: Empty string is empty.
+When the response body is assigned `""`
+Then the value of the response body is empty
+
+Scenario: Non-empty string is not empty.
+When the response body is assigned `blah`
+Then the value of the response body is not empty
+
+Scenario: Quoted whitespace is not empty.
+When the response body is assigned `" "`
+Then the value of the response body is not empty
+
+Scenario: Empty arrays are empty.
+When the response body is assigned `[]`
+Then the value of the response body is empty
+
+Scenario: Non-empty arrays are not empty.
+When the response body is assigned `[[]]`
+Then the value of the response body is not empty
+
+Scenario: Empty objects are empty.
+When the response body is assigned `{}`
+Then the value of the response body is empty
+
+Scenario: Non-empty objects are not empty.
+When the response body is assigned `{"foo":{}}`
+Then the value of the response body is not empty
+
+Scenario: Null values are empty.
+When the response body is assigned `{"foo": null}`
+Then the value of the response body child `foo` is empty
+
+Scenario: False is not empty.
+When the response body is assigned `false`
+Then the value of the response body is not empty
+
+Scenario: 0 is not empty.
+When the response body is assigned `0`
+Then the value of the response body is not empty</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><strong>When</strong> I run <code>cucumber --strict features/is_empty.feature</code></p>
+</li>
+<li>
+<p><strong>Then</strong> the output should contain:</p>
+</li>
+</ul>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-gherkin" data-lang="gherkin">12 passed</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><strong>And</strong> it should pass</p>
+</li>
+</ul>
+</div>
+</div>
+</div>
+<div class="sect2">
 <h3 id="__span_class_feature_name_a_valid_span"><span class="feature name">A valid &#8230;&#8203;</span></h3>
 <div class="sect3">
 <h4 id="__span_class_scenario_name_positive_and_negative_assertions_for_json_types_span"><span class="scenario name">Positive and negative assertions for JSON types.</span></h4>
@@ -1665,7 +1759,7 @@ Then the value of the response body children `.val` has elements which are all a
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2017-11-16 16:15:35 -05:00
+Last updated 2018-02-08 12:09:12 EST
 </div>
 </div>
 </body>

data/docs/src/cookbook.adoc

@@ -4,13 +4,67 @@ Matt Whipple <http://github.com/mwhipple[@mwhipple]>
 :keywords: Brine, Cucumber, REST, DSL
 
 == Overview
+
 The following are some recipes to address issues which may arise while using
 Brine but are not considered part of Brine's responsibility (at least presently).
 Many of these are focused on simplicity and ease rather than robustness or elegance,
 and modification to address specific cases should be expected.
 
+Many of these will also be platform specific and be subject to further organization
+once platforms beyond ruby are supported.
+
+== Intercepting of HTTP Calls
+
+=== Context
+
+There may be cases where the request or reponse may need to be modified
+in some way before or after transmission, for example to add a custom header
+which is somehow specific to the testing configuration and therefore outside
+of anything that belongs in the specification.
+
+=== Solution
+
+This can be done through the registration of custom Faraday middleware on
+the Brine client. All of the registered middleware attaches
+to the generated connection through an array of functions in
+https://github.com/brightcove/brine/blob/master/lib/brine/requester.rb[requester.rb].
+Each function accepts the connection object as its single parameter. The array of functions
+is exposed as `connection_handlers`  and can be modified through getting that property
+from either the default `World` (for the default client) or from an appropriate `ClientBuilder`
+if creating custom clients and mutating it accordingly (setting the reference is not suported).
+You could just build your own client without the facilities provided by Brine.
+
+=== Recipe
+
+An example to add a custom header could be implemented as follows:
+
+[source,ruby]
+----
+require 'faraday'
+class CustomHeaderAdder < Faraday::Middleware
+  def initialize(app, key, val)
+    super(app)
+    @key = key
+    @val = val
+  end
+
+  def call(env)
+    env[:request_headers].merge!({@key => @val})
+    @app.call(env)
+  end
+end
+
+...
+
+connection_handlers.unshift(proc do |conn|
+  conn.use CustomHeaderAdder, 'x-header', 'I am a test'
+end)
+----
+
 == "Assurances"
+
 === Context
+
 Ideally all tests should be as self-contained and isolated as possible;
 when writing functional tests, however, there are cases where this isn't
 feasible or possible. In some cases a system depends on another external
@@ -28,6 +82,7 @@ and the number of accounts is limited, then that is likely to unfortunately prev
 complete test isolation.
 
 === Solution
+
 In such cases a standard solution is to designate certain resources to be reused for
 certain tests. These are analogous to the concept of "fixtures" in some test suites
 though there may be slight differences in implementation and reliance on them.
@@ -41,6 +96,7 @@ validate that preconditions are met; ideally if such preconditions can be establ
 idempotently then the assurances can do so before the validation.
 
 ==== Assurances are NOT Tests
+
 **Assurances validate a state which is desired to be consistently retained within the
 system rather than being changed**. This means that they should _not_ be used for tests
 as that would require state changes, nor should they clean up after themselves (as that

data/docs/src/guide.adoc

@@ -75,23 +75,17 @@ cover all of the functionality needed to exercise and validate all of
 the functionality exposed by your REST API.
 
 == Installation
-Presently the gem for this project isn't being published anywhere:
-primarily because tracking down a local gem repository seems scary. If
-this project is open sourced then this will probably change but in the
-meantime the project can be used off of GitHub by adding this to your
-`Gemfile` and performing the usual `bundle install` dance:
+Brine is published as `brine-dsl` on rubygems, the page for which is
+at https://rubygems.org/gems/brine-dsl. The latest version and other
+gem metadata can be viewed on that page. Brine can be used by
+declaring that gem in your project Gemfile such as:
 
 [source,ruby]
 ----
-git 'git@github.com:brightcove/brine.git', :branch => 'master' do
-  gem 'brine'
-end
+gem 'brine-dsl', '~> 1.0'
 ----
 
-Specific branches and refs can be targetted as
-documented http://bundler.io/git.html[here]. This should likely be
-done in any cases where you're not actively tracking Brine and don't want
-your tests to suddenly break because of changes to it.
+(after version 1.0 is released).
 
 Brine can then be "mixed in" to your project (which adds assorted
 modules to the `World` and loads all the step definitions and other
@@ -414,6 +408,11 @@ _see <<_selection_and_assertion>>_
 `Then it is including {grave}$VALUE{grave}`::
   Assert that the current select value includes/is a superset of `VALUE`.
 
+`Then it is empty`::
+  Assert that value is empty or null. Any type which is not testable for emptiness
+(such as booleans or numbers) will always return false. Null is treated as an empty
+value so that it can be treated as such for endpoints that return null in place of empty collections, and non-null empty values can easily be tested for using conjunction.
+
 `Then it is a valid {grave}$TYPE{grave}`::
   Assert that the selected value is a valid instance of a `TYPE`. Presently this
 is focused on standard data types (intially based on those specified by JSON),
@@ -424,4 +423,4 @@ wiring and documentation. The current supported types are:
  * `Number`
  * `Integer`
  * `Array`
- * `Boolean`
+ * `Boolean`

data/docs/src/specs.adoc

@@ -21,4 +21,5 @@ gherkin::../../features/selectors/all.feature[spec.erb]
 gherkin::../../features/assertions/is_equal_to.feature[spec.erb]
 gherkin::../../features/assertions/is_matching.feature[spec.erb]
 gherkin::../../features/assertions/is_including.feature[spec.erb]
-gherkin::../../features/assertions/is_a_valid.feature[spec.erb]
+gherkin::../../features/assertions/is_empty.feature[spec.erb]
+gherkin::../../features/assertions/is_a_valid.feature[spec.erb]

data/features/assertions/is_empty.feature

@@ -0,0 +1,67 @@
+Feature: Empty
+  It can be asserted that a value is empty.
+
+  Scenario: Assorted positive and negative assertions pass.
+    Given a file named "features/is_empty.feature" with:
+      """
+
+Feature: Assert emptiness for multiple types.
+  Scenario: Empty body is empty.
+    When the response body is assigned ``
+    Then the value of the response body is empty
+
+  Scenario: Whitespace-only body is empty.
+    When the response body is assigned:
+      \"\"\"
+             
+      \"\"\"
+    Then the value of the response body is empty
+
+  Scenario: Empty string is empty.
+    When the response body is assigned `""`
+    Then the value of the response body is empty
+
+  Scenario: Non-empty string is not empty.
+    When the response body is assigned `blah`
+    Then the value of the response body is not empty
+
+  Scenario: Quoted whitespace is not empty.
+    When the response body is assigned `" "`
+    Then the value of the response body is not empty
+
+  Scenario: Empty arrays are empty.
+    When the response body is assigned `[]`
+    Then the value of the response body is empty
+
+  Scenario: Non-empty arrays are not empty.
+    When the response body is assigned `[[]]`
+    Then the value of the response body is not empty
+
+  Scenario: Empty objects are empty.
+    When the response body is assigned `{}`
+    Then the value of the response body is empty
+
+  Scenario: Non-empty objects are not empty.
+    When the response body is assigned `{"foo":{}}`
+    Then the value of the response body is not empty
+
+  Scenario: Null values are empty.
+    When the response body is assigned `{"foo": null}`
+    Then the value of the response body child `foo` is empty
+
+  Scenario: False is not empty.
+    When the response body is assigned `false`
+    Then the value of the response body is not empty
+
+  Scenario: 0 is not empty.
+    When the response body is assigned `0`
+    Then the value of the response body is not empty
+
+      """
+    When I run `cucumber --strict features/is_empty.feature`
+    Then the output should contain:
+      """
+      12 passed
+      """
+    And it should pass
+

data/features/assertions/is_equal_to.feature

@@ -1,7 +1,7 @@
 Feature: Equal to
-  It can be asserted that a value is equal to another value
+  It can be asserted that a value is equal to another value.
 
-  Scenario: Assorted positive and negative assertions.
+  Scenario: Assorted positive and negative assertions pass.
     Given a file named "features/is_equal_to.feature" with:
       """
 

data/features/assertions/is_matching.feature

@@ -1,12 +1,12 @@
 Feature: Matching
-  It can be asserted that a value matches another string or regex
+  It can be asserted that a value matches another string or regex.
 
   Scenario: Assorted positive and negative assertions.
     Given a file named "features/is_matching.feature" with:
       """
 
-Feature: Assert value matchiness
-  Scenario: String in response body matched against a regex
+Feature: Assert value matchiness.
+  Scenario: String in response body is matched against a regex.
     When the response body is assigned:
       \"\"\"
       http://www.github.com?var=val
@@ -32,4 +32,4 @@ Feature: Assert value matchiness
       """
       2 passed
       """
-    And it should pass
+    And it should pass

data/lib/brine/requester.rb

@@ -32,21 +32,32 @@ module ClientBuilding
     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|
-      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
+      connection_handlers.each{|h| h.call(conn) }
     end
   end
 end

data/lib/brine/step_definitions/assertions.rb

@@ -25,6 +25,13 @@ Then(/^it is less than or equal to `([^`]*)`$/) do |value|
   selector.assert_that(value) {|v| be <= v}
 end
 
+# Be a little smarter than default.
+Then(/^it is empty$/) do
+  selector.assert_that(nil) do
+    satisfy{|i| i.nil? || (i.respond_to?(:empty?) && i.empty?) }
+  end
+end
+
 Then(/^it is including `([^`]*)`$/) do |value|
   selector.assert_that(value) {|v| include v }
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: brine-dsl
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Matt Whipple
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-12-05 00:00:00.000000000 Z
+date: 2018-02-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cucumber
@@ -220,6 +220,7 @@ files:
 - features/argument_transforms/template.feature
 - features/argument_transforms/whitespace.feature
 - features/assertions/is_a_valid.feature
+- features/assertions/is_empty.feature
 - features/assertions/is_equal_to.feature
 - features/assertions/is_including.feature
 - features/assertions/is_matching.feature
@@ -290,6 +291,7 @@ test_files:
 - features/argument_transforms/template.feature
 - features/argument_transforms/whitespace.feature
 - features/assertions/is_a_valid.feature
+- features/assertions/is_empty.feature
 - features/assertions/is_equal_to.feature
 - features/assertions/is_including.feature
 - features/assertions/is_matching.feature