本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用 IDT 上下文
<a name="idt-context"></a>

IDT 运行测试套件时，测试套件可以访问一组数据，这些数据可用于确定每个测试的运行方式。这些数据被称为 IDT 上下文。例如，测试运行器在 `userdata.json` 文件中提供的用户数据配置可用于 IDT 环境中的测试套件。

IDT 上下文可以被视为只读 JSON 文档。测试套件可以使用对象、阵列、数字等标准 JSON 数据类型从上下文中检索数据并将数据写入上下文。

## 上下文架构
<a name="idt-context-schema"></a>

IDT 上下文采用以下格式：

```
{
    "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`  
[`config.json`文件](set-custom-idt-config.md#config-json-custom)中的信息。`config` 字段还包含以下附加字段：    
`config.timeoutMultiplier`  
测试套件使用的任何超时值的乘数。此值由 IDT CLI 中的测试运行器指定。默认值为 `1`。

`device`  
有关为测试运行选择的设备的信息。此信息等同于所选设备[`device.json`文件](set-custom-idt-config.md#device-config-custom)中的 `devices` 阵列元素。

`devicePool`  
有关为测试运行选择的设备池的信息。此信息等同于 `device.json` 文件中为所选设备池定义的顶级设备池阵列元素。

`resource`  
`resource.json` 文件中有关资源设备的信息。    
`resource.devices`  
此信息等同于 `resource.json` 文件中定义的 `devices` 阵列。每个 `devices` 元素都包括以下附加字段：    
`resource.device.name`  
资源的名称。此值设置为 `test.json` 文件中的 `requiredResource.name` 值。

`testData.awsCredentials`  
测试用于连接到 AWS 云的 AWS 凭证。此信息是从 `config.json` 文件中获得的。

`testData.logFilePath`  
测试用例写入日志消息的日志文件的路径。如果日志文件不存在，则会创建。

`userData`  
[`userdata.json`文件](set-custom-idt-config.md#userdata-config-custom)中由测试运行器提供的信息。

## 在上下文中访问数据
<a name="accessing-context-data"></a>

您可以使用 JSON 文件中的 JSONPath 表示法以及带 `GetContextValue` 和 `GetContextString` API 的文本可执行文件查询上下文。访问 IDT 上下文的 JSONPath 字符串的语法各不相同，如下所示：
+ 在 `suite.json` 和`test.json` 中，使用 `{{query}}`。也就是说，不要使用根元素 `$.` 开始表达式。
+ 在 `test_orchestrator.yaml` 中，使用 `{{query}}`。

  如果您使用已弃用的状态机，那么在 `state_machine.json` 中，请使用 `{{$.query}}`。
+ 在 API 命令中，根据命令的不同，您可以使用 `query` 或 `{{$.query}}`。有关更多信息，请参阅开发工具包中的内联文档。

下表描述典型 JSONPath 表达式中的运算符：


| Operator  | Description  | 
| --- |--- |
| \$1 | The root element. Because the top-level context value for IDT is an object, you will typically use \$1. 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 \$1.config.awsRegion. | 
| [start:end] | Filters elements from an array, retrieving items beginning from the 开启 index and going up to the 最终 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. | 

要创建筛选表达式，请使用以下语法：

```
<jsonpath> | <value> operator <jsonpath> | <value> 
```

在此语法中：
+ `jsonpath` 是一个使用标准 JSON 语法的 JSONPath。
+ `value` 是使用标准 JSON 语法的任何自定义值。
+ `operator` 下列运算符之一：
  + `<`（小于）
  + `<=`（小于或等于）
  + `==`（等于）

    如果表达式中的 jsonPath 或值是阵列、布尔值或对象值，则这是您可以使用的唯一受支持的二进制运算符。
  + `>=`（大于或等于）
  + `>`（大于）
  + `=~`（正则表达式匹配）。要在过滤器表达式中使用此运算符，表达式左侧的 jsonPath 或值必须计算为字符串，而右侧必须是遵循 [RE2 语法](https://github.com/google/re2/wiki/Syntax)的模式值。

您可以使用 \$1\$1*query*\$1\$1 形式的 JSONPath 查询作为 `test.json` 文件 `args` 和`environmentVariables` 字段以及 `suite.json` 文件 `environmentVariables` 字段中的占位符字符串。IDT 执行上下文查找，并使用查询的评估值填充字段。例如，在 `suite.json` 文件中，您可以使用占位符字符串来指定随每个测试用例而变化的环境变量值，IDT 将使用每个测试用例的正确值填充环境变量。但是，当您在 `test.json` 和 `suite.json` 文件中使用占位符字符串时，以下注意事项适用于您的查询：
+ 查询中每次出现的 `devicePool` 密钥都必须全部使用小写字母。也就是说，改用 `devicepool`。
+ 对于数组，只能使用字符串数组。此外，数组使用非标准 `item1, item2,...,itemN` 格式。如果数组仅包含一个元素，则将其序列化为 `item`，使其与字符串字段没有区别。
+ 不能使用占位符从上下文中检索对象。

出于这些考虑，我们建议您尽可能使用 API 来访问测试逻辑中的上下文，而不是 `test.json` 和 `suite.json` 文件中的占位符字符串。但是，在某些情况下，使用 JsonPath 占位符检索要设置为环境变量的单个字符串可能会更方便。