diff --git a/articles/testing/variables-context.md b/articles/testing/variables-context.md index 8b13789..244928f 100644 --- a/articles/testing/variables-context.md +++ b/articles/testing/variables-context.md @@ -1 +1,101 @@ +# Using Context Variables + + +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. + +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 + +### With Captures + + + +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, to set multiple `$.ctx` values. + +### 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. + +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 '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 that just sets `myVariable` to the hardcoded value `123`: + +```javascript +$.ctx.set('myVariable', 123); +``` + +## Using Context Variables + + + +To use a context variable in a scenario, use the following syntax: + +``` +{$.ctx.myVariable} +``` + +Where: + +* `{...}` - Braces signify that this is a variable. +* `$` - The "single dollar sign" syntax is a reference to the current scenario's + 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, all context variables will +automatically be populated based on the contents of the `$.ctx` at +runtime. + +### 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 braces (`{}`) 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..b1eecd2 100644 --- a/articles/testing/variables-environment.md +++ b/articles/testing/variables-environment.md @@ -1 +1,93 @@ +# 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 from the active environment. 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 managing project environments, please review the [environment](../editor/environments.md) article. + +### With Captures + +Captures make it easy to "capture" values from your step request or result, and save them back to an environment variable for later use. Simply switch to the `captures` tab in the scenario step, and choose $$.env as the target property. + +Say you have a scenario step that sends an HTTP request to authenticate a new user. The response from that request includes an apiKey that you want to use for other requests. You can easily save that apiKey to an environment variable, for later re-use, by adding a capture in the form `$$.env.apiKey = output.body.apiKey`. After running the step, check your current environment variables and note the newly added apiKey! + +> Environment variables set via captures are only added to the user's private + variables, and are not sent to Stoplight. See the [Environment + section](../editor/environments.md) for more information. + +### With Scripting + +Scripting allows you to use more complicated logic in a scenario step. Scripts +are executed either before or after a step finishes. Scripts are plain +Javascript and give you direct access to the scenario environment through a +global `$$.env` object. + +To add variables to the environment, use the following syntax: + +```javascript +// store the step output (response) body's 'username' property in the environment +$$.env.set('username', output.body.get('username')); +``` + +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`). + +> Environment variables set via script are only added to the user's private + variables, and are not sent to Stoplight. See the [Environment + section](../editor/environments.md) for more information. + +## Using Environment Variables + + + +Use an environment variable in a scenario with the following syntax: + +``` +{$$.env.myVariable} +``` + +Where: + +* `{...}` - Braces signify that this is a variable. +* `$$` - The "double dollar sign" syntax is a reference to the global + scope. +* `env` - The `env` property holds the active environment's data. +* `myVariable` - This is the variable being referenced, which comes from the + active environment's resolved variables. Substitute your own variable name when using + this in your scenarios. + +When the scenario or step is run, any environment variables will +automatically be populated based on the editor's active 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 braces (`{}`) 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..ebcc5e9 100644 --- a/articles/testing/variables-overview.md +++ b/articles/testing/variables-overview.md @@ -1 +1,30 @@ +# Variables Overview +Variables in Stoplight provide a powerful and intuitive way to dynamically set, +update, and retrieve information at any step in a Scenario. + +Variables are stored in an [environment](../editor/environments.md). You can define one or more environments, +each with their own variables. This makes it easy to quickly swap out sets of +variables during testing. + +There are a variety of circumstances where you might consider using variables instead of hardcoding the value, for example: + +- __hostnames__: Instead of hard-coding a particular server location, use a variable +so that the host can quickly be changed to test multiple server locations (development versus production, for example). +- __api keys__ +- __usernames and passwords__ +- __ports__ +- __path parameters__: Instead of defining a request `GET /users/123`, you can define a request `GET /users/{$$.ctx.userId}`. + +There are two scopes for variables, which affect how and when they can be used. + +* __Environment Variables__ - Environment variables are scoped to the project, and are shared amongst all steps in your test run. They are persisted between test runs, and are great for data that does not change often (hostnames, ports, etc). See [here](./variables-environment.md) for more information on how to use environment variables. + +* __Context Variables__ - Context variables are scoped to the scenario, and are reset on every test run. They are useful to persist test and application state between scenario steps. Context variables are great for temporary information that is only relevant to the current test run. For example, you might store a newly created `userId` returned in your first step, to be used in the second step. This `userId` changes on every test run, which makes it a good context variable candidate. See [here](./variables-context.md) for more information on how to use context variables. + +*** + +**Related** + +* [Environment Variables](./variables-environment.md) +* [Context Variables](./variables-context.md)