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

# 使用 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,
        "idtRootPath": <path/to/IDT/root>
    },
    "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-config-custom.md#config-json-custom)中的信息。`config` 字段还包含以下附加字段：    
**`config.timeoutMultiplier`**  
测试套件使用的任何超时值的乘数。此值由 IDT CLI 中的测试运行器指定。默认值为 `1`。  
**`config.idRootPath`**  
此值是配置 `userdata.json` 文件时 IDT 的绝对路径值的占位符。编译命令和刷写命令会使用此值。

**`device`**  
有关为测试运行选择的设备的信息。此信息等同于所选设备[`device.json`文件](set-config-custom.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-config-custom.md#userdata-config-custom)中由测试运行器提供的信息。

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

您可以使用配置文件中的 JSONPath 符号以及带有和的文本可执行文件中的符号来查询上下文`GetContextString` APIs。`GetContextValue`用于访问 IDT 上下文的 JSONPath 字符串的语法各不相同，如下所示：
+ 在 `suite.json` 和`test.json` 中，使用 `{{query}}`。也就是说，不要使用根元素 `$.` 开始表达式。
+ 在 `statemachine.json` 中，使用 `{{$.query}}`。
+ 在 API 命令中，根据命令的不同，您可以使用 `query` 或 `{{$.query}}`。有关更多信息，请参阅中的内联文档 SDKs。

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


| 运算符  | 说明  | 
| --- | --- | 
| \$1 | 根元素。由于 IDT 的顶级上下文值是一个对象，因此，您通常会使用 \$1. 来启动查询。 | 
| .childName | 使用来自对象的名称 childName 访问子元素。如果应用到数组，则生成一个新数组，并将此运算符应用到每个元素。该元素名称区分大小写。例如，访问 config 对象中 awsRegion 值的查询是 \$1.config.awsRegion。 | 
| [start:end] | 筛选数组中的元素，检索从 start 索引开始直到 end 索引的项目（包括首尾）。 | 
| [index1, index2, ... , indexN] | 筛选数组中的元素，仅从指定索引检索项目。 | 
| [?(expr)] | 使用 expr 表达式筛选数组中的元素。该表达式的计算结果必须为布尔值。 | 

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

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

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

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

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

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