Update variables-context.md

articles/testing/variables-context.md

@@ -2,15 +2,23 @@
 
 <!--(FIXME - SHOW WRITING VARIABLE TO CONTEXT IN STEP)-->
 
-Context variables allow you to dynamically store and communicate
-data between various steps in a scenario. Stoplight stores data in the scenarios "context", which makes it possible to initialize and store data in one step. This allows data to be used again in subsequent steps. 
+Context variables allow you to dynamically store and share data between steps in a scenario. Contrary to environment variables, context variables are _not_ saved once a test has completed. Therefore, context variables are only suitable for temporary data. 
 
+Context variables are scoped to the scenario, _not_ the collection. This means that two scenarios can both read/write the same context variable `myVar`, and not conflict with each other. Environment variables, on the other hand, are shared amongst all scenarios, and are scoped to the collection.
 
-Data stored in the context is _not_ saved once a test has completed. Therefore, it is
-important to only store useful temporary data within the current test or
-scenario execution. At the start of a test run, the scenario context is emptied.
-Good examples of data to store in a context would be things like ID's,
-usernames, and randomly generated tokens.
+At the start of a test run, the context object is empty. Good examples of data to store in a context would be things like ID's, usernames, and randomly generated tokens.
+
+## Use Case
+
+Context variables make it possible to chain related steps together. For example, say we have the following set of actions to perform:
+
+1. Create User, `POST /users`. Returns a new user object, with an `id` property.
+2. Get User, `GET /users/{$.ctx.userId}`.
+3. Delete User, `DELETE /users/{$.ctx.userId}`.
+
+Somehow we need to use the `id` property for the user created in step #1 to build the request in steps #2 and #3. This is a great case for context variables, since the data is temporary (the new user's id changes every test run, and is only needed in this single scenario).
+
+To accomplish this, we would capture/set the `$.ctx.userId` property to `output.id` in step #1, and then use that variable to create the request urls in #2 and #3 (shown above).
 
 ## Setting Context Variables
 
@@ -18,12 +26,10 @@ usernames, and randomly generated tokens.
 
 <!--(FIXME - SHOW USING THE CAPTURE MENU IN A SCENARIO STEP)-->
 
-By using a "capture" in a scenario step, data can be saved to the current
-context by referencing either the step output, the scenario response, the
-environment, or the step context.
+The capture UI in the step editor makes it easy to set `$.ctx` values. You can use values from the step output or input, including headers, response bodies, etc.
 
 <!-- theme: info --> 
->Multiple captures can be applied to the same step.
+> Multiple captures can be applied to the same step, to set multiple `$.ctx` values.
 
 ### With Scripting
 
@@ -34,29 +40,28 @@ are executed either before or after a step request finishes. Scripts are plain
 Javascript and give you direct access to the scenario context through the global
 `$.ctx` object.
 
-To add variables to the scenario context, use the following syntax:
+For example, if we wanted to set the `userId` property as described in the use case above, we would add an after script to the first step with the code:
 
 ```javascript
-// store the step output body's 'apiKey' object in the context
-$.ctx.set('apiKey', output.body.get('apiKey'));
+// store the step output body's 'id' property in the context, for use in subsequent steps
+$.ctx.set('userId', output.body.get('id'));
 ```
 
 Where the `$.ctx.set(x, y)` function adds the data referenced in the second
 argument (`y`) to the context under the string value of the first argument
 (`x`). 
 
-Here is another example:
+Here is another example that just sets `myVariable` to the hardcoded value `123`:
 
 ```javascript
-myVariable = "hello";
-$.ctx.set('myVariable', myVariable);
+$.ctx.set('myVariable', 123);
 ```
 
-## Referencing Context Variables
+## Using Context Variables
 
 <!--(FIXME - SHOW USING A CONTEXT VARIABLE IN A SCENARIO STEP)-->
 
-To reference a context variable in a scenario, use the following syntax:
+To use a context variable in a scenario, use the following syntax:
 
 ```
 {$.ctx.myVariable}
@@ -64,17 +69,14 @@ To reference a context variable in a scenario, use the following syntax:
 
 Where:
 
-* `{...}` - Braces signify that this is a variable reference. See the [variables
-  overview](./variables-overview.md) section for more information on how
-  variables are used.
+* `{...}` - Braces signify that this is a variable.
 * `$` - The "single dollar sign" syntax is a reference to the current scenario's
-  runtime scope.
-* `ctx` - Every scenario step has a `ctx` property that allows access to the
-  runtime context (where variables can be stored for later use).
-* `myVariable` - This is the variable being referenced within the context.
+  runtime scope. Again, context variables are scoped to the individual scenario, not the global collection!
+* `ctx` - This is the actual context object onto which values are stored and retrieved.
+* `myVariable` - This is the name of the variable being referenced within the context.
 
-When the scenario or step is run, any context variable references will
-automatically be populated based on the contents of the scenario context at
+When the scenario or step is run, all context variables will
+automatically be populated based on the contents of the `$.ctx` at
 runtime.
 
 ### In Scripts