From 7285d7a9e143c737a311b3d59af34da798c87e95 Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Fri, 2 Feb 2018 13:11:03 -0600 Subject: [PATCH 1/7] 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) From 60edd173dd22579353c66ecd00806a873d0df74d Mon Sep 17 00:00:00 2001 From: Robert Wallach Date: Fri, 2 Feb 2018 15:54:27 -0600 Subject: [PATCH 2/7] Update variables-context.md --- articles/testing/variables-context.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/articles/testing/variables-context.md b/articles/testing/variables-context.md index 7bf4a87..daa8c7e 100644 --- a/articles/testing/variables-context.md +++ b/articles/testing/variables-context.md @@ -2,12 +2,11 @@ -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. +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. -Data stored in the context is _not_ saved once a test has completed, so it is + +Data stored in the context is _not_ saved once a test has completed. Therefore, 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, @@ -23,7 +22,8 @@ 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. + +>Multiple captures can be applied to the same step. ### With Scripting From fe5e946afe94b0a4ac19cd5285d9f70833ada00f Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Fri, 2 Feb 2018 16:45:47 -0600 Subject: [PATCH 3/7] Clarify what curly brackets are. Other minor updates and clarifications. --- articles/testing/variables-context.md | 23 +++++++++++------------ articles/testing/variables-environment.md | 12 ++++++++---- 2 files changed, 19 insertions(+), 16 deletions(-) diff --git a/articles/testing/variables-context.md b/articles/testing/variables-context.md index 7bf4a87..ca379c0 100644 --- a/articles/testing/variables-context.md +++ b/articles/testing/variables-context.md @@ -64,19 +64,18 @@ To reference a context variable in a scenario, use the following syntax: 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. +* `{...}` - Braces 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. + 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. -When the scenario or step is run, any environment variable references will -automatically be populated based on the editor's current environment. +When the scenario or step is run, any context variable references will +automatically be populated based on the contents of the scenario context at +runtime. ### In Scripts @@ -87,7 +86,7 @@ script, use the following syntax: $.ctx.get('myVariable'); ``` -Where the curly brackets are absent, and we are using the `get()` method for +Where the braces (`{}`) are absent, and we are using the `get()` method for retrieving the context variable under the `myVariable` key. *** diff --git a/articles/testing/variables-environment.md b/articles/testing/variables-environment.md index ccc9025..0a4d2ef 100644 --- a/articles/testing/variables-environment.md +++ b/articles/testing/variables-environment.md @@ -36,6 +36,10 @@ 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. + ## Referencing Environment Variables @@ -48,9 +52,9 @@ To reference an environment variable in a scenario, use the following syntax: 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. +* `{...}` - Braces 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 @@ -71,7 +75,7 @@ script, use the following syntax: $$.env.get('myVariable'); ``` -Where the curly brackets are absent, and we are using the `get()` method for +Where the braces (`{}`) are absent, and we are using the `get()` method for retrieving the environment variable under the `myVariable` key. *** From 6242466fbd0faa9b6973d3f5e80faff379d3d640 Mon Sep 17 00:00:00 2001 From: Robert Wallach Date: Mon, 5 Feb 2018 13:49:38 -0600 Subject: [PATCH 4/7] Update variables-context.md --- articles/testing/variables-context.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/testing/variables-context.md b/articles/testing/variables-context.md index b0f9bc6..d1e38be 100644 --- a/articles/testing/variables-context.md +++ b/articles/testing/variables-context.md @@ -7,7 +7,7 @@ data between various steps in a scenario. Stoplight stores data in the scenarios Data stored in the context is _not_ saved once a test has completed. Therefore, it is -important to only store temporary data useful within the current test or +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. From b6f257d1829d06f4d0b607fd37c22724d4e61961 Mon Sep 17 00:00:00 2001 From: Marc MacLeod Date: Wed, 7 Feb 2018 17:27:25 -0600 Subject: [PATCH 5/7] Update variables-overview.md --- articles/testing/variables-overview.md | 34 ++++++++++++++------------ 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/articles/testing/variables-overview.md b/articles/testing/variables-overview.md index 1bcc295..ebcc5e9 100644 --- a/articles/testing/variables-overview.md +++ b/articles/testing/variables-overview.md @@ -1,22 +1,26 @@ -# Variables +# Variables Overview -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: +Variables in Stoplight provide a powerful and intuitive way to dynamically set, +update, and retrieve information at any step in a Scenario. -* __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. +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. -* __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. +There are a variety of circumstances where you might consider using variables instead of hardcoding the value, for example: -Variables can be used to modify both request and response objects, including -URL's, headers, the request/response body, and more. +- __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. *** From 55cb3405845eb6ad1b3f837fb47aabda76c003f7 Mon Sep 17 00:00:00 2001 From: Marc MacLeod Date: Wed, 7 Feb 2018 17:35:40 -0600 Subject: [PATCH 6/7] Update variables-environment.md --- articles/testing/variables-environment.md | 45 +++++++++++++---------- 1 file changed, 25 insertions(+), 20 deletions(-) diff --git a/articles/testing/variables-environment.md b/articles/testing/variables-environment.md index 0a4d2ef..b1eecd2 100644 --- a/articles/testing/variables-environment.md +++ b/articles/testing/variables-environment.md @@ -6,8 +6,7 @@ [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 +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. @@ -15,21 +14,30 @@ populate based on the current environment. ### With the Editor Configuration -For information on setting environment variables, please review the [environment -configuration](../editor/editor-configuration.md) article. +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 request finishes. Scripts are plain -Javascript and give you direct access to the scenario environment through the +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 body's 'hostname' object in the environment -$$.env.set('hostname', output.body.get('hostname')); +// 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 @@ -40,11 +48,11 @@ argument (`y`) to the environment under the string value of the first argument variables, and are not sent to Stoplight. See the [Environment section](../editor/environments.md) for more information. -## Referencing Environment Variables +## Using Environment Variables -To reference an environment variable in a scenario, use the following syntax: +Use an environment variable in a scenario with the following syntax: ``` {$$.env.myVariable} @@ -52,19 +60,16 @@ To reference an environment 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. -* `$$` - The "double dollar sign" syntax is a reference to the scenario's global +* `{...}` - Braces signify that this is a variable. +* `$$` - The "double dollar sign" syntax is a reference to the global scope. -* `env` - Every scenario has a global `env` property that signifies this being a - reference to the editor's environment. +* `env` - The `env` property holds the active environment's data. * `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. + 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 variable references will -automatically be populated based on the editor's current environment. +When the scenario or step is run, any environment variables will +automatically be populated based on the editor's active environment. ### In Scripts From b1610a8395db16cff5e8ee3b085bcbb38cbbc4a4 Mon Sep 17 00:00:00 2001 From: Marc MacLeod Date: Wed, 7 Feb 2018 17:51:02 -0600 Subject: [PATCH 7/7] Update variables-context.md --- articles/testing/variables-context.md | 58 ++++++++++++++------------- 1 file changed, 30 insertions(+), 28 deletions(-) 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