Variables

Variables provide a number of capabilities when writing Jikken tests. They can hold literal values, values parsed from data files, and generated values based on criteria you specify. They allow you to embed fields from the environment or from Jikken configuration files. You can even extract variables from response bodies 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 request bodies.

Note

Variable names are case-sensitive. If you name a variable name (all lowercase), 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 full or 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 in another.

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

Tip

While you can define a variable for a URL in your test definition, it is often more useful to leverage environment or configuration file-defined variables, since the URL will likely differ between environments.

Parameters

Variables can be embedded into parameter values. This allows you to leverage generated values as well as pass values between tests 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 inject the current date into your tests. It is also possible to modify this value to generate a relative date - see Modifying variables for details.

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: Bearer ${token}

Body

Variables can be used for both request and response body definitions. They enable you to reference an external file or reuse 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 do 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 method is using the variables field in a Jikken test definition. For example, if you wanted to create a variable that contained a username, you might define it like so:

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

This creates a variable called username with a literal string value.

Name requirements

Variable names must be at least one character long. Valid characters include upper and lowercase letters, numbers, hyphens (-), and underscores (_).

What if you wanted to run the same request multiple times while iterating through different users? Variable values also support arrays via the valueSet field, which allows a test to cycle through a set of values as it runs multiple iterations.

variables:
  - name: username
    valueSet: ["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 containing john.doe@jikken.io, and then on the second iteration, the ${username} variable would equal jane.doe@jikken.io instead.

Loading data from files

You can also create a variable with data from a file. Instead of writing literal 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 contain 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 using relative paths for greater flexbility.

Using environment variables

Jikken tests have access to variables from the environment. These can be defined through specially-prefixed environment variables or in 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, you would define it as JIKKEN_GLOBAL_url in your system environment.

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

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

.jikken

[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 of other variables defined in your test files.

For example, if you were writing a test in which you wanted to iterate over two different endpoints with the same base URL, you could do so like this:

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

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

Extracting data from API calls

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

From our login.jkt example test:

login.jkt

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 returned status code equals 200. If this is true, then it creates a new variable named token with the value contained in the auth.token field of the response body.

If the response JSON looks like this:

{
  "auth": {
    "token": "itsatoken"
  }
}

Then the token variable would contain the value itsatoken.

Modifying variables

In the case where we want to generate a value that is relative to a different value, we can use the modifier block.

variables:
  - name: nextWeek
    value: ${TODAY}
    modifier:
      operation: add
      value: 7
      unit: days

This variable starts with the value of TODAY, which is a built-in variable containing the current date. It then adds 7 days to that value, giving us a date that is 7 days in the future.

This functionality is currently only supported for dates and date-times, but we plan to expand on it in the future.

Generating variables

Instead of defining literal values for a variable, you can generate values based on specified constraints. Let’s say you wanted to generate a random username:

variables:
  - name: username
    type: String
    length: 10

When you specify a type instead of a value, Jikken knows to generate a new value for the variable. Here, we also specify length: 10, so username will contain a random 10-character string.

Jikken supports data generation for many different types. For details, see the Data Generation page.

Full format

Below is the full format for variables in the test definition, with all possible fields.

See the Full Format page for details and descriptions of each field.

variables:
- name:
  type:
  value:
  valueSet:
  file:
  min:
  max:
  oneOf:
  noneOf:
  anyOf:
  length:
  minLength:
  maxLength:
  schema:
  modifier:
    operation:
    value:
    unit:
  format:

Built-in variables

For convenience, Jikken provides built-in global variables for some commonly-used values. These work the same way as user-defined global variables.

We will likely expand this list in the future.

Variable	Description
NOW	The current timestamp in the local system’s timezone, in the format YYYY-MM-DD hh:mm:ss.sss.
NOW_UTC	The current timestamp in UTC, in the format YYYY-MM-DD hh:mm:ss.sss.
TODAY	The current date in the local system’s timezone, in the format YYYY-MM-DD.
TODAY_UTC	The current date in UTC, in the format YYYY-MM-DD.

Note

The “current timestamp” used in NOW and NOW_UTC is evaluated once, at the beginning of the test session. These values will remain consistent throughout all tests executed in the same session.