本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用 TestState API 測試狀態機器

概觀

您可以使用 Step Functions 主控台、 AWSCommand Line Interface (AWS CLI)或 SDK 中的 TestState 功能來測試支援的狀態。

TestState API 接受 狀態的定義並執行它。它可讓您在不建立狀態機器或更新現有狀態機器的情況下測試狀態。您可以提供：

TestState API 會擔任 角色，該IAM角色必須包含狀態存取之資源的必要IAM許可。當您指定模擬時，指定角色會變成選用角色，可讓您在不設定IAM許可的情況下測試狀態機器邏輯。如需狀態可能需要之許可的相關資訊，請參閱 IAM 使用 TestState API 的許可。

主題

在 TestState API 中使用檢查層級

當您使用 TestState API 測試狀態時，您可以指定要在測試結果中檢視的詳細資訊量。例如，如果您已使用輸入和輸出資料處理篩選條件，例如 InputPath或 ResultPath，您可以檢視中繼和最終資料處理結果。 Step Functions提供下列檢查層級：

所有這些層級也會傳回 status和 nextState 欄位。 會status指出狀態執行的狀態。例如，SUCCEEDED、RETRIABLE、 FAILED和 CAUGHT_ERROR。 nextState指出要轉換為的下一個狀態的名稱。如果您尚未在定義中定義下一個狀態，此欄位會傳回空值。

如需在Step Functions主控台和 中使用這些檢查層級測試狀態的資訊AWS CLI，請參閱 使用 AWSStep Functions 主控台測試狀態和 使用 測試狀態AWS CLI。

INFO inspectionLevel

如果測試成功，此層級會顯示狀態輸出。如果測試失敗，此層級會顯示錯誤輸出。根據預設，如果您未指定關卡， Step Functions會將檢測關卡設定為 INFO。

DEBUG inspectionLevel

如果測試成功，此層級會顯示狀態輸出，以及輸入和輸出資料處理的結果。

如果測試失敗，此層級會顯示錯誤輸出。此層級會顯示截至故障點的中繼資料處理結果。例如，假設您測試了叫用 Lambda函數的任務狀態。假設您已將 InputPath、在 Step Functions 中使用 ResultPath 指定狀態輸出、 和 Parameters使用 OutputPath 篩選狀態輸出篩選條件套用至任務狀態。假設調用失敗。在此情況下，DEBUG關卡會根據篩選條件的應用程式，依下列順序顯示資料處理結果：

此層級中可用的診斷資訊可協助您針對可能已定義的服務整合或輸入和輸出資料處理流程相關問題進行疑難排解。

TRACE inspectionLevel

Step Functions 提供 TRACE 層級來測試 HTTP 任務。此層級會傳回 Step Functions HTTPS API 傳回的 HTTP 請求和回應的相關資訊。回應可能包含資訊，例如標頭和請求內文。此外，您可以在此層級中檢視輸入和輸出資料處理的狀態輸出和結果。

如果測試失敗，此層級會顯示錯誤輸出。

此層級僅適用於 HTTP 任務。如果您將此層級用於其他狀態類型， 會Step Functions擲回錯誤。

當您將檢測層級設定為 TRACE 時，您也可以檢視 EventBridge 連線中包含的秘密。若要這樣做，您必須在 TestState API true 中將 revealSecrets 參數設定為 。此外，您必須確保呼叫 TestState API IAM的使用者具有 states:RevealSecrets動作的許可。如需設定 states:RevealSecrets許可IAM的政策範例，請參閱 IAM 使用 TestState API 的許可。如果沒有此許可， 會Step Functions擲回拒絕存取的錯誤。

如果您將 revealSecrets 參數設定為 false， Step Functions 會省略 HTTP 請求和回應資料中的所有秘密。請注意，在啟用模擬revealSecrets時，您無法使用 。如果您在 TestState API 請求中同時指定 revealSecrets和 模擬， 會Step Functions傳回驗證例外狀況。

IAM 使用 TestState API 的許可

呼叫 TestState API IAM的使用者必須具有執行 states:TestState動作的許可。當您不使用模擬時，IAM使用者也必須具有執行 iam:PassRole動作的許可，才能將執行角色傳遞給 Step Functions。此外，如果您將 revealSecrets 參數設定為 true，IAM使用者必須具有執行 states:RevealSecrets動作的許可。如果沒有此許可， 會Step Functions擲回拒絕存取的錯誤。

請注意，當您在 TestState API 請求中指定模擬時，您可以測試狀態機器邏輯，而無需提供執行角色 （請參閱模擬服務整合下的更多詳細資訊）。當您不使用模擬時，您必須提供執行角色，其中包含狀態存取之資源所需的許可。如需狀態可能需要之許可的相關資訊，請參閱管理執行角色。

使用 AWSStep Functions 主控台測試狀態

您可以在 主控台中測試狀態，並檢查狀態輸出或輸入和輸出資料處理流程。對於 HTTP 任務，您可以測試原始 HTTP 請求和回應。

使用 測試狀態AWS CLI

您可以使用 中的 TestState API 測試狀態AWS CLI。此 API 接受 狀態的定義並執行它。

對於每個狀態，您可以指定要在測試結果中檢視的詳細資訊量。這些詳細資訊提供有關狀態執行的其他資訊，包括其輸入和輸出資料處理結果，以及 HTTP 請求和回應資訊。下列範例示範您可以為 TestState API 指定的不同檢查層級。

本節包含下列範例，說明如何使用 Step Functions中提供的不同檢查層級AWS CLI：

範例 1：使用 INFO inspectionLevel 測試選擇狀態

若要使用 中的 INFO 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}'

此範例使用選擇狀態，根據您提供的數值輸入來判斷狀態的執行路徑。根據預設，INFO如果您未Step Functions設定關卡， inspectionLevel會將 設定為 。

Step Functions 會傳回下列輸出。

{
    "output": "{\"number\": 2}",
    "nextState": "Equals 2",
    "status": "SUCCEEDED"
}

範例 2：使用 DEBUG inspectionLevel 在通過狀態下偵錯輸入和輸出資料處理

若要使用 中的 DEBUG 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

此範例使用 傳遞工作流程狀態 狀態來示範如何使用輸入和輸出資料處理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 和 中的 revealSecrets 參數來測試 HTTP 任務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，並使用 jq公用程式來篩選和列印 TestState API 以人類可讀格式傳回的 HTTP 回應。如需 jq 及其安裝說明的詳細資訊，請參閱 GitHub 上的 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 中處理輸入和輸出。

Amazon States Language (ASL) 中的所有狀態類型 （任務、平行、映射、通過、等待、選擇、成功和失敗） 共用一組常用欄位，用於篩選和操作通過它們的 JSON 資料。這些欄位為：InputPath、Parameters、在 Step Functions 中使用 ResultPath 指定狀態輸出、 ResultSelector和 使用 OutputPath 篩選狀態輸出。每個欄位的支援會因狀態而異。在執行時間， 會以特定順序Step Functions套用每個欄位。下圖顯示將這些欄位套用至任務狀態內資料的順序：

下列清單說明圖表中顯示的輸入和輸出處理欄位的應用程式順序。

這些輸入和輸出處理欄位是選用的。如果您在狀態定義中未使用任何這些欄位，任務將使用原始狀態輸入，並將任務結果傳回為狀態輸出。

使用 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 定義欄位映射至inspectionData物件中的對應欄位：

如需使用 TestState API 偵錯輸入和輸出處理的範例，請參閱以下內容：

針對映射狀態，當 inspectionLevel 設為 時DEBUG，inspectionData物件會包含其他欄位，協助您檢查映射狀態如何擷取和轉換項目。您可以在了解映射狀態檢查資料區段中進一步了解這些欄位。

了解映射狀態檢查資料

當您測試inspectionLevel設定為 的映射狀態時DEBUG，TestState API 回應會在 inspectionData 物件中包含其他欄位，顯示映射狀態如何處理資料：

這些欄位可讓您在部署之前，驗證映射狀態的資料轉換和容錯能力組態是否正常運作。

您可以使用 TestState API 測試和宣告的內容

TestState API 可讓您為狀態機器撰寫完整的單元測試。您可以在狀態機器邏輯的多個層面上宣告，包括下列項目：

錯誤處理：適用哪個 Catch 或 Retry

當您模擬錯誤時，您可以使用 TestState API 來查看啟用的錯誤處理常式。

對於 Catch 區塊，您可以宣告：

對於重試區塊，您可以宣告：

資料轉換：輸入和輸出處理

使用 TestState API，您可以驗證每個處理階段的狀態資料轉換方式。

您可以在以下位置宣告：

映射狀態轉換：It ItemSelector、ItemsPath、It ItemBatcher、ItemsPointer

對於映射狀態，您可以使用 TestState API 來查看如何擷取和轉換項目。

您可以在以下位置宣告：

映射狀態失敗閾值：Test 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 欄位會顯示哪個錯誤處理常式捕捉到錯誤。您可以在以下位置宣告：

模擬服務整合

TestState API 支援模擬服務整合的結果，可讓您在不叫用實際AWS服務的情況下測試狀態機器邏輯。

何時使用模擬

模擬適用於：

當您指定模擬時， roleArn 參數會變成選用，可讓您專注於測試狀態機器定義，而無需處理許可相關問題。

基本模擬語法

若要模擬服務整合結果：

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"}}'

模擬驗證模式

TestState API 會根據AWS服務 API 模型驗證模擬回應，以確保正確性。您可以使用 fieldValidationMode 參數控制驗證行為：

使用驗證模式的範例：

aws stepfunctions test-state \
  --definition '{
    "Type": "Task",
    "Resource": "arn:aws:states:::dynamodb:putItem",
    "Parameters": {...},
    "End": true
  }' \
  --input '{"key": "value"}' \
  --mock '{"fieldValidationMode": "STRICT", "result": "{\"Attributes\": {...}}"}'

測試映射和平行狀態

指定模擬時，TestState API 支援測試映射和平行狀態。這可讓您測試這些流程狀態的輸入和輸出處理。

了解映射狀態測試

當您使用 TestState API 測試映射狀態時，您要測試映射狀態的輸入和輸出處理，而不執行內部的反覆運算。此方法可讓您測試：

您不會測試 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": "..."}'

自動內容人口

在 Map 狀態 （使用 stateName 參數） 內測試狀態而不提供context參數時，TestState 會自動將預設值填入內容物件。這包括映射特定的內容欄位，例如：

測試平行狀態

測試平行狀態時，模擬結果必須是每個分支有一個元素的 JSON 陣列，其順序與定義中分支的順序相同。

測試活動、.sync 和 .waitForTaskToken 狀態

指定模擬時，TestState API 支援測試活動狀態、.sync 服務整合模式和 .waitForTaskToken 模式。如果沒有模擬，透過 TestState API 叫用這些狀態將傳回驗證例外狀況。

透過狀態機器定義反覆運算

您可以向 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
    }
  }
}

此回應指出：

測試捕獲處理常式

當錯誤模擬且符合 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
    }
  }
}

此回應表示：

您也可以透過增加內容物件中的 RetryCount 值，測試所有重試嘗試都用盡時會發生的情況。