本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 TestState API 測試狀態機器
**注意**
從 2025 年 11 月開始，TestState API 包含的增強功能可讓您為 AWSStep Functions 工作流程建置自動化單元測試。這些增強功能可透過 AWS CLI和 SDKs取得。新增了關鍵增強功能：
透過 HTTP 任務狀態叫用模擬AWS服務整合或服務，以測試狀態邏輯，而無需呼叫實際服務
使用模擬回應測試進階狀態，例如映射、平行和活動狀態
控制執行內容以測試特定的重試嘗試、映射反覆運算位置和錯誤案例
## 概觀
您可以使用 Step Functions 主控台、 AWSCommand Line Interface (AWS CLI)或 SDK 中的 TestState 功能來測試[支援的狀態](https://docs.aws.amazon.com/step-functions/latest/dg/test-state-isolation.html#supported-test-states)。
[TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html) API 接受 狀態的定義並執行它。它可讓您在不建立狀態機器或更新現有狀態機器的情況下測試狀態。您可以提供：
+ 單一狀態定義
+ 具有 `stateName` 參數的完整狀態機器定義
`TestState` API 會擔任 角色，該IAM角色必須包含狀態存取之資源的必要IAM許可。當您指定模擬時，指定角色會變成選用角色，可讓您在不設定IAM許可的情況下測試狀態機器邏輯。如需狀態可能需要之許可的相關資訊，請參閱 [IAM 使用 TestState API 的許可](#test-state-permissions)。
**主題**
+ [在 TestState API 中使用檢查層級](#how-test-state-works)
+ [IAM 使用 TestState API 的許可](#test-state-permissions)
+ [使用 AWSStep Functions 主控台測試狀態](#test-state-console)
+ [使用 測試狀態AWS CLI](#test-state-cli)
+ [測試和偵錯輸入和輸出資料流程](#test-state-input-output-dataflow)
+ [您可以使用 TestState API 測試和宣告的內容](#what-you-can-test-assert)
+ [模擬服務整合](#mocking-service-integrations)
+ [測試映射和平行狀態](#testing-map-parallel-states)
+ [測試活動、.sync 和 .waitForTaskToken 狀態](#testing-activity-sync-waitfortasktoken)
+ [透過狀態機器定義反覆運算](#iterating-through-state-machine-definitions)
+ [在 TestState API 中使用內容欄位](#using-context-field)
+ [測試重試和錯誤處理](#testing-retry-error-handling)
## 在 TestState API 中使用檢查層級
當您使用 [TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html) API 測試狀態時，您可以指定要在測試結果中檢視的詳細資訊量。例如，如果您已使用輸入和輸出資料處理篩選條件，例如 [`InputPath`](input-output-inputpath-params.md#input-output-inputpath)或 [`ResultPath`](input-output-resultpath.md)，您可以檢視中繼和最終資料處理結果。 Step Functions提供下列檢查層級：
+ [INFO](#test-state-info-level)
+ [除錯](#test-state-debug-level)
+ [TRACE](#test-state-trace-level)
所有這些層級也會傳回 `status`和 `nextState` 欄位。 會`status`指出狀態執行的狀態。例如，`SUCCEEDED`、`RETRIABLE`、 `FAILED`和 `CAUGHT_ERROR`。 `nextState`指出要轉換為的下一個狀態的名稱。如果您尚未在定義中定義下一個狀態，此欄位會傳回空值。
如需在Step Functions主控台和 中使用這些檢查層級測試狀態的資訊AWS CLI，請參閱 [使用 AWSStep Functions 主控台測試狀態](#test-state-console)和 [使用 測試狀態AWS CLI](#test-state-cli)。
### INFO inspectionLevel
如果測試成功，此層級會顯示狀態輸出。如果測試失敗，此層級會顯示錯誤輸出。根據預設，如果您未指定關卡， Step Functions會將檢測關卡設定為 **INFO**。 ****
#### 具有成功 INFO 層級的測試範例
下圖顯示成功通過狀態的測試。此狀態的**檢查層級**設定為 **INFO**，且狀態的輸出會出現在**輸出**索引標籤中。
#### INFO 層級失敗的測試範例
下圖顯示檢查**層級**設定為 **INFO** 時，任務狀態測試失敗。**輸出**索引標籤會顯示錯誤輸出，其中包含錯誤名稱和該錯誤原因的詳細說明。
### DEBUG inspectionLevel
如果測試成功，此層級會顯示狀態輸出，以及輸入和輸出資料處理的結果。
如果測試失敗，此層級會顯示錯誤輸出。此層級會顯示截至故障點的中繼資料處理結果。例如，假設您測試了叫用 Lambda函數的任務狀態。假設您已將 [InputPath](input-output-inputpath-params.md#input-output-inputpath)、[在 Step Functions 中使用 ResultPath 指定狀態輸出](input-output-resultpath.md)、 和 [Parameters](input-output-inputpath-params.md#input-output-parameters)[使用 OutputPath 篩選狀態輸出](input-output-example.md#input-output-outputpath)篩選條件套用至任務狀態。假設調用失敗。在此情況下，`DEBUG`關卡會根據篩選條件的應用程式，依下列順序顯示資料處理結果：
+ `input` – 原始狀態輸入
+ `afterInputPath` – 之後的輸入會Step Functions套用`InputPath`篩選條件。
+ `afterParameters` – 之後的有效輸入會Step Functions套用`Parameters`篩選條件。
此層級中可用的診斷資訊可協助您針對可能已定義的[服務整合](integrate-services.md)或[輸入和輸出資料處理](#test-state-input-output-dataflow)流程相關問題進行疑難排解。
#### DEBUG 層級成功的測試範例
下圖顯示成功通過狀態的測試。此狀態的**檢查層級**設定為 **DEBUG**。下圖中的**輸入/輸出處理**索引標籤顯示在此狀態提供的輸入[`Parameters`](input-output-inputpath-params.md#input-output-parameters)上應用程式 的結果。
#### DEBUG 層級失敗的測試範例
下圖顯示當**檢測層級**設定為 **DEBUG** 時，任務狀態的測試失敗。下圖中的**輸入/輸出處理**索引標籤會顯示狀態截至故障點的輸入和輸出資料處理結果。
### TRACE inspectionLevel
Step Functions 提供 **TRACE** 層級來測試 [HTTP 任務](call-https-apis.md)。此層級會傳回 Step Functions HTTPS API 傳回的 HTTP 請求和回應的相關資訊。回應可能包含資訊，例如標頭和請求內文。此外，您可以在此層級中檢視輸入和輸出資料處理的狀態輸出和結果。
如果測試失敗，此層級會顯示錯誤輸出。
此層級僅適用於 HTTP 任務。如果您將此層級用於其他狀態類型， 會Step Functions擲回錯誤。
當您將**檢測層級**設定為 **TRACE** 時，您也可以檢視 [EventBridge 連線](call-https-apis.md#http-task-authentication)中包含的秘密。若要這樣做，您必須在 [TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html) API `true` 中將 `revealSecrets` 參數設定為 。此外，您必須確保呼叫 TestState API IAM的使用者具有 `states:RevealSecrets`動作的許可。如需設定 `states:RevealSecrets`許可IAM的政策範例，請參閱 [IAM 使用 TestState API 的許可](#test-state-permissions)。如果沒有此許可， 會Step Functions擲回拒絕存取的錯誤。
如果您將 `revealSecrets` 參數設定為 `false`， Step Functions 會省略 HTTP 請求和回應資料中的所有秘密。請注意，在啟用模擬`revealSecrets`時，您無法使用 。如果您在 TestState API 請求中同時指定 `revealSecrets`和 模擬， 會Step Functions傳回驗證例外狀況。
#### TRACE 層級成功的測試範例
下圖顯示成功 HTTP 任務的測試。此狀態的**檢查層級**設定為 **TRACE**。下圖中的 **HTTP 請求和回應**索引標籤會顯示 HTTPS API 呼叫的結果。
## IAM 使用 TestState API 的許可
呼叫 `TestState` API IAM的使用者必須具有執行 `states:TestState`動作的許可。當您不使用模擬時，IAM使用者也必須具有執行 `iam:PassRole`動作的許可，才能將執行角色傳遞給 Step Functions。此外，如果您將 `revealSecrets` 參數設定為 `true`，IAM使用者必須具有執行 `states:RevealSecrets`動作的許可。如果沒有此許可， 會Step Functions擲回拒絕存取的錯誤。
請注意，當您在 TestState API 請求中指定模擬時，您可以測試狀態機器邏輯，而無需提供執行角色 （請參閱[模擬服務整合](#mocking-service-integrations)下的更多詳細資訊）。當您不使用模擬時，您必須提供執行角色，其中包含狀態存取之資源所需的許可。如需狀態可能需要之許可的相關資訊，請參閱[管理執行角色](manage-state-machine-permissions.md)。
## 使用 AWSStep Functions 主控台測試狀態
您可以在 主控台中測試狀態，並檢查狀態輸出或輸入和輸出資料處理流程。對於 [HTTP 任務](call-https-apis.md)，您可以測試原始 HTTP 請求和回應。
**注意**
主控台 TestState 功能尚不支援本文件所述的一些增強功能，例如模擬服務整合、測試映射和平行狀態，或活動、.sync 和 .waitForTaskToken 模式。這些功能目前只能透過使用 AWS CLI或 SDK 的 TestState API 使用。
**測試狀態**
1. 開啟 [Step Functions 主控台](https://console.aws.amazon.com/states/home?region=us-east-1#/)。
1. 選擇**建立狀態機器**以開始建立狀態機器，或選擇現有的狀態機器。
1. 在 Workflow Studio [設計模式](workflow-studio.md#wfs-interface-design-mode)的 中，選擇您要測試的狀態。
1. 在 Workflow Studio [Inspector 面板](workflow-studio.md#workflow-studio-components-formdefinition) 的 中選擇**測試狀態**。
1. 在**測試狀態**對話方塊中，執行下列動作：
1. 針對**執行角色**，選擇要測試狀態的執行角色。請確定您擁有要測試之狀態的必要[IAM許可](#test-state-permissions)。
1. （選用） 提供您選擇的測試狀態所需的任何 JSON 輸入。
1. 針對**檢測層級**，根據您要檢視的值選取下列其中一個選項：
+ [INFO](#test-state-info-level) – 如果測試成功，在輸出索引標籤中顯示狀態**輸出**。如果測試失敗，**INFO** 會顯示錯誤輸出，其中包含錯誤名稱和該錯誤原因的詳細說明。根據預設，如果您未選取關卡， Step Functions會將檢測關卡設定為 **INFO**。 ****
+ [DEBUG](#test-state-debug-level) – 如果測試成功，會顯示狀態輸出和輸入和輸出資料處理的結果。如果測試失敗，**DEBUG** 會顯示錯誤輸出，其中包含錯誤名稱和該錯誤原因的詳細說明。
+ [TRACE](#test-state-trace-level) – 顯示原始 HTTP 請求和回應，對於驗證標頭、查詢參數和其他 API 特定詳細資訊很有用。此選項僅適用於 [HTTP 任務](call-https-apis.md)。
或者，您可以選擇**顯示秘密**。結合 **TRACE**，此設定可讓您查看EventBridge連線插入的敏感資料，例如 API 金鑰。您用來存取主控台IAM的使用者身分必須具有執行 `states:RevealSecrets`動作的許可。如果沒有此許可， 會在您開始測試時Step Functions擲出存取遭拒錯誤。如需IAM設定 `states:RevealSecrets`許可的政策範例，請參閱 [IAM 使用 TestState API 的許可](#test-state-permissions)。
1. 選擇**開始測試**。
## 使用 測試狀態AWS CLI
您可以使用 中的 [TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html) API 測試狀態AWS CLI。此 API 接受 狀態的定義並執行它。
對於每個狀態，您可以指定要在測試結果中檢視的詳細資訊量。這些詳細資訊提供有關狀態執行的其他資訊，包括其輸入和輸出資料處理結果，以及 HTTP 請求和回應資訊。下列範例示範您可以為 TestState API 指定的不同檢查層級。
本節包含下列範例，說明如何使用 Step Functions中提供的不同檢查層級AWS CLI：
+ [使用 INFO inspectionLevel](#test-info-level-cli)
+ [使用 DEBUG inspectionLevel](#test-debug-level-cli)
+ [使用 TRACE inspectionLevel](#test-trace-level-cli)
+ [在 中使用 jq 公用程式AWS CLI來篩選和列印 TestState API 傳回的 HTTP 回應](#cli-readable-output)
### 範例 1：使用 INFO inspectionLevel 測試選擇狀態
若要使用 中的 `INFO` [inspectionLevel](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html#StepFunctions-TestState-request-inspectionLevel) 測試狀態AWS CLI，請執行 `test-state`命令，如下列範例所示。
```
aws stepfunctions test-state \
--definition '{"Type": "Choice", "Choices": [{"Variable": "$.number", "NumericEquals": 1, "Next": "Equals 1"}, {"Variable": "$.number", "NumericEquals": 2, "Next": "Equals 2"}], "Default": "No Match"}' \
--role-arn arn:aws:iam::{{account-id}}:role/{{myRole}} \
--input '{"number": 2}'
```
此範例使用[選擇](state-choice.md)狀態，根據您提供的數值輸入來判斷狀態的執行路徑。根據預設，`INFO`如果您未Step Functions設定關卡， `inspectionLevel`會將 設定為 。
Step Functions 會傳回下列輸出。
```
{
"output": "{\"number\": 2}",
"nextState": "Equals 2",
"status": "SUCCEEDED"
}
```
### 範例 2：使用 DEBUG inspectionLevel 在通過狀態下偵錯輸入和輸出資料處理
若要使用 中的 `DEBUG` [inspectionLevel](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html#StepFunctions-TestState-request-inspectionLevel) 測試狀態AWS CLI，請執行 `test-state`命令，如下列範例所示。
```
aws stepfunctions test-state \
--definition '{"Type": "Pass", "InputPath": "$.payload", "Parameters": {"data": 1}, "ResultPath": "$.result", "OutputPath": "$.result.data", "Next": "Another State"}' \
--role-arn arn:aws:iam::{{account-id}}:role/{{myRole}} \
--input '{"payload": {"foo": "bar"}}' \
--inspection-level DEBUG
```
此範例使用 [傳遞工作流程狀態](state-pass.md) 狀態來示範如何使用輸入和輸出資料處理Step Functions篩選條件來篩選和操作輸入 JSON 資料。此範例使用這些篩選條件：`InputPath`、`在 Step Functions 中使用 ResultPath 指定狀態輸出`、 `Parameters`和 `使用 OutputPath 篩選狀態輸出`。
Step Functions 會傳回下列輸出。
```
{
"output": "1",
"inspectionData": {
"input": "{\"payload\": {\"foo\": \"bar\"}}",
"afterInputPath": "{\"foo\":\"bar\"}",
"afterParameters": "{\"data\":1}",
"afterResultSelector": "{\"data\":1}",
"afterResultPath": "{\"payload\":{\"foo\":\"bar\"},\"result\":{\"data\":1}}"
},
"nextState": "Another State",
"status": "SUCCEEDED"
}
```
### 範例 3：使用 TRACE inspectionLevel 和 revealSecrets 來檢查傳送至 HTTPS API 的 HTTP 請求
若要使用 `TRACE` [inspectionLevel](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html#StepFunctions-TestState-request-inspectionLevel) 和 中的 [revealSecrets](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html#StepFunctions-TestState-request-revealSecrets) 參數來測試 [HTTP 任務](call-https-apis.md)AWS CLI，請執行 `test-state`命令，如下列範例所示。
```
aws stepfunctions test-state \
--definition '{"Type": "Task", "Resource": "arn:aws:states:::http:invoke", "Parameters": {"Method": "GET", "Authentication": {"ConnectionArn": "arn:aws:events:{{region}}:{{account-id}}:connection/{{MyConnection/0000000-0000-0000-0000-000000000000"}}}, "ApiEndpoint": "https://httpbin.org/get", "Headers": {"definitionHeader": "h1"}, "RequestBody": {"message": "Hello from Step Functions!"}, "QueryParameters": {"queryParam": "q1"}}, "End": true}' \
--role-arn arn:aws:iam::{{account-id}}:role/{{myRole}} \
--inspection-level TRACE \
--reveal-secrets
```
此範例會測試 HTTP 任務是否呼叫指定的 HTTPS API `https://httpbin.org/`。它也會顯示 API 呼叫的 HTTP 請求和回應資料。
Step Functions 會傳回類似目前文件中原始範例的輸出。
### 範例 4：使用 jq 公用程式來篩選和列印 TestState API 傳回的回應
TestState API 會在回應中將 JSON 資料傳回為逸出字串。下列AWS CLI範例延伸[範例 3](#test-trace-level-cli)，並使用 `jq`公用程式來篩選和列印 TestState API 以人類可讀格式傳回的 HTTP 回應。如需 `jq` 及其安裝說明的詳細資訊，請參閱 *GitHub* 上的 [jq](https://stedolan.github.io/jq/)。
```
aws stepfunctions test-state \
--definition '{"Type": "Task", "Resource": "arn:aws:states:::http:invoke", "Parameters": {"Method": "GET", "Authentication": {"ConnectionArn": "arn:aws:events:{{region}}:{{account-id}}:connection/{{MyConnection/0000000-0000-0000-0000-000000000000"}}}, "ApiEndpoint": "https://httpbin.org/get", "Headers": {"definitionHeader": "h1"}, "RequestBody": {"message": "Hello from Step Functions!"}, "QueryParameters": {"queryParam": "q1"}}, "End": true}' \
--role-arn arn:aws:iam::{{account-id}}:role/{{myRole}} \
--inspection-level TRACE \
--reveal-secrets \
| jq '.inspectionData.response.body | fromjson'
```
下列範例顯示以人類可讀格式傳回的輸出。
```
{
"args": {
{{"QueryParam1": "QueryParamValue1",
"queryParam": "q1"}}
},
"headers": {
"Authorization": "Basic XXXXXXXX",
"Content-Type": "application/json; charset=UTF-8",
"Customheader1": "CustomHeaderValue1",
"Definitionheader": "h1",
"Host": "httpbin.org",
"Range": "bytes=0-262144",
"Transfer-Encoding": "chunked",
"User-Agent": "Amazon|StepFunctions|HttpInvoke|{{region}}",
"X-Amzn-Trace-Id": "Root=1-0000000-0000-0000-0000-000000000000"
},
"origin": "{{12.34.567.891}}",
"url": "{{https://httpbin.org/get?queryParam=q1&QueryParam1=QueryParamValue1}}"
}
```
## 測試和偵錯輸入和輸出資料流程
`TestState` API 有助於測試和偵錯流經工作流程的資料。本節提供一些關鍵概念，並說明如何將 TestState 用於此目的。
### 重要概念
在 中Step Functions，篩選和操作通過狀態機器中狀態的 JSON 資料的程序稱為*輸入和輸出處理*。如需其運作方式的相關資訊，請參閱[在 Step Functions 中處理輸入和輸出](concepts-input-output-filtering.md)。
[Amazon States Language](concepts-amazon-states-language.md) (ASL) 中的所有[狀態](workflow-states.md)類型 （任務、平行、映射、通過、等待、選擇、成功和失敗） 共用一組常用欄位，用於篩選和操作通過它們的 JSON 資料。這些欄位為：[InputPath](input-output-inputpath-params.md#input-output-inputpath)、[Parameters](input-output-inputpath-params.md#input-output-parameters)、[在 Step Functions 中使用 ResultPath 指定狀態輸出](input-output-resultpath.md)、 [ResultSelector](input-output-inputpath-params.md#input-output-resultselector)和 [使用 OutputPath 篩選狀態輸出](input-output-example.md#input-output-outputpath)。每個欄位的支援[會因狀態而異](https://states-language.net/spec.html#state-type-table)。在執行時間， 會以特定順序Step Functions套用每個欄位。下圖顯示將這些欄位套用至任務狀態內資料的順序：
下列清單說明圖表中顯示的輸入和輸出處理欄位的應用程式順序。
1. *狀態輸入*是從先前狀態傳遞至目前狀態的 JSON 資料。
1. [InputPath](input-output-inputpath-params.md#input-output-inputpath) 會篩選原始狀態輸入的一部分。
1. [Parameters](input-output-inputpath-params.md#input-output-parameters) 設定要傳遞至[任務](state-task.md)的一組值。
1. 任務會執行工作並傳回結果。
1. [ResultSelector](input-output-inputpath-params.md#input-output-resultselector) 會選取要從任務結果保留的一組值。
1. [在 Step Functions 中使用 ResultPath 指定狀態輸出](input-output-resultpath.md) 會將結果與原始狀態輸入合併，或使用其取代結果。
1. [使用 OutputPath 篩選狀態輸出](input-output-example.md#input-output-outputpath) 會篩選輸出的一部分，以傳遞至下一個狀態。
1. *狀態輸出*是從目前狀態傳遞至下一個狀態的 JSON 資料。
這些輸入和輸出處理欄位是選用的。如果您在狀態定義中未使用任何這些欄位，任務將使用原始狀態輸入，並將任務結果傳回為狀態輸出。
### 使用 TestState 檢查輸入和輸出處理
當您呼叫 `TestState` API 並將 `inspectionLevel` 參數設定為 時`DEBUG`，API 回應會包含名為 的物件`inspectionData`。此物件包含欄位，可協助您檢查資料在執行時在 狀態內如何篩選或操作。下列範例顯示任務狀態的 `inspectionData` 物件。
```
"inspectionData": {
"input": string,
"afterInputPath": string,
"afterParameters": string,
"result": string,
"afterResultSelector": string,
"afterResultPath": string,
"output": string
}
```
在此範例中，包含 `after` 字首的每個欄位都會顯示套用特定欄位之後的資料。例如， `afterInputPath`顯示套用 `InputPath` 欄位以篩選原始狀態輸入的效果。下圖會將每個 [ASL 定義](concepts-amazon-states-language.md)欄位映射至`inspectionData`物件中的對應欄位：
如需使用 TestState API 偵錯輸入和輸出處理的範例，請參閱以下內容：
+ [在 Step Functions主控台中使用 DEBUG 檢查層級測試狀態](#test-state-debug-level)
+ [中的使用 DEBUG 檢查層級測試狀態AWS CLI](#test-debug-level-cli)
針對映射狀態，當 `inspectionLevel` 設為 時`DEBUG`，`inspectionData`物件會包含其他欄位，協助您檢查映射狀態如何擷取和轉換項目。您可以在了解[映射狀態檢查資料](#understanding-map-inspection-data)區段中進一步了解這些欄位。
### 了解映射狀態檢查資料
當您測試`inspectionLevel`設定為 的映射狀態時`DEBUG`，TestState API 回應會在 `inspectionData` 物件中包含其他欄位，顯示映射狀態如何處理資料：
**注意**
`afterItemsPath` 只有在使用 JSONPath 做為查詢語言時才會填入 。
+ `afterItemsPath` （字串） – 套用 ItemsPath 篩選條件之後的有效輸入。這會顯示從您的輸入擷取的項目陣列。
+ `afterItemsPointer` （字串） – 套用 ItemsPointer 篩選條件之後的有效輸入。這僅適用於 JSON 輸入 （不適用於 JSONata)。
+ `afterItemSelector` （字串陣列） – 套用 ItemSelector 轉換後包含輸入值的陣列。陣列中的每個元素代表一個轉換的項目。此欄位僅在測試映射狀態時存在。
+ `afterItemBatcher` （字串陣列） – 套用 ItemBatcher 分組後包含輸入值的陣列。這會顯示如何將項目分組為批次。此欄位僅在測試映射狀態時存在。
+ `toleratedFailureCount` （數目） – 對應狀態的容錯閾值，表示為對應狀態反覆運算的計數。此值衍生自 ToleratedFailureCount 中指定的值，或 ToleratedFailureCountPath 在執行時間評估的值。
+ `toleratedFailurePercentage` （數目） – Map 狀態的容錯閾值，以 Map 狀態反覆運算的百分比表示。此值衍生自 ToleratedFailurePercentage 中指定的值，或在執行時間從 ToleratedFailurePercentagePath 評估的值。
+ `maxConcurrency` （數字） – Map 狀態的最大並行設定。
這些欄位可讓您在部署之前，驗證映射狀態的資料轉換和容錯能力組態是否正常運作。
## 您可以使用 TestState API 測試和宣告的內容
TestState API 可讓您為狀態機器撰寫完整的單元測試。您可以在狀態機器邏輯的多個層面上宣告，包括下列項目：
+ [錯誤處理：適用哪個 Catch 或 Retry](#error-handling-catch-retry)
+ [資料轉換：輸入和輸出處理](#data-transformations-assert)
+ [映射狀態轉換：It ItemSelector、ItemsPath、It ItemBatcher、ItemsPointer](#map-state-transformations-assert)
+ [映射狀態失敗閾值：Test States.ExceedToleratedFailureThreshold](#map-failure-thresholds-assert)
+ [Map 和 Parallel 狀態中的錯誤傳播](#error-propagation-assert)
### 錯誤處理：適用哪個 Catch 或 Retry
當您模擬錯誤時，您可以使用 TestState API 來查看啟用的錯誤處理常式。
對於 Catch 區塊，您可以宣告：
+ 哪個 Catch 處理常式會擷取錯誤 （透過回應`catchIndex`中的 )
+ 下一個狀態將是什麼 （透過回應`nextState`中的 )
+ 哪些資料流向錯誤處理常式 （透過回應`output`中考慮 ResultPath)
對於重試區塊，您可以宣告：
+ 適用的重試 （透過回應`retryIndex`中的 )
+ 退避持續時間為何 （透過回應`retryBackoffIntervalSeconds`)
+ 重試是否用盡，並攔截錯誤
### 資料轉換：輸入和輸出處理
使用 TestState API，您可以驗證每個處理階段的狀態資料轉換方式。
您可以在以下位置宣告：
+ InputPath 篩選條件後的輸入 (`afterInputPath`)
+ 參數/參數轉換之後的資料 (`afterParameters` 或 `afterArguments`)
+ ResultSelector (`afterResultSelector`) 之後的結果
+ ResultPath 後的輸出 (`afterResultPath`)
+ OutputPath 之後的最終輸出 (`output`)
### 映射狀態轉換：It ItemSelector、ItemsPath、It ItemBatcher、ItemsPointer
對於映射狀態，您可以使用 TestState API 來查看如何擷取和轉換項目。
您可以在以下位置宣告：
+ ItemsPath 篩選條件之後的項目 (`afterItemsPath`)
+ ItemsPointer 篩選條件之後的項目 (`afterItemsPointer`)
+ ItemSelector 轉換後的項目 (`afterItemSelector`)
+ ItemBatcher 分組之後的項目 (`afterItemBatcher`)
### 映射狀態失敗閾值：Test States.ExceedToleratedFailureThreshold
測試特定數量的失敗反覆運算是否觸發可容忍的失敗閾值。
您可以在以下位置宣告：
+ 映射狀態是否因 States.ExceedToleratedFailureThreshold 失敗
### Map 和 Parallel 狀態中的錯誤傳播
在映射或平行狀態下測試狀態時，錯誤會傳播到父系狀態錯誤處理常式，就像在實際執行中一樣。
#### 使用 errorCausedByState 指定錯誤來源
模擬映射或平行狀態的錯誤時，您必須使用 `stateConfiguration.errorCausedByState` 參數指定導致錯誤的子狀態。這在測試萬用字元錯誤時特別重要，例如 `States.TaskFailed`。 `States.TaskFailed` 是一種萬用字元錯誤，適用於任何任務狀態失敗。若要測試您的映射或平行狀態如何處理此錯誤，您需要識別捨棄該錯誤的特定子狀態。請參閱以下範例：
```
aws stepfunctions test-state \
--definition '{...Map or Parallel state definition...}' \
--input '[...]' \
--state-configuration '{"errorCausedByState": "ProcessItem"}' \
--mock '{"errorOutput": {"error": "States.TaskFailed", "cause": "Task execution failed"}}'
```
在此範例中， `errorCausedByState`會告知 TestState 映射/平行工作流程中的「ProcessItem」狀態已擲回錯誤。父項映射/平行狀態的擷取或重試處理常式會像實際執行期間一樣處理錯誤。回應中的 `nextState` 欄位會顯示哪個錯誤處理常式捕捉到錯誤。您可以在以下位置宣告：
+ 父 Catch 處理常式是否攔截子狀態錯誤
+ 子狀態錯誤是否觸發父重試政策
+ 錯誤傳播後的下一個狀態為何
## 模擬服務整合
TestState API 支援模擬服務整合的結果，可讓您在不叫用實際AWS服務的情況下測試狀態機器邏輯。
### 何時使用模擬
模擬適用於：
+ 隔離單位測試狀態機器定義
+ 測試錯誤處理和重試邏輯
+ 驗證輸入和輸出資料轉換
+ 模擬各種服務回應和錯誤條件
+ 在未設定IAM許可的情況下進行測試
當您指定模擬時， `roleArn` 參數會變成選用，可讓您專注於測試狀態機器定義，而無需處理許可相關問題。
**注意**
如果您需要測試下列狀態類型或服務整合模式 - 映射、平行、活動、.sync 服務整合和 waitForTaskToken 服務整合，則需要模擬。
### 基本模擬語法
若要模擬服務整合結果：
```
aws stepfunctions test-state \
--definition '{
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Arguments": {
"FunctionName": "MyFunction",
"Payload.$": "$"
},
"End": true
}' \
--input '{"key": "value"}' \
--mock '{"result": "{\"Payload\": {\"statusCode\": 200, \"body\": \"Success\"}}"}'
```
若要模擬錯誤：
```
aws stepfunctions test-state \
--definition '{
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Arguments": {...},
"End": true
}' \
--input '{"key": "value"}' \
--mock '{"errorOutput": {"error": "Lambda.ServiceException", "cause": "Service unavailable"}}'
```
**注意**
您無法在相同的 API 呼叫`mock.errorOutput`中同時提供 `mock.result`和 。這會導致驗證例外狀況。
### 模擬驗證模式
TestState API 會根據AWS服務 API 模型驗證模擬回應，以確保正確性。您可以使用 `fieldValidationMode` 參數控制驗證行為：
+ **STRICT （預設）** – 從 AWSAPI 模型強制執行欄位命名、大小、形狀和資料類型限制。所有必要欄位必須具有正確的類型。此模式有助於確保您的模擬準確代表實際的服務回應。
+ **PRESENT** – 僅驗證模擬中存在的欄位。忽略不明欄位。當您想要彈性，但仍想要驗證已知欄位時，此模式很有用。
+ **NONE** – 完全略過驗證。請謹慎使用，因為這可能會導致不正確的測試假設和行為與實際執行不同。
**注意**
驗證只會在AWS服務 API 模型中定義的欄位上執行。無論驗證模式為何，驗證期間都會忽略 API 模型中未指定的任何欄位。例如，如果針對沒有定義「必要」欄位的 API 使用 STRICT 模式，則空模擬回應將通過驗證。
使用驗證模式的範例：
```
aws stepfunctions test-state \
--definition '{
"Type": "Task",
"Resource": "arn:aws:states:::dynamodb:putItem",
"Parameters": {...},
"End": true
}' \
--input '{"key": "value"}' \
--mock '{"fieldValidationMode": "STRICT", "result": "{\"Attributes\": {...}}"}'
```
**重要**
[HTTP 任務](call-https-apis.md)、API Gateway、EKS 呼叫和 EKS RunJob 整合不支援模擬驗證。
## 測試映射和平行狀態
指定模擬時，TestState API 支援測試映射和平行狀態。這可讓您測試這些流程狀態的輸入和輸出處理。
### 了解映射狀態測試
當您使用 TestState API 測試映射狀態時，您要測試映射狀態的輸入和輸出處理，而不執行內部的反覆運算。此方法可讓您測試：
+ 從輸入擷取 ItemsPath 或 ItemsPointer
+ 套用至每個項目的 ItemSelector 轉換
+ ItemBatcher 分組 （如果指定）
+ Map 狀態的輸出處理 (ResultPath、OutputPath)
+ 容許的失敗閾值
您不會測試 ItemProcessor 內發生的情況 （處理每個項目的狀態）。
### 測試映射狀態
測試映射狀態時，模擬結果必須代表整個映射狀態的輸出。模擬結果必須是有效的 JSON 陣列或 JSON 物件，視您的映射狀態組態而定。請參閱以下範例：
```
aws stepfunctions test-state \
--definition '{
"Type": "Map",
"ItemsPath": "$.items",
"ItemSelector": {
"value.$": "$$.Map.Item.Value",
"index.$": "$$.Map.Item.Index"
},
"ItemProcessor": {
"ProcessorConfig": {"Mode": "INLINE"},
"StartAt": "ProcessItem",
"States": {
"ProcessItem": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"End": true
}
}
},
"End": true
}' \
--input '{"items": [1, 2, 3, 4, 5]}' \
--mock '{"result": "[10, 20, 30, 40, 50]"}' \
--inspection-level DEBUG
```
### 測試分散式地圖狀態
分散式地圖狀態的測試方式與內嵌地圖狀態類似。當您的映射使用 ItemReader 從 S3 讀取時，請直接在輸入中提供資料 （如同已從 S3 讀取一樣）。例如：
```
aws stepfunctions test-state \
--definition '{
"Type": "Map",
"ItemReader": {
"Resource": "arn:aws:states:::s3:getObject",
"Parameters": {
"Bucket": "my-bucket",
"Key": "orders.json"
}
},
"ItemsPath": "$.orders",
"ItemProcessor": {
"ProcessorConfig": {"Mode": "DISTRIBUTED"},
...
},
"ToleratedFailureCount": 5,
"End": true
}' \
--input '{
"orders": [
{"orderId": "123"},
{"orderId": "456"},
{"orderId": "789"}
]
}' \
--mock '{"result": "..."}'
```
**注意**
測試分散式映射狀態 （模式設定為 DISTRIBUTED) 時，您也可以在 mapIterationFailureCount 上宣告。此欄位的值不能超過輸入中的項目數量，或等於在映射中測試狀態時的項目數量。
### 自動內容人口
在 Map 狀態 （使用 `stateName` 參數） 內測試狀態而不提供`context`參數時，TestState 會自動將預設值填入內容物件。這包括映射特定的內容欄位，例如：
+ `$$.Map.Item.Index` = `0`（第一次反覆運算）
+ `$$.Map.Item.Value` = 您的輸入值
+ `$$.Map.Item.Key` （適用於具有特定 ItemReader 組態的分散式地圖）
+ `$$.Map.Item.Source` （對於分散式地圖，指出項目的來源）
### 測試平行狀態
測試平行狀態時，模擬結果必須是每個分支有一個元素的 JSON 陣列，其順序與定義中分支的順序相同。
## 測試活動、.sync 和 .waitForTaskToken 狀態
指定模擬時，TestState API 支援測試活動狀態、.sync 服務整合模式和 .waitForTaskToken 模式。如果沒有模擬，透過 TestState API 叫用這些狀態將傳回驗證例外狀況。
**注意**
對於使用 TestState API 測試 .sync 整合，模擬回應會根據輪詢 API 的結構描述進行驗證。例如，測試 時`startExecution.sync:2`，您的模擬必須符合`DescribeExecution`回應結構描述 (Step Functions輪詢狀態），而非`StartExecution`回應。
## 透過狀態機器定義反覆運算
您可以向 TestState API 提供完整的狀態機器定義，並使用 `stateName` 參數指定要測試的狀態。這可讓您在完整狀態機器的內容中測試該特定狀態。您也可以使用輸出 和 nextState 從一個測試鏈結測試，做為下一個測試的輸入。這可讓您在狀態機器內測試部分或完整的執行路徑。
## 在 TestState API 中使用內容欄位
`context` 參數可讓您為內容物件提供通常在執行期間填入的值。這適用於測試參考執行 ID、狀態名稱或輸入時間等內容值的狀態。以下範例示範如何在 TestState API 呼叫中使用內容物件：
```
aws stepfunctions test-state \
--definition '{
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Arguments": {
"FunctionName": "MyFunction",
"Payload": {
"executionId.$": "$$.Execution.Id",
"stateName.$": "$$.State.Name",
"enteredTime.$": "$$.State.EnteredTime"
}
},
"End": true
}' \
--input '{"data": "value"}' \
--context '{
"Execution": {
"Id": "arn:aws:states:us-east-1:123456789012:execution:MyStateMachine:test-exec-123",
"Name": "test-exec-123",
"StartTime": "2024-01-01T10:00:00.000Z"
},
"State": {
"Name": "ProcessData",
"EnteredTime": "2024-01-01T10:00:05.000Z"
}
}' \
--mock '{"result": "{\"status\": \"success\"}"}'
```
## 測試重試和錯誤處理
TestState API 可讓您透過指定重試嘗試和模擬錯誤來模擬重試案例和測試錯誤處理邏輯。
### 模擬重試嘗試
```
aws stepfunctions test-state \
--definition '{
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Arguments": {...},
"Retry": [{
"ErrorEquals": ["Lambda.ServiceException"],
"IntervalSeconds": 2,
"MaxAttempts": 3,
"BackoffRate": 2.0
}],
"End": true
}' \
--input '{"data": "value"}' \
--state-configuration '{"retrierRetryCount": 1}' \
--mock '{"errorOutput": {"error": "Lambda.ServiceException", "cause": "Service error"}}' \
--inspection-level DEBUG
```
回應包含 inspectionData 中的錯誤詳細資訊：
```
{
"status": "RETRIABLE",
"inspectionData": {
"errorDetails": {
"retryBackoffIntervalSeconds": 4,
"retryIndex": 0
}
}
}
```
此回應指出：
+ 錯誤可重試 （狀態：可重試）
+ 退避持續時間為 4 秒 (2 × 2.0^1)
+ 套用第一個重試 （索引 0)
### 測試捕獲處理常式
當錯誤模擬且符合 Catch 處理常式時，TestState API 回應中的 `nextState` 欄位會指出將處理錯誤的狀態。在下列範例中：
對於以下指定的 TestState API 請求，
```
aws stepfunctions test-state \
--definition '{
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Arguments": {...},
"Catch": [{
"ErrorEquals": ["Lambda.TooManyRequestsException"],
"ResultPath": "$.error",
"Next": "HandleThrottling"
}],
"Next": "Success"
}' \
--input '{"data": "value"}' \
--mock '{"errorOutput": {"error": "Lambda.TooManyRequestsException", "cause": "Rate exceeded"}}' \
--inspection-level DEBUG
```
預期的 API 回應應該是：
```
{
"status": "CAUGHT_ERROR",
"nextState": "HandleThrottling",
"error": "Lambda.TooManyRequestsException",
"cause": "Rate exceeded",
"output": "{\"data\": \"value\", \"error\": {\"Error\": \"Lambda.TooManyRequestsException\", \"Cause\": \"Rate exceeded\"}}",
"inspectionData": {
"errorDetails": {
"catchIndex": 0
}
}
}
```
此回應表示：
+ 攔截到錯誤 （狀態：CAUGHT\_ERROR)
+ 下一個狀態是 HandleThrottling
+ 錯誤資訊會透過 ResultPath 新增至輸出
+ 第一個 Catch 處理常式 （索引 0) 攔截到錯誤
您也可以透過增加內容物件中的 RetryCount 值，測試所有重試嘗試都用盡時會發生的情況。