brine-dsl 0.7.0 → 0.8.0

data/docs/guide.html

@@ -546,11 +546,12 @@ type.</p>
 </dd>
 <dt class="hdlist1">Type Coercion</dt>
 <dd>
-<p>Related to transforms, a facility to coerce types is also provided. This allows
-more intelligent comparison of inputs which have been transformed to a
+<p>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.</p>
+the string to a date/time so that the values can be compared using the proper
+semantics.</p>
 </dd>
 <dt class="hdlist1"><a href="#_resource_cleanup">Resource Cleanup</a></dt>
 <dd>
@@ -616,7 +617,8 @@ requiring any additional ruby code.</p>
 <div class="sectionbody">
 <div class="paragraph">
 <p>We&#8217;ll write some tests against <a href="http://myjson.com/api" class="bare">http://myjson.com/api</a>
-(selected fairly arbitrary from the list at  <a href="https://github.com/toddmotto/public-apis" class="bare">https://github.com/toddmotto/public-apis</a>).
+(selected fairly arbitrary from the list at
+<a href="https://github.com/toddmotto/public-apis" class="bare">https://github.com/toddmotto/public-apis</a>).
 The API is being explored for the sake of this tutorial,
 which also serves to bolster this library to support the effort.</p>
 </div>
@@ -648,7 +650,8 @@ end</code></pre>
 <p>which could then be called with <code>rake cucumber</code>. The rake approach
 can be extended for different tasks for each environment, each
 of which sets the appropriate environment variables allowing the
-test code itself to follow <a href="https://12factor.net/config">Twelve-Factor App guidelines</a>
+test code itself to follow
+<a href="https://12factor.net/config">Twelve-Factor App guidelines</a>
 where Rake provides sugary convenience.</p>
 </div>
 </div>
@@ -673,8 +676,8 @@ testing the response status from a GET request.</p>
 <h3 id="_a_write_request">A Write Request</h3>
 <div class="paragraph">
 <p>For POST, PATCH and PUT requests you&#8217;ll normally want to include a request body.
-To support this, additional data can be added to the requests before they are sent
-(see <a href="#_request_construction">Request Construction</a>).</p>
+To support this, additional data can be added to the requests before they are
+sent (see <a href="#_request_construction">Request Construction</a>).</p>
 </div>
 <div class="listingblock">
 <div class="content">
@@ -723,14 +726,16 @@ can check that the <code>uri</code> response child matches the expected pattern.
 <h2 id="_environment_variables">Environment Variables</h2>
 <div class="sectionbody">
 <div class="paragraph">
-<p>Some Brine behavior can be tuned by passing it appropriate environment variables, listed here.</p>
+<p>Some Brine behavior can be tuned by passing it appropriate environment
+variables, listed here.</p>
 </div>
 <div class="dlist">
 <dl>
 <dt class="hdlist1"><code>BRINE_LOG_HTTP</code></dt>
 <dd>
-<p>Output HTTP traffic to stdout. Any truthy value will result in request and response
-metadata being logged, a value of <code>DEBUG</code> (case insensitive) will also log the bodies.</p>
+<p>Output HTTP traffic to stdout. Any truthy value will result in request and
+response metadata being logged, a value of <code>DEBUG</code> (case insensitive) will
+also log the bodies.</p>
 </dd>
 <dt class="hdlist1"><code>BRINE_LOG_BINDING</code></dt>
 <dd>
@@ -747,15 +752,16 @@ metadata being logged, a value of <code>DEBUG</code> (case insensitive) will als
 <h3 id="_the_use_of_code_code_s">The use of <code>`</code>s</h3>
 <div class="paragraph">
 <p>Backticks/grave accents are used as <em>parameter delimiters</em>. It is perhaps
-most helpful to think of them in those explicit terms rather than thinking of them
-as an alternate <em>quote</em> construct. In particular quoting implies that the parameter
-value is a string value, while the step transforms allow for alternate data types.</p>
+most helpful to think of them in those explicit terms rather than thinking of
+them as an alternate <em>quote</em> construct. In particular quoting implies that the
+parameter value is a string value, while the step transforms allow for
+alternative data types.</p>
 </div>
 <div class="paragraph">
-<p><code>`</code>s were chosen as they are less common than
-many other syntactical elements and also allow for the use of logically significant
-quoting within paremeter values while hopefully avoiding the need for escape artistry
-(as used for argument transforms).</p>
+<p><code>`</code>s were chosen as they are less common than many other syntactical
+elements and also allow for the use of logically significant
+quoting within paremeter values while hopefully avoiding the need for escape
+artistry (as used for argument transforms).</p>
 </div>
 </div>
 </div>
@@ -764,16 +770,19 @@ quoting within paremeter values while hopefully avoiding the need for escape art
 <h2 id="_selection_and_assertion">Selection and Assertion</h2>
 <div class="sectionbody">
 <div class="paragraph">
-<p>As tests are generally concerned with performing assertions, a testing DSL should be
-able to express the variety of assertions that may be needed. Because these are likely
-to be numerous, it could easily lead to duplicated logic or geometric growth of code due
-to the combinations of types of assertions and the means to select the inputs for the assertion.</p>
+<p>As tests are generally concerned with performing assertions, a testing DSL
+should be able to express the variety of assertions that may be needed. Because
+these are likely to be numerous, it could easily lead to duplicated logic or
+geometric growth of code due to the combinations of types of assertions and the
+means to select the inputs for the assertion.</p>
 </div>
 <div class="paragraph">
-<p>To avoid this issue the concepts of selection and assertion are considered separate operations in Brine.
-Internally this corresponds to two steps: the first assigns a selector;
-the second passes the assertion to that selector which is responsible for applying the assertion against
-the selected value(s). In standard step use this will still be expressed as a single step,
+<p>To avoid this issue the concepts of selection and assertion are considered
+separate operations in Brine. Internally this corresponds to two steps: the
+first assigns a selector;
+the second passes the assertion to that selector which is responsible for
+applying the assertion against the selected value(s). In standard step use this
+will still be expressed as a single step,
 and dynamic step definitions are used to split the work appropriately.</p>
 </div>
 <div class="paragraph">
@@ -786,58 +795,67 @@ and dynamic step definitions are used to split the work appropriately.</p>
 </div>
 <div class="paragraph">
 <p>Will be split where the subject of the step (<code>the value of the response body</code>)
-defines the selector and the predicate of the step <code>is equal to `foo`</code> defines
-the assertion (which is translated to a step such as <code>Then it is equal to `foo`</code>).</p>
+defines the selector and the predicate of the step
+<code>is equal to `foo`</code> defines the assertion (which is translated to a
+step such as <code>Then it is equal to `foo`</code>).</p>
 </div>
 <div class="paragraph">
-<p>The result of this is that the assertion steps will always follow a pattern where the subject
-resembles <code>the value of &#8230;&#8203;</code> and the predicate always resembles <code>is &#8230;&#8203;</code>. Learning the selection
-phrases and the assertion phrases and combining them should be a more efficient and flexible way
-to become familiar with the language instead of focusing on the resulting combined steps.</p>
+<p>The result of this is that the assertion steps will always follow a pattern
+where the subject resembles <code>the value of &#8230;&#8203;</code> and the predicate always
+resembles <code>is &#8230;&#8203;</code>. Learning the selection phrases and the assertion phrases
+and combining them should be a more efficient and flexible way to become
+familiar with the language instead of focusing on the resulting combined steps.</p>
 </div>
 <div class="paragraph">
 <p>The chosen approach sacrifices eloquence for the sake of consistency.
-The predicate will always start with <code>is</code> which can lead to awkward language such as
-<code>is including</code> rather than simply <code>includes</code>.
+The predicate will always start with <code>is</code> which can lead to awkward language
+such as <code>is including</code> rather than simply <code>includes</code>.
 The consistency provides additional benefits such as consistent modification:
-for instance <code>is not</code> can always be use for negation rather than working out the appropriate
-phrasing for a more natural sounding step (let alone the logic).</p>
+for instance <code>is not</code> can always be use for negation rather than working out the
+appropriate phrasing for a more natural sounding step (let alone the logic).</p>
 </div>
 <div class="paragraph">
-<p>One of the secondary goals of this is that assertion step definitions should very simple to
-write and modifiers (such as negation) should be provided for free to those definitions.
-As assertion definitions are likely to be numerous and potentially customized, this should help optimize code economy.</p>
+<p>One of the secondary goals of this is that assertion step definitions should
+be very simple to write and modifiers (such as negation) should be provided for
+free to those definitions.
+As assertion definitions are likely to be numerous and potentially customized,
+this should help optimize code economy.</p>
 </div>
 <div class="sect2">
 <h3 id="_selection_modifiers">Selection Modifiers</h3>
 <div class="paragraph">
-<p>To pursue economical flexibility Brine steps attempt to balance step definitions which accommodate variations
-while keeping the step logic and patterns fairly simple. Selection steps in particular generally accept some
-parameters that affect their behavior. This allows the relatively small number of selection steps to provide
-the flexibility to empower the more numerous assertion steps.</p>
+<p>To pursue economical flexibility Brine steps attempt to balance step definitions
+which accommodate variations while keeping the step logic and patterns fairly
+simple. Selection steps in particular generally accept some parameters that
+affect their behavior. This allows the relatively small number of selection
+steps to provide the flexibility to empower the more numerous assertion steps.</p>
 </div>
 <div class="sect3">
 <h4 id="_traversal">Traversal</h4>
 <div class="paragraph">
-<p>Selection steps can generally target the root of the object specified (such as the response body)
-or some nodes within the object if it is a non-scalar value (for instance a child of the response body).
-This is indicated in the <a href="#_selection">step reference selection steps</a> by the <code>[$TRAVERSAL]</code> placeholder.
-<code>child `$EXPRESSION`</code> or <code>children `$EXPRESSION`</code> can optionally be
-inserted at the placeholder to select nested nodes as described in <a href="#_traversal_2">Traversal</a>.</p>
+<p>Selection steps can generally target the root of the object specified (such as
+the response body) or some nodes within the object if it is a non-scalar value
+(for instance a child of the response body). This is indicated in the
+<a href="#_selection">step reference selection steps</a> by the <code>[$TRAVERSAL]</code> placeholder.
+<code>child `$EXPRESSION`</code> or <code>children `$EXPRESSION`</code> can
+optionally be inserted at the placeholder to select nested nodes as described
+in <a href="#_traversal_2">Traversal</a>.</p>
 </div>
 </div>
 <div class="sect3">
 <h4 id="_negation">Negation</h4>
 <div class="paragraph">
 <p>The selectors also currently handle negation of the associated assertions.
-This is potentially counter-intuitive but as previously mentioned the intent is that this
-should ease the creation of assertions. If negation is added to a selector that it is expected that
-the assertion will <em>fail</em>.</p>
+This is potentially counter-intuitive but as previously mentioned the intent is
+that this should ease the creation of assertions. If negation is added to a
+selector that it is expected that the assertion will <em>fail</em>.</p>
 </div>
 <div class="paragraph">
-<p>Negation will be normally indicated in the <a href="#_selection">step reference selection steps</a> by the presence
-of the <code>[not]</code> placeholder. A similar placeholder may be used that is more readable but leads to an equivalent
-inversion of the semantics of the statement. To negate the step, the text within the <code>[]</code>s should be inserted
+<p>Negation will be normally indicated in the
+<a href="#_selection">step reference selection steps</a> by the presence
+of the <code>[not]</code> placeholder. A similar placeholder may be used that is more
+readable but leads to an equivalent inversion of the semantics of the statement.
+To negate the step, the text within the <code>[]</code>s should be inserted
 in the indicated position.</p>
 </div>
 <div class="admonitionblock note">
@@ -847,10 +865,12 @@ in the indicated position.</p>
 <i class="fa icon-note" title="Future Versions"></i>
 </td>
 <td class="content">
-Handling this in the selectors is (as mentioned) counter-intuitive and unnecessarily couples the selector
-to the assertion. It is currently done for practical reasons but is likely to be replaced in a future version
-after (or as part of) the initial port of the library to another platform. When it is replaced, all existing steps
-will remain supported through at least one more major revision and most should (most should remain unchanged).
+Handling this in the selectors is (as mentioned) counter-intuitive and
+unnecessarily couples the selector to the assertion. It is currently done for
+practical reasons but is likely to be replaced in a future version after (or as
+part of) the initial port of the library to another platform. When it is
+replaced, all existing steps will remain supported through at least one more
+major revision and most should (most should remain unchanged).
 </td>
 </tr>
 </table>
@@ -872,9 +892,12 @@ Use at your own risk, this feature is <strong>not presently supported</strong>.
 </table>
 </div>
 <div class="paragraph">
-<p>For anyone that likes to live on the (relative) edge or if this gathers notable interest&#8230;&#8203;the above also
-provides an implicit feature: after a value is selected multiple assertions could be performed against it.
-For instance:</p>
+<p>For anyone that likes to live on the (relative) edge or if this gathers notable
+interest&#8230;&#8203;the above also provides an implicit feature: after a value is
+selected multiple assertions could be performed against it.</p>
+</div>
+<div class="paragraph">
+<p>For instance:</p>
 </div>
 <div class="listingblock">
 <div class="content">
@@ -883,9 +906,10 @@ And it is of the type `String`</code></pre>
 </div>
 </div>
 <div class="paragraph">
-<p>Though this may work in simple cases the present design is likely to produce surprising results since
-some aspects (such as negation) are handled by the selector so it would be inherited by the conjunctions
-even though it wouldn&#8217;t read that way.</p>
+<p>Though this may work in simple cases the present design is likely to produce
+surprising results since some aspects (such as negation) are handled by the
+selector so it would be inherited by the conjunctions even though it wouldn&#8217;t
+read that way.</p>
 </div>
 </div>
 </div>
@@ -894,13 +918,14 @@ even though it wouldn&#8217;t read that way.</p>
 <h2 id="_traversal_2">Traversal</h2>
 <div class="sectionbody">
 <div class="paragraph">
-<p>The language exposed by Brine is flat but the data returned by the server is likely
-to include deeper data structures such as objects and collections. To allow selection within
-such structures a <code>traversal</code> language is embedded within some steps which will be indicated
-by the use of the <code>TRAVERSAL</code> placeholder.</p>
+<p>The language exposed by Brine is flat but the data returned by the server is
+likely to include deeper data structures such as objects and collections. To
+allow selection within such structures a <code>traversal</code> language is embedded within
+some steps which will be indicated by the use of the <code>TRAVERSAL</code> placeholder.</p>
 </div>
 <div class="paragraph">
-<p>The traversal language consists of a selected subset of <a href="http://goessner.net/articles/JsonPath/">JsonPath</a>.</p>
+<p>The traversal language consists of a selected subset of
+<a href="http://goessner.net/articles/JsonPath/">JsonPath</a>.</p>
 </div>
 <div class="admonitionblock note">
 <table>
@@ -909,12 +934,14 @@ by the use of the <code>TRAVERSAL</code> placeholder.</p>
 <i class="fa icon-note" title="The Selected Subset"></i>
 </td>
 <td class="content">
-The subset of JsonPath functionality has been chosen that is believed to support all needed
-test cases without requiring deep familiarity with JsonPath. This may lead to more numerous simple steps
-in place of fewer steps that use unsupported expressions. Additionally Brine is intended to be
-ported to a range of platforms and so only those steps outlined here will be supported across those platforms.
-JsonPath expressions <em>not</em> listed below will not be explicitly disallowed but are not officially supported
-(will not be tested and will not be ported to another platform if needed).
+The subset of JsonPath functionality has been chosen that is believed to support
+all needed test cases without requiring deep familiarity with JsonPath. This may
+lead to more numerous simple steps in place of fewer steps that use unsupported
+expressions. Additionally Brine is intended to be ported to a range of platforms
+and so only those steps outlined here will be supported across those platforms.
+JsonPath expressions <em>not</em> listed below will not be explicitly disallowed but
+are not officially supported (will not be tested and will not be ported to
+another platform if needed).
 </td>
 </tr>
 </table>
@@ -922,12 +949,15 @@ JsonPath expressions <em>not</em> listed below will not be explicitly disallowed
 <div class="sect2">
 <h3 id="_cardinality">Cardinality</h3>
 <div class="paragraph">
-<p>Each traversal expression will select <em>all</em> matching nodes which is therefore represented as a collection.
-Often, however, only a single node is expected or desired. Therefore the traversal expression will also
-be accompanied by a phrase which defines the expected cardinality, normally <code>child</code> vs. <code>children</code>. <code>children</code> will
-<em>always</em> return an array while <code>child</code> will return what would be the first element in that array. <code>child</code> should be
-used when accessing a specific node within the tree, while <code>children</code> should be used for what amounts to a query
-across multiple nodes (such as testing the value of a field for every element in a collection).</p>
+<p>Each traversal expression will select <em>all</em> matching nodes which is therefore
+represented as a collection. Often, however, only a single node is expected or
+desired. Therefore the traversal expression will also be accompanied by a phrase
+which defines the expected cardinality, normally <code>child</code> vs. <code>children</code>.
+<code>children</code> will <em>always</em> return an array while <code>child</code> will return what would be
+the first element in that array. <code>child</code> should be used when accessing a
+specific node within the tree, while <code>children</code> should be used for what amounts
+to a query across multiple nodes (such as testing the value of a field for every
+element in a collection).</p>
 </div>
 </div>
 <div class="sect2">
@@ -936,9 +966,18 @@ across multiple nodes (such as testing the value of a field for every element in
 <dl>
 <dt class="hdlist1"><code>.$KEY</code></dt>
 <dd>
-<p>  Access the <code>KEY</code> named child of the starting node. The leading <code>.</code> can be
+<p>Access the <code>KEY</code> named child of the starting node. The leading <code>.</code> can be
 omitted if at the start of an expression.</p>
 </dd>
+<dt class="hdlist1"><code>.[$INDEX]</code></dt>
+<dd>
+<p>Access the element of the array at index <code>INDEX</code></p>
+</dd>
+<dt class="hdlist1"><code>.[$FROM:$TO]</code></dt>
+<dd>
+<p>Access a slice of the array containing the elements at index <code>FROM</code> through
+<code>TO</code> (including both limits).</p>
+</dd>
 </dl>
 </div>
 </div>
@@ -948,26 +987,32 @@ omitted if at the start of an expression.</p>
 <h2 id="_resource_cleanup">Resource Cleanup</h2>
 <div class="sectionbody">
 <div class="paragraph">
-<p>All test suites should clean up after themselves as a matter of hygiene and to help enforce test independence
-and reproducibility. This is particularly important for this library given that it is likely the systems under test
-are likely to remain running; accumulated uncleaned resources are at best a nuisance to have to weed through and
-at worst raise some costs or other due to heightened consumption of assorted resources (as opposed to more
-ephemeral test environments).</p>
+<p>All test suites should clean up after themselves as a matter of hygiene and to
+help enforce test independence and reproducibility. This is particularly
+important for this library given that it is likely the systems under test
+are likely to remain running; accumulated uncleaned resources are at best a
+nuisance to have to weed through and at worst raise some costs or other due to
+heightened consumption of assorted resources (as opposed to more ephemeral test
+environments).</p>
 </div>
 <div class="paragraph">
-<p>Brine therefore provides mechanisms to assist in cleaning up those resources which are created as part of a test run.
-A conceptual hurdle for this type of functionality is that it is very unlikely to be part of the feature that is being
-specified, and therefore should ideally not be part of the specification. Depending on the functionality
-(and arguably the <a href="https://www.martinfowler.com/articles/richardsonMaturityModel.html">maturity</a>) of the
-API, most or all of the cleanup can be automagically done based on convention. There are tentative plans to support
-multiple techniques for cleaning up resources based on how much can be implicitly ascertained&#8230;&#8203;though presently there
-exists only one.</p>
+<p>Brine therefore provides mechanisms to assist in cleaning up those resources
+which are created as part of a test run. A conceptual hurdle for this type of
+functionality is that it is very unlikely to be part of the feature that is
+being specified, and therefore should ideally not be part of the specification.
+Depending on the functionality (and arguably the
+<a href="https://www.martinfowler.com/articles/richardsonMaturityModel.html">maturity</a>)
+of the API, most or all of the cleanup can be automagically done based on
+convention. There are tentative plans to support multiple techniques for
+cleaning up resources based on how much can be implicitly
+ascertained&#8230;&#8203;though presently there exists only one.</p>
 </div>
 <div class="sect2">
 <h3 id="_step_indicating_resource_to_delete">Step indicating resource to DELETE</h3>
 <div class="paragraph">
-<p>If the API supports DELETE requests to remove created resources but it is either desirable or necessary to specify
-what those resource PATHS are, a step can be used to indicate which resources should be DELETEd upon test completion.</p>
+<p>If the API supports DELETE requests to remove created resources but it is either
+desirable or necessary to specify what those resource PATHS are, a step can be
+used to indicate which resources should be DELETEd upon test completion.</p>
 </div>
 <div class="paragraph">
 <p><em>see <a href="#_cleanup">Cleanup Step Definitions</a></em></p>
@@ -991,27 +1036,34 @@ a <a href="https://en.wikipedia.org/wiki/Builder_pattern">Builder</a>.</p>
 <dl>
 <dt class="hdlist1"><code>When a $METHOD is sent to `$PATH`</code></dt>
 <dd>
-<p>  As every request to a REST API is likely to have a significant
-HTTP <code>METHOD</code> and <code>PATH</code>, this step is considered required and is therefore used
-to send the built request. This should therefore be the <strong>last</strong> step for any
-given request that is being built.</p>
+<p>As every request to a REST API is likely to have a significant
+HTTP <code>METHOD</code> and <code>PATH</code>, this step is considered required and is therefore
+used to send the built request. This should therefore be the <strong>last</strong> step for
+any given request that is being built.</p>
 </dd>
 <dt class="hdlist1"><code>When the request body is assigned:</code></dt>
 <dd>
-<p>  The multiline content provided will be assigned to the body of the request.
+<p>The multiline content provided will be assigned to the body of the request.
 This will normally likely be the JSON representation of data.</p>
 </dd>
-<dt class="hdlist1"><code>When the request query parameter `$PARAMETER` is assigned `$VALUE`</code></dt>
-<dd>
-<p>  Assign <code>VALUE</code> to the request query <code>PARAMETER</code>.
-The value will be URL encoded and the key/value pair appended to the URL using
-the appropriate <code>?</code> or <code>&amp;</code> delimiter.
-The order of the parameters in the resulting URL should be considered undefined.</p>
-</dd>
+</dl>
+</div>
+<div class="paragraph">
+<p><code>When the request query parameter `$PARAMETER` is assigned
+`$VALUE`</code>::
+  Assign <code>VALUE</code> to the request query <code>PARAMETER</code>.
+  The value will be URL encoded and the key/value pair appended to the URL using
+  the appropriate <code>?</code> or <code>&amp;</code> delimiter.
+  The order of the parameters in the resulting URL should be considered
+  undefined.</p>
+</div>
+<div class="dlist">
+<dl>
 <dt class="hdlist1"><code>When the request header `$HEADER` is assigned `$VALUE`</code></dt>
 <dd>
-<p>  Assign <code>VALUE</code> to the request header <code>HEADER</code>.
-Will overwrite any earlier value for the specified header, including earlier steps or defaults.</p>
+<p>Assign <code>VALUE</code> to the request header <code>HEADER</code>.
+Will overwrite any earlier value for the specified header, including earlier
+steps or defaults.</p>
 </dd>
 </dl>
 </div>
@@ -1022,13 +1074,17 @@ Will overwrite any earlier value for the specified header, including earlier ste
 <dl>
 <dt class="hdlist1"><code>When a resouce is created at `$PATH`</code></dt>
 <dd>
-<p>Mark <code>PATH</code> as a resource to DELETE after the test is run. See <a href="#_resource_cleanup">Resource Cleanup</a></p>
+<p>Mark <code>PATH</code> as a resource to DELETE after the test is run.
+See <a href="#_resource_cleanup">Resource Cleanup</a></p>
 </dd>
 </dl>
 </div>
 </div>
 <div class="sect2">
 <h3 id="_assignment">Assignment</h3>
+<div class="paragraph">
+<p><a href="specs.html#_assignment"><span class="icon"><i class="fa fa-cogs"></i></span> Specification</a></p>
+</div>
 <div class="dlist">
 <dl>
 <dt class="hdlist1"><code>When `$IDENTIFIER` is assigned `$VALUE`</code></dt>
@@ -1037,14 +1093,19 @@ Will overwrite any earlier value for the specified header, including earlier ste
 </dd>
 <dt class="hdlist1"><code>When `$IDENTIFIER` is assigned a random string</code></dt>
 <dd>
-<p>  Assigns a random string (UUID) to <code>IDENTIFIER</code>.
+<p>Assigns a random string (UUID) to <code>IDENTIFIER</code>.
 This is particularly useful to assist with test isolation.</p>
 </dd>
 <dt class="hdlist1"><code>When `$IDENTIFIER` is assigned a timestamp</code></dt>
 <dd>
-<p>  Assigns to <code>IDENTIFIER</code> a timestamp value representing the instant at
+<p>Assigns to <code>IDENTIFIER</code> a timestamp value representing the instant at
 which the step was evaluated.</p>
 </dd>
+<dt class="hdlist1"><code>When `$IDENTIFIER` is assigned the response (body|status|headers) [$TRAVERSAL]</code></dt>
+<dd>
+<p>Assigns to <code>IDENTIFIER</code> the value extracted from the specified response
+attribtute (at the optional traversal path).</p>
+</dd>
 </dl>
 </div>
 </div>
@@ -1056,11 +1117,14 @@ which the step was evaluated.</p>
 <div class="paragraph">
 <p><em>see <a href="#_selection_and_assertion">Selection and Assertion</a></em></p>
 </div>
+<div class="paragraph">
+<p><em>TODO: Replace all the explicit attributes.</em></p>
+</div>
 <div class="dlist">
 <dl>
-<dt class="hdlist1"><code>Then the value of the response status is</code></dt>
+<dt class="hdlist1"><code>Then the value of the response (body|status|headers) is</code></dt>
 <dd>
-<p>Select the status code of the current HTTP response.</p>
+<p>Select the sepecified attribute of the current HTTP response.</p>
 </dd>
 <dt class="hdlist1"><code>Then the value of the response body [$TRAVERSAL] is [not]</code></dt>
 <dd>
@@ -1101,13 +1165,15 @@ which the step was evaluated.</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>
+<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 of length `$VALUE`</code></dt>
 <dd>
-<p>  Assert that the value exposes a length attribute and the value of that
+<p>Assert that the value exposes a length attribute and the value of that
 attribute is <code>VALUE</code>.</p>
 </dd>
 <dt class="hdlist1"><code>Then it is a valid `$TYPE`</code></dt>
@@ -1147,7 +1213,7 @@ wiring and documentation. The current supported types are:</p>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2018-05-30 12:55:31 EDT
+Last updated 2018-06-17 22:38:06 EDT
 </div>
 </div>
 </body>

data/docs/index.html

@@ -426,7 +426,8 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 <div id="toc" class="toc2">
 <div id="toctitle">Table of Contents</div>
 <ul class="sectlevel1">
-<li><a href="#_documentation">Documentation</a></li>
+<li><a href="#_overview">Overview</a></li>
+<li><a href="#_documents">Documents</a></li>
 </ul>
 </div>
 </div>
@@ -439,11 +440,21 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 </div>
 </div>
 <div class="sect1">
-<h2 id="_documentation">Documentation</h2>
+<h2 id="_overview">Overview</h2>
 <div class="sectionbody">
 <div class="paragraph">
-<p>The following are the documentation resources presently available.</p>
+<p>The documentation should provide the background information to
+get started using Brine and a framework for figuring out specific details.
+The focus of guides will be on concepts and high level information while
+more comprehensive and finer grained information will be provided by
+specifications and source. Recipes will be provided for problems which
+are common, interesting, or anything anyone wants to contribute :).</p>
 </div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_documents">Documents</h2>
+<div class="sectionbody">
 <div class="dlist">
 <dl>
 <dt class="hdlist1"><a href="guide.html"><span class="icon"><i class="fa fa-book"></i></span> User Guide</a></dt>
@@ -460,12 +471,15 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
 </dd>
 </dl>
 </div>
+<div class="paragraph">
+<p><em>TODO: The current Cookbook name should be qualified to match its scope</em></p>
+</div>
 </div>
 </div>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2018-05-30 12:01:52 EDT
+Last updated 2018-06-17 15:55:45 EDT
 </div>
 </div>
 </body>