diff --git a/articles/testing/variables-context.md b/articles/testing/variables-context.md index d1e38be..244928f 100644 --- a/articles/testing/variables-context.md +++ b/articles/testing/variables-context.md @@ -2,15 +2,23 @@ -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. -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. ->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 -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