Scenario Parameters

Introduction

Scenario parameters allow you to pass parameters into your scenario from a test configuration. This enables sharing a single scenario definition across many different test configurations. Scenario parameters are often used to set the target URL of a test, credentials, number of virtual users, timeouts, etc.

Scenarios can declare parameter names in the Declared Params section. When you create a test configuration and choose that scenario, any declared parameters will automatically appear and prompt you for a value. The test configuration can also add additional parameters as required.

During test execution, scenario parameter values can be accessed as environment variables, system properties, or a params object depending on the scenario type chosen (i.e. Node.js script, JMeter, Gatling, Locust, Selenium, PhantomJs/SlimerJs, etc).

Scenario parameter values can be encrypted.

Declaring Parameters

Within any scenario there is a Declared Params widget. Declare any parameters here including whether or not they should be required or not. Any parameters declared here will appear when creating a test configuration and this scenario is chosen.

Declaring Parameters

Setting Parameters

Each test configuration that uses a scenario will be able to set different values for declared parameters as well as adding additional parameters. Parameter values can be set via the website or via the API.

Setting Parameters via the Website

See the Scenario Params section of the test configuration setup screen.

Setting Parameters

Setting Parameters via the API

  • Trigger URL: Each test configuration has one or more trigger URLs. You can pass a parameter values as query parameters or in the body as a JSON object. See the trigger URL documentation for more details

  • Simple API: When triggering a test via our simple API you can pass parameters using the params[*] parameter. So for example: -F "params[url]=https://google.com".

Accessing Parameters

In your scenario you can access the parameter value using a variety of approaches:

  1. As environment variable PARAM_[name] where name is the name of the parameter in upper case with any spaces removed.
  2. As a system property with the same name as the parameter name. Only available for JMeter and Selenium Java scenarios.
  3. With the params object for Node.js, PhantomJS, and SlimerJS scripts. For example parameter Abc is accessible with params['Abc'].

Encrypting Parameters

Scenario parameter values can be encrypted. This can be a useful way to pass sensitive information like credentials, keys, etc to your scenario.

Each test case has a unique 2048 bit public/private RSA key pair.

Each parameter is encrypted using a uniquely generated 256-bit AES symmetric key and IV. The symmetric AES key is encrypted into the parameter using the RSA public key and included with the encrypted parameter contents.

Each test case's public key is available for download so that parameter values can also be encrypted locally.

The private key is stored encrypted using an AWS KMS key in Testable's account by default. You can also choose to have Testable encrypt parameters using your own AWS KMS key or Azure Key Vault key or GCP Key Ring key as well. To do this you need to setup your cloud account as a test runner source first (Org Management => Test Runner Sources) and then choose your account for the Encryption field at Org Management => Settings.

During test execution, parameter values are decrypted just before sending to the test runners for execution over an SSL connection. The decrypted values are then available to your test like any other parameter. These decrypted values are not stored or logged anywhere by Testable.

Encrypted parameters have the format secret:[IV]:[rsa-encrypted-aes-key]:[aes-encrypted-contents].

You can encrypt any parameter value easily via our website. Next to any parameter there is an Encrypt button that will encrypt the value using that test case's public key.

Encrypting a Parameter

Download Public Key

There are 2 ways to download your public key.

  1. https://api.testable.io/test-cases/[testCaseId]/key. The testCaseId is the number after https://a.testable.io in the URL when viewing a test case on our website.

  2. Click on any test case and in the upper right click the certificate icon.

Public Key Icon

Encrypt Value Locally

Use openssl to encrypt a value locally once you've downloaded the test case's public key. Here is an example script that assumes your test case public key is saved at testable-key-123.pub:

#!/bin/bash

# contents to encode
contents="my secret text"

# generate a random key (32 byte) and iv (16 byte)
key=$(openssl rand -hex 32)
iv=$(openssl rand -hex 16)

# encrypt the key using the RSA public key for the test case
encryptedAesKey=$(echo -n "$key" | xxd -r -p | openssl rsautl -encrypt -pubin -inkey testable-key-123.pub -out >(base64))

# encrypt the contents using your key + iv
encryptedContents=$(echo -n $contents | openssl enc -aes-256-cbc -K $key -iv $iv -base64)

# convert your hexadecimal iv to base64 as required by Testable
ivb64=$(echo -n $iv | xxd -r -p | base64)

# format to store as your parameter value on Testable
echo "secure:$ivb64:$encryptedAesKey:$encryptedContents"

The final output should be used as your parameter value.