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:

// 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:

$.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:

$.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 Articles