brine-dsl 0.7.0 → 0.8.0

data/docs/specs.html

@@ -440,6 +440,14 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <li><a href="#__span_class_feature_name_resource_cleanup_span"><span class="feature name">Resource Cleanup</span></a></li>
 </ul>
 </li>
+<li><a href="#_assignment">Assignment</a>
+<ul class="sectlevel2">
+<li><a href="#__span_class_feature_name_a_parameter_span"><span class="feature name">A Parameter</span></a></li>
+<li><a href="#__span_class_feature_name_a_random_string_span"><span class="feature name">A Random String</span></a></li>
+<li><a href="#__span_class_feature_name_a_timestamp_span"><span class="feature name">A Timestamp</span></a></li>
+<li><a href="#__span_class_feature_name_a_value_from_a_response_attribute_span"><span class="feature name">A Value From A Response Attribute.</span></a></li>
+</ul>
+</li>
 <li><a href="#_selection">Selection</a>
 <ul class="sectlevel2">
 <li><a href="#__span_class_feature_name_any_element_span"><span class="feature name">Any Element</span></a></li>
@@ -1065,6 +1073,224 @@ When a resource is created at `/some/path`</code></pre>
 </div>
 </div>
 <div class="sect1">
+<h2 id="_assignment">Assignment</h2>
+<div class="sectionbody">
+<div class="sect2">
+<h3 id="__span_class_feature_name_a_parameter_span"><span class="feature name">A Parameter</span></h3>
+<div class="paragraph">
+<p>An identifier can be assigned the value of the provided parameter.</p>
+</div>
+<div class="sect3">
+<h4 id="__span_class_scenario_name_parameter_assignment_span"><span class="scenario name">Parameter assignment.</span></h4>
+<div class="ulist step-list">
+<ul>
+<li>
+<p><strong>Given</strong> a file named "features/parameter.feature" with:</p>
+</li>
+</ul>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-gherkin" data-lang="gherkin">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`</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><strong>When</strong> I run <code>cucumber --strict features/parameter.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">1 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_random_string_span"><span class="feature name">A Random String</span></h3>
+<div class="paragraph">
+<p>An identifier can be assigned a random string with decent entropy.</p>
+</div>
+<div class="sect3">
+<h4 id="__span_class_scenario_name_random_string_assignment_span"><span class="scenario name">Random string assignment.</span></h4>
+<div class="ulist step-list">
+<ul>
+<li>
+<p><strong>Given</strong> a file named "features/random.feature" with:</p>
+</li>
+</ul>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-gherkin" data-lang="gherkin">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 }}`</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><strong>When</strong> I run <code>cucumber --strict features/random.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">8 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_timestamp_span"><span class="feature name">A Timestamp</span></h3>
+<div class="paragraph">
+<p>An identifier can be assigned a current timestamp.</p>
+</div>
+<div class="sect3">
+<h4 id="__span_class_scenario_name_timestamp_assignment_span"><span class="scenario name">Timestamp assignment.</span></h4>
+<div class="ulist step-list">
+<ul>
+<li>
+<p><strong>Given</strong> a file named "features/timestamp.feature" with:</p>
+</li>
+</ul>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-gherkin" data-lang="gherkin">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 }}`</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><strong>When</strong> I run <code>cucumber --strict features/timestamp.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">2 passed</code></pre>
+</div>
+</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="__span_class_feature_name_a_value_from_a_response_attribute_span"><span class="feature name">A Value From A Response Attribute.</span></h3>
+<div class="paragraph">
+<p>An identifier can be assigned a value extracted from a response attribute.</p>
+</div>
+<div class="sect3">
+<h4 id="__span_class_scenario_name_assorted_attribute_extractions_span"><span class="scenario name">Assorted attribute extractions.</span></h4>
+<div class="ulist step-list">
+<ul>
+<li>
+<p><strong>Given</strong> a file named "features/response_attribute.feature" with:</p>
+</li>
+</ul>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="highlightjs highlight"><code class="language-gherkin" data-lang="gherkin">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"]`</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><strong>When</strong> I run <code>cucumber --strict features/response_attribute.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">3 passed</code></pre>
+</div>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><strong>And</strong> it should pass</p>
+</li>
+</ul>
+</div>
+</div>
+</div>
+</div>
+</div>
+<div class="sect1">
 <h2 id="_selection">Selection</h2>
 <div class="sectionbody">
 <div class="sect2">
@@ -1833,7 +2059,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 2018-05-30 13:07:46 EDT
+Last updated 2018-06-17 22:22:57 EDT
 </div>
 </div>
 </body>

data/docs/src/cookbook.adoc

@@ -2,16 +2,17 @@
 Matt Whipple <http://github.com/mwhipple[@mwhipple]>
 :description: Cookbook for the Brine REST Testing DSL
 :keywords: Brine, Cucumber, REST, DSL
+:gh_repo: https://github.com/brightcove/brine
 
 == 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.
+Brine but are not considered part of Brine's (current) responsibility.
+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.
+Many of these will also be platform specific and be subject to further
+organization once platforms beyond ruby are supported.
 
 == Intercepting of HTTP Calls
 
@@ -27,11 +28,13 @@ of anything that belongs in the specification.
 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).
+{gh_repo}/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
@@ -78,66 +81,80 @@ additional overhead to provision a new account. When testing a secured
 system valid accounts are needed for representative testing, but provisioning
 a new account may be difficult or outside the scope of the system that is being
 actively tested. If tested functionality involves enacting account-wide changes
-and the number of accounts is limited, then that is likely to unfortunately prevent
-complete test isolation.
+and the number of accounts is limited, then that is likely to unfortunately
+prevent 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.
-Here the term "assurances" is used..primarily because it starts with `a` which lends
-itself to relevant files being listed towards the beginning alphabetically in a given directory.
+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. Here the term "assurances" is used...primarily because it
+starts with `a` which lends itself to relevant files being listed towards the
+beginning alphabetically in a given directory.
 
 The goal of assurances is to specify conditions which are expected before other
-tests are to be run. Preferably the dependent tests should also explicitly declare the
-dependency but a significant solution for that is not established. Assurances therefore
-validate that preconditions are met; ideally if such preconditions can be established
-idempotently then the assurances can do so before the validation.
+tests are to be run. Preferably the dependent tests should also explicitly
+declare the dependency but a significant solution for that is not established.
+Assurances therefore validate that preconditions are met; ideally if such
+preconditions can be established 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
-would also imply a state change). If assurances are configured for a system which should
-also be tested, then appropriate tests should exist (including those that may validate any
-behavior relied upon by the assurance).
+**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 would also imply a state change). If assurances are
+configured for a system which should also be tested, then appropriate tests
+should exist (including those that may validate any behavior relied upon by
+the assurance).
 
 ==== Consequences
-As mentioned previously assertions help in cases where tests cannot be fully isolated,
-and therefore some known state must be established and reused across tests (and such state
-should *not* change). A practical reason for this is to allow for overlapping test executions.
-If tests are not fully isolated, state is being changed, and test runs overlap, then tests
-may fail non-deterministically due to one test run pulling the state out from another. This
-in the simplest form can be a nuisance but it also effectively precludes the ability to speed
-up test runs through the use of parallelism/asynchronicity.
+
+As mentioned previously assertions help in cases where tests cannot be fully
+isolated, and therefore some known state must be established and reused across
+tests (and such state should *not* change). A practical reason for this is to
+allow for overlapping test executions.
+If tests are not fully isolated, state is being changed, and test runs overlap,
+then tests may fail non-deterministically due to one test run pulling the state
+out from another. This in the simplest form can be a nuisance but it also
+effectively precludes the ability to speed up test runs through the use of
+parallelism/asynchronicity.
 
 _TODO: Enumerate drawbacks_
 
 === Recipe
-This can be done using standard cucumber tags. Assurances can be defined in designated
-`assure_*.feature` files where each Feature is appropriately tagged:
+
+This can be done using standard cucumber tags. Assurances can be defined in
+designated `assure_*.feature` files where each Feature is appropriately tagged:
+
 [source,gherkin]
 ----
 @assure
 Feature: Some preconditions are verified...
 ----
+
 And then a Rake task is added to run those tagged features:
+
 [source,ruby]
 ----
 Cucumber::Rake::Task.new(:assure) do |t|
    t.cucumber_opts = "#{ENV['CUCUMBER_OPTS']} --tags @assure"
 end
 ----
+
 The Rake task that runs the other tests then depends on that task:
+
 [source,ruby]
 ----
 task :invoke_cuke => [:assure] do
   #Run cucumber, potentially in parallel and likely with --tags `@assure`
 end
 ----
-This approach tests preconditions and will avoid running the rest of the tests if they
-are not (relying on standard Rake behavior). The assurances can also be run with different
-Cucumber behavior so that the full test suite can be more stochastic
-(randomized/non-serialized) while the assurances can be more controlled.
+
+This approach tests preconditions and will avoid running the rest of the tests
+if they are not (relying on standard Rake behavior). The assurances can also be
+run with different Cucumber behavior so that the full test suite can be more
+stochastic (randomized/non-serialized) while the assurances can be more
+controlled.