Variables

Variables provide a number of capabilities when writing Jikken tests. They allow you to embed values from the environment, configuration files, and data files. They let you hard-code values, generate values based on criteria, or even extract values from JSON responses which can then be injected into future tests or stages.

Using Variables

Jikken Test Definitions support variable embedding, similar to JavaScript string interpolation. Variables have names, and you reference the name in the location you wish to embed the value. The format looks like ${name}, where name is the name of the variable. Variables can be used in URL definitions, parameter values, header values, and post bodies.

Note

Variable names are case sensitive. If you name a variable name (all lowercase) then you must use ${name} where you want it to be embedded. ${Name} would not be a valid reference.

URLs

You can use variables to embed partial URLs in your tests. This is a common technique for leveraging the same test across different environments, or crawling URLs returned from one stage or test into another.

request:
  url: https://${baseUrl}/api/v1/examples/status
response:
  status: 200
variables:
  - name: baseUrl
    value: api.jikken.io

Tip

While you can define variables for a URL in your test definition, it is often more useful to leverage environment or configuration file-defined variables to embed into your URLs.

Parameters

Variables can be embedded into parameter values. This allows you to leverage generated values as well as pass values between tests and/or stages.

request:
  url: https://api.jikken.io/api/v1/query
  params:
    - param: date
      value: ${TODAY}

Note

The TODAY variable is provided via the test runner as a built-in value. This allows you to have relative date values to inject into your tests. By leveraging the features of the variable section you can create a variable which takes the TODAY value and modifies it before injecting it into URLs, params, bodies, etc. For more information on built-ins, see the section below on Built-in Variables.

Headers

Headers also support variable embedding. While this is most commonly used for the Authorization header, it can be used for any header to support complex testing flows.

request:
  url: https://api.jikken.io/api/v1/examples/status
  headers:
    - header: Authorization
      value: ${token}

Body

Variables can be used for both request and response body definitions. They enable you to reference an external file or to customize sections of pre-defined payloads.

request:
  method: Post
  url: https://api.jikken.io/api/v1/examples/login
  body: ${credentials}
response:
  status: 200
variables:
  - name: credentials
    file: creds.json

Caution

Variables which load data from files are a powerful feature, but they come with some risks. The file must exist at an absolute path or a relative path based on the location of the test jkt file location. If the file is missing, the test execution will fail at runtime.

Creating Variables

Basic Format

There are many ways to create variables for Jikken tests. The most basic example is using the variables field in a Jikken test definition. For example, if you wanted to create a variable that contained a username to use in a request, you might define it as in the example below.

variables:
  - name: username
    value: john.doe@jikken.io

What if you wanted to run the same request multiple times while iterating through multiple users? Variables support arrays, which allows a test to run multiple iterations while it cycles through the array values.

variables:
  - name: username
    value: ["john.doe@jikken.io", "jane.doe@jikken.io"]

Now if you were to run the test with two iterations, it would run once with the ${username} variable equalling john.doe@jikken.io, and on the second iteration the ${username} variable would equal jane.doe@jikken.io.

Environment Variables

Jikken tests have access to variables from the environment. These can be defined through specially prefixed ENVVARS or from the .jikken configuration file. Environment variables that you wish to expose directly to Jikken tests must be prefixed with JIKKEN_GLOBAL_.

For example, if you wanted to define a variable named url with a value of https://api.jikken.io, you would name to name it JIKKEN_GLOBAL_url in your system environment.

export JIKKEN_GLOBAL_url=https://api.jikken.io

An alternative is to define environment variables in the .jikken configuration file. The same example would be defined as follows:

[globals]
url="https://api.jikken.io"

Unlike localized variables defined in test files, global variables only accept a single string value. While this does limit what the global variable itself is capable of doing, you can leverage global variables inside other variables, which are defined in your test files.

For example, if you were writing a test in which you wanted to iterate over two separate endpoints which needed to reference a global variable, you could do so like this:

variables:
  - name: baseUrl
    value: ["${url}/path/one", "${url}/path/two"]

Now, instead of using the url global variable in your request defintion, you can use the locally-created variable baseUrl which leverages the global variable.

Loading Data from Files

Jikken tests also enable you to inject data from files. Instead of hard-coding JSON in a body block for a request or response, you can reference a separate JSON file which contains the data.

To load a file’s data into a variable, you leverage the file field instead of the value field in the variable definition.

variables:
  - name: requestBody
    file: postbody.json

The file field must equal a valid filename. It should be a relative path to the test definition file’s location, or an absolute path on the target system (we recommend relative paths).

Extracting Values from API Calls

Variables can also be created by extracting data from JSON responses. This is accomplished via the response.extract field.

From our login.jkt example test:

id: auth
request:
  method: Post
  url: https://api.jikken.io/api/v1/examples/login
  body: {
    "username": "testuser",
    "password": "password"
  }
response:
  status: 200
  extract:
    - name: token
      field: auth.token

In this test, the response section checks that the response status code equals 200. If this is true, then it creates a new variable named token with the value contained in the auth.token node of the response JSON.

If the response JSON looks like this:

{
  "auth": {
    "token": "blah1234"
  }
}

Then the token variable would contain the value blah1234.

Full Format

variables:
- name:
  type:
  value:
  file:
  modifier:
    operation:
    value:
    unit:
  format:

Built-in Variables

To make it easier to support certain use cases, Jikken provides some built-in variables. These work the same as user-defined global variables. We will likely expand this list in the future.

Variable	Description
TODAY	The TODAY global variable provides the current date of the local system’s timezone.
TODAY_UTC	The TODAY_UTC global variable provides the current date in UTC.