Use the IDT context
When IDT runs a test suite, the test suite can access a set of data that can be used
to determine how each test runs. This data is called the IDT context. For example, user
data configuration provided by test runners in a userdata.json
file
is made available to test suites in the IDT context.
The IDT context can be considered a read-only JSON document. Test suites can retrieve data from and write data to the context using standard JSON data types like objects, arrays, numbers and so on.
Context schema
The IDT context uses the following format:
{ "config": { <config-json-content> "timeoutMultiplier": timeout-multiplier }, "device": { <device-json-device-element> }, "devicePool": { <device-json-pool-element> }, "resource": { "devices": [ { <resource-json-device-element> "name": "<resource-name>" } ] }, "testData": { "awsCredentials": { "awsAccessKeyId": "<access-key-id>", "awsSecretAccessKey": "<secret-access-key>", "awsSessionToken": "<session-token>" }, "logFilePath": "/path/to/log/file" }, "userData": { <userdata-json-content> } }
config
-
Information from the config.json file. The
config
field also contains the following additional field:config.timeoutMultiplier
-
The multiplier for the any timeout value used by the test suite. This value is specified by the test runner from the IDT CLI. The default value is
1
.
device
-
Information about the device selected for the test run. This information is equivalent to the
devices
array element in the device.json file for the selected device. devicePool
-
Information about the device pool selected for the test run. This information is equivalent to the top-level device pool array element defined in the
device.json
file for the selected device pool. resource
-
Information about resource devices from the
resource.json
file.resource.devices
-
This information is equivalent to the
devices
array defined in theresource.json
file. Eachdevices
element includes the following additional field:resource.device.name
-
The name of the resource device. This value is set to the
requiredResource.name
value in thetest.json
file.
testData.awsCredentials
-
The Amazon credentials used by the test to connect to the Amazon cloud. This information is obtained from the
config.json
file. testData.logFilePath
-
The path to the log file to which the test case writes log messages. The test suite creates this file if it doesn't exist.
userData
-
Information provided by the test runner in the userdata.json file.
Access data in the context
You can query the context using JSONPath notation from your JSON files and from
your text executable with the GetContextValue
and
GetContextString
APIs. The syntax for JSONPath strings to access
the IDT context varies as follows:
-
In
suite.json
andtest.json
, you use{{
. That is, do not use the root elementquery
}}$.
to start your expression. -
In
test_orchestrator.yaml
, you use{{
.query
}}If you use the deprecated state machine, then in
state_machine.json
, you use{{$.
.query
}} -
In API commands, you use
orquery
{{$.
, depending on the command. For more information, see the inline documentation in the SDKs.query
}}
The following table describes the operators in a typical JSONPath expression:
Operator | Description |
---|---|
$ |
The root element. Because the top-level context
value for IDT is an object, you will typically use $. to
start your queries. |
.childName |
Accesses the child element with name
childName from an object. If applied to an array,
yields a new array with this operator applied to each element. The
element name is case sensitive. For example, the query to access the
awsRegion value in the config object is
$.config.awsRegion . |
[start:end] |
Filters elements from an array, retrieving items
beginning from the start index and going up to the
end index, both inclusive. |
[index1, index2, ... , indexN] |
Filters elements from an array, retrieving items from only the specified indices. |
[?(expr)] |
Filters elements from an array using the
expr expression. This expression must evaluate to a
boolean value. |
To create filter expressions, use the following syntax:
<jsonpath>
|<value>
operator
<jsonpath>
|<value>
In this syntax:
-
jsonpath
is a JSONPath that uses standard JSON syntax. -
value
is any custom value that uses standard JSON syntax. -
operator
is one of the following operators:-
<
(Less than) -
<=
(Less than or equal to) -
==
(Equal to)If the JSONPath or value in your expression is an array, boolean, or object value, then this is the only supported binary operator that you can use.
-
>=
(Greater than or equal to) -
>
(Greater than) -
=~
(Regular expression match). To use this operator in a filter expression, the JSONPath or value on the left side of your expression must evaluate to a string and the right side must be a pattern value that follows the RE2 syntax.
-
You can use JSONPath queries in the form {{query
}} as
placeholder strings within the args
and
environmentVariables
fields in test.json
files
and within the environmentVariables
fields in
suite.json
files. IDT performs a context lookup and
populates the fields with the evaluated value of the query. For example, in the
suite.json
file, you can use placeholder strings to specify
environment variable values that change with each test case and IDT will populate
the environment variables with the correct value for each test case. However, when
you use placeholder strings in test.json
and
suite.json
files, the following considerations apply for
your queries:
-
You must each occurrence of the
devicePool
key in your query in all lower case. That is, usedevicepool
instead. -
For arrays, you can use only arrays of strings. In addition, arrays use a non-standard
item1, item2,...,itemN
format. If the array contains only one element, then it is serialized asitem
, making it indistinguishable from a string field. -
You cannot use placeholders to retrieve objects from the context.
Because of these considerations, we recommend that whenever possible, you use the
API to access the context in your test logic instead of placeholder strings in
test.json
and suite.json
files.
However, in some cases it might be more convenient to use JSONPath placeholders to
retrieve single strings to set as environment variables.