From 7285d7a9e143c737a311b3d59af34da798c87e95 Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Fri, 2 Feb 2018 13:11:03 -0600 Subject: [PATCH] First drafts of all three articles. --- articles/testing/variables-context.md | 99 +++++++++++++++++++++++ articles/testing/variables-environment.md | 83 +++++++++++++++++++ articles/testing/variables-overview.md | 25 ++++++ 3 files changed, 207 insertions(+) diff --git a/articles/testing/variables-context.md b/articles/testing/variables-context.md index 8b13789..7bf4a87 100644 --- a/articles/testing/variables-context.md +++ b/articles/testing/variables-context.md @@ -1 +1,100 @@ +# Using Context Variables + + +Context variables in Stoplight allow you to dynamically store and communicate +data between various steps in a scenario, by storing data in the scenario +"context". This makes it possible to initialize and store data in one step, and +then use that data again in subsequent steps. + +Data stored in the context is _not_ saved once a test has completed, so it is +important to only store temporary data useful 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. + +## Setting Context Variables + +### With Captures + + + +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. + +Multiple captures can be applied to the same step. + +### With Scripting + + + +Scripting allows you to use more complicated logic in a scenario step. Scripts +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: + +```javascript +// store the step output body's 'apiKey' object in the context +$.ctx.set('apiKey', output.body.get('apiKey')); +``` + +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: + +```javascript +myVariable = "hello"; +$.ctx.set('myVariable', myVariable); +``` + +## Referencing Context Variables + + + +To reference a context variable in a scenario, use the following syntax: + +``` +{$.ctx.myVariable} +``` + +Where: + +* `{...}` - Curly brackets signify that this is a variable reference. See the + [variables overview](./variables-overview.md) section for more information on + how variables are used. +* `$` - The "single dollar sign" syntax is a reference to the current scenario's + "context". +* `ctx` - Every scenario context has an `ctx` property that signifies this being + a reference to the editor's environment. +* `myVariable` - This is the variable being referenced, which comes from the + project's `.stoplight.yml` file. Substitute your own variable name when using + this in a scenario. + +When the scenario or step is run, any environment variable references will +automatically be populated based on the editor's current environment. + +### In Scripts + +Similar to the example above, when referencing a context variable in a step +script, use the following syntax: + +```javascript +$.ctx.get('myVariable'); +``` + +Where the curly brackets are absent, and we are using the `get()` method for +retrieving the context variable under the `myVariable` key. + +*** + +**Related** + +* [Environment Overview](../editor/environments.md) +* [Environment Configuration](../editor/editor-configuration.md) +* [Variables Overview](./variables-overview.md) +* [Context Variables](./variables-context.md) diff --git a/articles/testing/variables-environment.md b/articles/testing/variables-environment.md index 8b13789..ccc9025 100644 --- a/articles/testing/variables-environment.md +++ b/articles/testing/variables-environment.md @@ -1 +1,84 @@ +# Using Environment Variables + + +> If you have not already done so, we recommend reviewing the +[Environments](../editor/environments.md) article before continuing. + +Environment variables in Stoplight allow you to dynamically retrieve information +in a scenario using the editor's [environment +configuration](../editor/editor-configuration.md). This makes it possible to +switch between different environments with ease, having variables automatically +populate based on the current environment. + +## Setting Environment Variables + +### With the Editor Configuration + +For information on setting environment variables, please review the [environment +configuration](../editor/editor-configuration.md) article. + +### With Scripting + +Scripting allows you to use more complicated logic in a scenario step. Scripts +are executed either before or after a step request finishes. Scripts are plain +Javascript and give you direct access to the scenario environment through the +global `$$.env` object. + +To add variables to the environment, use the following syntax: + +```javascript +// store the step output body's 'hostname' object in the environment +$$.env.set('hostname', output.body.get('hostname')); +``` + +Where the `$$.env.set(x, y)` function adds the data referenced in the second +argument (`y`) to the environment under the string value of the first argument +(`x`). + +## Referencing Environment Variables + + + +To reference an environment variable in a scenario, use the following syntax: + +``` +{$$.env.myVariable} +``` + +Where: + +* `{...}` - Curly brackets signify that this is a variable reference. See the + [variables overview](./variables-overview.md) section for more information on + how variables are used. +* `$$` - The "double dollar sign" syntax is a reference to the scenario's global + scope. +* `env` - Every scenario has a global `env` property that signifies this being a + reference to the editor's environment. +* `myVariable` - This is the variable being referenced, which comes from the + project's `.stoplight.yml` file. Substitute your own variable name when using + this in a scenario. + +When the scenario or step is run, any environment variable references will +automatically be populated based on the editor's current environment. + +### In Scripts + +Similar to the example above, when referencing an environment variable in a step +script, use the following syntax: + +```javascript +$$.env.get('myVariable'); +``` + +Where the curly brackets are absent, and we are using the `get()` method for +retrieving the environment variable under the `myVariable` key. + +*** + +**Related** + +* [Environment Overview](../editor/environments.md) +* [Environment Configuration](../editor/editor-configuration.md) +* [Variables Overview](./variables-overview.md) +* [Context Variables](./variables-context.md) diff --git a/articles/testing/variables-overview.md b/articles/testing/variables-overview.md index 8b13789..1bcc295 100644 --- a/articles/testing/variables-overview.md +++ b/articles/testing/variables-overview.md @@ -1 +1,26 @@ +# Variables +Variables in Stoplight provide a powerful and intuitive way to allow you to +dynamically set, update, and retrieve information at any step in a Scenario. +Variables can be used in many different ways, however the two primary methods +for using variable data is through: + +* __Environments__ - Variables can be persisted in the environment configuration, + allowing data to be automatically populated depending on the editor's + environment. See [here](./variables-environment.md) for more information on + how to use variables in an environment. + +* __Contexts__ - Variables can be stored in a scenario "context", allowing for + test and application state to be persisted between scenario steps. See + [here](./variables-context.md) for more information on how to use variables in + a scenario context. + +Variables can be used to modify both request and response objects, including +URL's, headers, the request/response body, and more. + +*** + +**Related** + +* [Environment Variables](./variables-environment.md) +* [Context Variables](./variables-context.md)