Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # Test di macchine a stati con TestState API **Nota** A partire da novembre 2025, l' TestState API include miglioramenti che consentono di creare unit test automatici per i flussi di lavoro AWS Step Functions. Questi miglioramenti sono disponibili tramite e. AWS CLI SDKs Miglioramenti chiave aggiunti: Integrazioni o AWS servizi fittizi richiamati tramite HTTP Task state per testare la logica dello stato senza chiamare il servizio effettivo Testa stati avanzati come gli stati Map, Parallel e Activity con risposte simulate Controlla il contesto di esecuzione per testare tentativi di ripetizione specifici, posizioni di iterazione della mappa e scenari di errore ## Panoramica di Puoi testare uno [stato supportato](https://docs.aws.amazon.com/step-functions/latest/dg/test-state-isolation.html#supported-test-states) utilizzando la TestState funzionalità nella Step Functions console o nell'AWSCommand Line Interface (AWS CLI)SDK. L'[TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html)API accetta la definizione di uno stato e la esegue. Consente di testare uno stato senza creare una macchina a stati o aggiornare una macchina a stati esistente. È possibile fornire: + Una singola definizione di stato + Una definizione completa di macchina a stati con `stateName` parametri L'`TestState`API assume un IAM ruolo che deve contenere le IAM autorizzazioni necessarie per le risorse a cui accede lo stato. Quando si specifica un mock, la specificazione del ruolo diventa facoltativa e consente di testare la logica della macchina a stati senza configurare le autorizzazioni. IAM Per informazioni sulle autorizzazioni di cui uno stato potrebbe aver bisogno, consulta. [IAMautorizzazioni per l'utilizzo dell'API TestState](#test-state-permissions) **Argomenti** + [Utilizzo dei livelli di ispezione nell'API TestState](#how-test-state-works) + [IAMautorizzazioni per l'utilizzo dell'API TestState](#test-state-permissions) + [Test di uno stato utilizzando la console AWS Step Functions](#test-state-console) + [Testare uno stato utilizzando AWS CLI](#test-state-cli) + [Test e debug del flusso di dati di input e output](#test-state-input-output-dataflow) + [Cosa puoi testare e affermare con l'API TestState](#what-you-can-test-assert) + [Integrazioni di servizi di simulazione](#mocking-service-integrations) + [Test degli stati di Map e Parallel](#testing-map-parallel-states) + [Testing Activity, .sync e. waitForTaskStati dei token](#testing-activity-sync-waitfortasktoken) + [Iterazione attraverso le definizioni delle macchine a stati](#iterating-through-state-machine-definitions) + [Utilizzo del campo contestuale nell' TestState API](#using-context-field) + [Test, ripetizione dei tentativi e della gestione degli errori](#testing-retry-error-handling) ## Utilizzo dei livelli di ispezione nell'API TestState Quando testate uno stato utilizzando l'[TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html)API, potete specificare la quantità di dettagli che desiderate visualizzare nei risultati del test. Ad esempio, se hai utilizzato filtri di elaborazione dei dati di input e output come [`InputPath`](input-output-inputpath-params.md#input-output-inputpath)o [`ResultPath`](input-output-resultpath.md), puoi visualizzare i risultati intermedi e finali dell'elaborazione dei dati. Step Functionsfornisce i seguenti livelli di ispezione: + [INFORMAZIONI](#test-state-info-level) + [ESEGUIRE IL DEBUG](#test-state-debug-level) + [TRACCIA](#test-state-trace-level) Tutti questi livelli restituiscono anche `nextState` i campi `status` and. `status`indica lo stato dell'esecuzione dello stato. Ad esempio, `SUCCEEDED``FAILED`,`RETRIABLE`, e`CAUGHT_ERROR`. `nextState`indica il nome dello stato successivo verso cui passare. Se non hai definito uno stato successivo nella definizione, questo campo restituisce un valore vuoto. Per informazioni sul test di uno stato utilizzando questi livelli di ispezione nella Step Functions console eAWS CLI, consulta [Test di uno stato utilizzando la console AWS Step Functions](#test-state-console) e[Testare uno stato utilizzando AWS CLI](#test-state-cli). ### INFO Inspection Level Se il test ha esito positivo, questo livello mostra l'output dello stato. Se il test fallisce, questo livello mostra l'output dell'errore. Per impostazione predefinita, Step Functions imposta il **livello di ispezione** **su INFO** se non si specifica un livello. #### Esempio di test con livello INFO che ha esito positivo L'immagine seguente mostra un test per uno stato Pass che ha esito positivo. Il **livello di ispezione** per questo stato è impostato su **INFO** e l'output per lo stato viene visualizzato nella scheda **Output**. ![\[Schermata dell'output a livello INFO di un test superato.\]](http://docs.aws.amazon.com/it_it/step-functions/latest/dg/images/test-state-info-success.png) #### Esempio di test con livello INFO che fallisce L'immagine seguente mostra un test fallito per uno stato Task quando il **livello di ispezione** è impostato su **INFO**. La scheda **Output** mostra l'output dell'errore che include il nome dell'errore e una spiegazione dettagliata della causa dell'errore. ![\[Schermata dell'output a livello INFO di un test fallito.\]](http://docs.aws.amazon.com/it_it/step-functions/latest/dg/images/test-state-info-failed.png) ### Livello di ispezione DEBUG Se il test ha esito positivo, questo livello mostra lo stato di output e il risultato dell'elaborazione dei dati di input e output. Se il test fallisce, questo livello mostra l'output dell'errore. Questo livello mostra i risultati intermedi dell'elaborazione dei dati fino al punto di errore. Ad esempio, supponiamo di aver testato uno stato Task che richiama una funzione. Lambda Immagina di aver applicato i [Filtraggio dell'output dello stato utilizzando OutputPath](input-output-example.md#input-output-outputpath) filtri[InputPath](input-output-inputpath-params.md#input-output-inputpath), [Parameters](input-output-inputpath-params.md#input-output-parameters)[Specificazione dello stato dell'output utilizzando ResultPath in Step Functions](input-output-resultpath.md), e allo stato Task. Supponiamo che l'invocazione sia fallita. In questo caso, il `DEBUG` livello mostra i risultati dell'elaborazione dei dati in base all'applicazione dei filtri nell'ordine seguente: + `input`— Input in stato grezzo + `afterInputPath`— Input after Step Functions applica il `InputPath` filtro. + `afterParameters`— L'input effettivo dopo l'Step Functionsapplicazione del `Parameters` filtro. Le informazioni diagnostiche disponibili in questo livello possono aiutarti a risolvere i problemi relativi all'[integrazione di un servizio](integrate-services.md) o al flusso di [elaborazione dei dati di input e output](#test-state-input-output-dataflow) che potresti aver definito. #### Esempio di test con livello DEBUG che ha esito positivo L'immagine seguente mostra un test per uno stato Pass che ha esito positivo. Il **livello di ispezione** per questo stato è impostato su **DEBUG**. La scheda **Elaborazione Input/Output** nell'immagine seguente mostra il risultato dell'applicazione di [`Parameters`](input-output-inputpath-params.md#input-output-parameters)sull'input fornito per questo stato. ![\[Schermata dell'output a livello di DEBUG relativo a un test superato.\]](http://docs.aws.amazon.com/it_it/step-functions/latest/dg/images/test-state-debug-success.png) #### Esempio di test con livello DEBUG che fallisce L'immagine seguente mostra un test fallito per uno stato Task quando il **livello di ispezione** è impostato su **DEBUG**. La scheda **Elaborazione input/output nell'immagine seguente mostra il risultato dell'elaborazione** dei dati di input e output per lo stato fino al punto in cui si è verificato il fallimento. ![\[Schermata dell'output a livello di DEBUG per un test fallito.\]](http://docs.aws.amazon.com/it_it/step-functions/latest/dg/images/test-state-debug-failed.png) ### Livello di ispezione TRACE Step Functions[fornisce il livello **TRACE** per testare un task HTTP.](call-https-apis.md) Questo livello restituisce informazioni sulla richiesta HTTP che Step Functions effettua e sulla risposta restituita da un'API HTTPS. La risposta potrebbe contenere informazioni, come le intestazioni e il corpo della richiesta. Inoltre, è possibile visualizzare l'output dello stato e il risultato dell'elaborazione dei dati di input e output in questo livello. Se il test fallisce, questo livello mostra l'output dell'errore. Questo livello è applicabile solo per HTTP Task. Step Functionsgenera un errore se si utilizza questo livello per altri tipi di stato. Quando si imposta il **livello di ispezione** su **TRACE**, è possibile visualizzare anche i segreti inclusi nella [EventBridge connessione](call-https-apis.md#http-task-authentication). A tale scopo, è necessario impostare il `revealSecrets` parametro su `true` nell'[TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html)API. Inoltre, devi assicurarti che l'IAMutente che chiama l' TestState API disponga dell'autorizzazione per l'`states:RevealSecrets`azione. Per un esempio di IAM politica che imposta l'`states:RevealSecrets`autorizzazione, vedi[IAMautorizzazioni per l'utilizzo dell'API TestState](#test-state-permissions). Senza questa autorizzazione, Step Functions genera un errore di accesso negato. Se si imposta il `revealSecrets` parametro su`false`, Step Functions omette tutti i segreti nei dati di richiesta e risposta HTTP. Tieni presente che non puoi utilizzarlo `revealSecrets` quando il mocking è abilitato. Se si specificano entrambi `revealSecrets` e un mock nella richiesta TestState API, Step Functions restituisce un'eccezione di convalida. #### Esempio di test con livello TRACE che ha esito positivo L'immagine seguente mostra un test per un task HTTP che ha esito positivo. Il **livello di ispezione** per questo stato è impostato su **TRACE**. La scheda **Richiesta e risposta HTTP** nell'immagine seguente mostra il risultato della chiamata all'API HTTPS. ![\[Schermata dell'output a livello TRACE di un test superato.\]](http://docs.aws.amazon.com/it_it/step-functions/latest/dg/images/test-state-trace-success.png) ## IAMautorizzazioni per l'utilizzo dell'API TestState L'IAMutente che chiama l'`TestState`API deve avere l'autorizzazione per eseguire l'`states:TestState`azione. Quando non si utilizza il mocking, l'IAMutente deve inoltre disporre dell'autorizzazione a eseguire l'`iam:PassRole`azione a cui passare il ruolo di esecuzione. Step Functions Inoltre, se si imposta il `revealSecrets` parametro su`true`, l'IAMutente deve disporre dell'autorizzazione per eseguire l'`states:RevealSecrets`azione. Senza questa autorizzazione, Step Functions genera un errore di accesso negato. Tieni presente che quando specifichi un mock nella richiesta TestState API, puoi testare la logica della tua macchina a stati senza fornire un ruolo di esecuzione (vedi maggiori dettagli in [Integrazioni del servizio di simulazione](#mocking-service-integrations)). Quando non si utilizzano mock, è necessario fornire un ruolo di esecuzione che contenga le autorizzazioni necessarie per le risorse a cui accede il proprio stato. [Per informazioni sulle autorizzazioni che potrebbero essere necessarie al tuo stato, vedi Gestione dei ruoli di esecuzione.](manage-state-machine-permissions.md) ## Test di uno stato utilizzando la console AWS Step Functions È possibile testare uno stato nella console e controllare lo stato di output o il flusso di elaborazione dei dati di input e output. Per un [task HTTP](call-https-apis.md), puoi testare la richiesta e la risposta HTTP non elaborate. **Nota** La TestState funzionalità della console non supporta ancora alcuni dei miglioramenti descritti in questo documento, come la simulazione delle integrazioni di servizi, il test degli stati Map e Parallel o Activity, .sync e. waitForTaskSchemi di token. Queste funzionalità sono attualmente disponibili solo tramite l' TestState API che utilizza AWS CLI o SDK. **Per testare uno stato** 1. Apri la [console Step Functions](https://console.aws.amazon.com/states/home?region=us-east-1#/). 1. Scegli **Crea macchina a stati** per iniziare a creare una macchina a stati o scegli una macchina a stati esistente. 1. In Workflow Studio, scegli lo stato che desideri testare. [Modalità progettazione](workflow-studio.md#wfs-interface-design-mode) 1. Scegliete **Stato [Pannello Inspector](workflow-studio.md#workflow-studio-components-formdefinition) di test** in Workflow Studio. 1. Nella finestra di dialogo **Stato di test**, effettuate le seguenti operazioni: 1. Per **Ruolo di esecuzione**, scegliete un ruolo di esecuzione per testare lo stato. Assicurati di disporre delle [IAMautorizzazioni](#test-state-permissions) necessarie per lo stato che desideri testare. 1. (Facoltativo) Fornisci qualsiasi input JSON necessario allo stato selezionato per il test. 1. Per **Livello di ispezione**, selezionate una delle seguenti opzioni in base ai valori che desiderate visualizzare: + [INFORMAZIONI](#test-state-info-level): mostra l'output dello stato nella scheda **Output** se il test ha esito positivo. Se il test fallisce, **INFO** mostra l'output dell'errore, che include il nome dell'errore e una spiegazione dettagliata della causa dell'errore. Per impostazione predefinita, Step Functions imposta il **livello di ispezione** **su INFO** se non si seleziona un livello. + [DEBUG](#test-state-debug-level): mostra l'output dello stato e il risultato dell'elaborazione dei dati di input e output se il test ha esito positivo. Se il test fallisce, **DEBUG** mostra l'output dell'errore, che include il nome dell'errore e una spiegazione dettagliata della causa dell'errore. + [TRACE](#test-state-trace-level): mostra la richiesta e la risposta HTTP non elaborate ed è utile per verificare intestazioni, parametri di query e altri dettagli specifici dell'API. [Questa opzione è disponibile solo per il task HTTP.](call-https-apis.md) Facoltativamente, puoi scegliere di selezionare **Reveal secrets**. In combinazione con **TRACE**, questa impostazione consente di visualizzare i dati sensibili inseriti dalla EventBridge connessione, come le chiavi API. L'identità IAM utente che utilizzi per accedere alla console deve disporre dell'autorizzazione per eseguire l'`states:RevealSecrets`azione. Senza questa autorizzazione, all'avvio Step Functions del test viene generato un errore di accesso negato. Per un esempio di IAM policy che imposta l'`states:RevealSecrets`autorizzazione, vedi[IAMautorizzazioni per l'utilizzo dell'API TestState](#test-state-permissions). 1. Scegli **Avvia test**. ## Testare uno stato utilizzando AWS CLI È possibile testare uno stato utilizzando l'[TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html)API inAWS CLI. Questa API accetta la definizione di uno stato e la esegue. Per ogni stato, puoi specificare la quantità di dettagli che desideri visualizzare nei risultati del test. Questi dettagli forniscono informazioni aggiuntive sull'esecuzione dello stato, inclusi i risultati dell'elaborazione dei dati di input e output e le informazioni su richieste e risposte HTTP. Gli esempi seguenti mostrano i diversi livelli di ispezione che è possibile specificare per l' TestState API. Questa sezione contiene i seguenti esempi che descrivono come utilizzare i diversi livelli di ispezione disponibili in: Step Functions AWS CLI + [Utilizzo di INFO InspectionLevel](#test-info-level-cli) + [Utilizzo di DEBUG InspectionLevel](#test-debug-level-cli) + [Utilizzo di TRACE InspectionLevel](#test-trace-level-cli) + [Utilizzo dell'utilità jq AWS CLI per filtrare e stampare la risposta HTTP restituita dall'API TestState ](#cli-readable-output) ### Esempio 1: utilizzo di INFO InspectionLevel per testare uno stato Choice Per testare uno stato utilizzando `INFO` [InspectionLevel](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html#StepFunctions-TestState-request-inspectionLevel) inAWS CLI, esegui il `test-state` comando come mostrato nell'esempio seguente. ``` 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}' ``` Questo esempio utilizza uno stato [Choice](state-choice.md) per determinare il percorso di esecuzione dello stato in base all'input numerico fornito. Per impostazione predefinita, Step Functions imposta `inspectionLevel` su `INFO` se non si imposta un livello. Step Functionsrestituisce il seguente risultato. ``` { "output": "{\"number\": 2}", "nextState": "Equals 2", "status": "SUCCEEDED" } ``` ### Esempio 2: utilizzo di DEBUG inspectionLevel per eseguire il debug dell'elaborazione dei dati di input e output in uno stato Pass Per testare uno stato utilizzando `DEBUG` [InspectionLevel](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html#StepFunctions-TestState-request-inspectionLevel) inAWS CLI, esegui il comando come mostrato nell'esempio seguente`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 ``` Questo esempio utilizza uno [Passare lo stato del workflow](state-pass.md) stato per mostrare come Step Functions filtra e manipola i dati JSON di input utilizzando i filtri di elaborazione dei dati di input e output. Questo esempio utilizza i seguenti filtri:`InputPath`,, e`Parameters`. `Specificazione dello stato dell'output utilizzando ResultPath in Step Functions` `Filtraggio dell'output dello stato utilizzando OutputPath` Step Functionsrestituisce il seguente risultato. ``` { "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" } ``` ### Esempio 3: utilizzo di TRACE InspectionLevel e RevealSecrets per ispezionare la richiesta HTTP inviata a un'API HTTPS Per testare un [task HTTP](call-https-apis.md) utilizzando `TRACE` [InspectionLevel](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html#StepFunctions-TestState-request-inspectionLevel) insieme al parametro [RevealSecrets](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html#StepFunctions-TestState-request-revealSecrets) in, esegui il comando come illustrato nell'AWS CLIesempio seguente. `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 ``` Questo esempio verifica se il task HTTP chiama l'API HTTPS specificata,. `https://httpbin.org/` Mostra anche i dati di richiesta e risposta HTTP per la chiamata API. Step Functionsrestituisce un output simile all'esempio originale nella documentazione corrente. ### Esempio 4: utilizzo dell'utilità jq per filtrare e stampare la risposta restituita dall' TestState API L' TestState API restituisce i dati JSON come stringhe di escape nella sua risposta. L'AWS CLIesempio seguente estende l'[esempio 3](#test-trace-level-cli) e utilizza l'`jq`utilità per filtrare e stampare la risposta HTTP restituita dall' TestState API in un formato leggibile dall'uomo. [Per informazioni `jq` e istruzioni di installazione, consulta jq on. *GitHub*](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' ``` L'esempio seguente mostra l'output restituito in un formato leggibile dall'uomo. ``` { "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" } ``` ## Test e debug del flusso di dati di input e output L'`TestState`API è utile per testare ed eseguire il debug dei dati che fluiscono attraverso il flusso di lavoro. Questa sezione fornisce alcuni concetti chiave e spiega come utilizzarli TestState per questo scopo. ### Concetti chiave NelStep Functions, il processo di filtraggio e manipolazione dei dati JSON mentre attraversano gli stati della macchina a stati viene chiamato elaborazione di *input* e output. Per ulteriori informazioni sul funzionamento, consulta [Elaborazione di input e output in Step Functions](concepts-input-output-filtering.md). Tutti i tipi di [stato](workflow-states.md) presenti in [Lingua degli Stati di Amazon](concepts-amazon-states-language.md) (ASL) (Task, Parallel, Map, Pass, Wait, Choice, Succeed e Fail) condividono una serie di campi comuni per filtrare e manipolare i dati JSON che li attraversano. Questi campi sono:[InputPath](input-output-inputpath-params.md#input-output-inputpath),, e[Parameters](input-output-inputpath-params.md#input-output-parameters). [ResultSelector](input-output-inputpath-params.md#input-output-resultselector) [Specificazione dello stato dell'output utilizzando ResultPath in Step Functions](input-output-resultpath.md) [Filtraggio dell'output dello stato utilizzando OutputPath](input-output-example.md#input-output-outputpath) Il supporto per ogni campo [varia a seconda degli stati](https://states-language.net/spec.html#state-type-table). In fase di esecuzione, Step Functions applica ogni campo in un ordine specifico. Il diagramma seguente mostra l'ordine in cui questi campi vengono applicati ai dati all'interno di uno stato del task: ![\[Ordine dei filtri: InputPath, Parametri, ResultSelector ResultPath, e OutputPath.\]](http://docs.aws.amazon.com/it_it/step-functions/latest/dg/images/input-output-processing.png) L'elenco seguente descrive l'ordine di applicazione dei campi di elaborazione di input e output mostrati nel diagramma. 1. L'*input di stato* è costituito dai dati JSON passati allo stato corrente da uno stato precedente. 1. [InputPath](input-output-inputpath-params.md#input-output-inputpath)filtra una parte dell'input allo stato grezzo. 1. [Parameters](input-output-inputpath-params.md#input-output-parameters)configura l'insieme di valori da passare al [Task](state-task.md). 1. L'attività esegue un lavoro e restituisce un risultato. 1. [ResultSelector](input-output-inputpath-params.md#input-output-resultselector)seleziona un insieme di valori da escludere dal risultato dell'attività. 1. [Specificazione dello stato dell'output utilizzando ResultPath in Step Functions](input-output-resultpath.md)combina il risultato con l'input allo stato grezzo o lo sostituisce con esso. 1. [Filtraggio dell'output dello stato utilizzando OutputPath](input-output-example.md#input-output-outputpath)filtra una parte dell'output per farla passare allo stato successivo. 1. *Lo stato di output* è costituito dai dati JSON passati dallo stato corrente allo stato successivo. Questi campi di elaborazione di input e output sono opzionali. Se non si utilizza nessuno di questi campi nella definizione dello stato, l'attività utilizzerà lo stato non elaborato e restituirà il risultato dell'attività come output dello stato. ### Utilizzo TestState per ispezionare l'elaborazione di input e output Quando si chiama l'`TestState`API e si imposta il `inspectionLevel` parametro su`DEBUG`, la risposta dell'API include un oggetto chiamato`inspectionData`. Questo oggetto contiene campi che consentono di verificare in che modo i dati sono stati filtrati o manipolati all'interno dello stato in cui sono stati eseguiti. L'esempio seguente mostra l'`inspectionData`oggetto per uno stato Task. ``` "inspectionData": { "input": string, "afterInputPath": string, "afterParameters": string, "result": string, "afterResultSelector": string, "afterResultPath": string, "output": string } ``` In questo esempio, ogni campo che contiene il `after` prefisso mostra i dati dopo l'applicazione di un determinato campo. Ad esempio, `afterInputPath` mostra l'effetto dell'applicazione del `InputPath` campo per filtrare l'input allo stato grezzo. Il diagramma seguente mappa ogni campo di [definizione ASL](concepts-amazon-states-language.md) al campo corrispondente nell'`inspectionData`oggetto: ![\[Diagramma che mostra la mappatura dei campi ASL su InspectionData.\]](http://docs.aws.amazon.com/it_it/step-functions/latest/dg/images/inspection-data-after-fields.png) Per esempi di utilizzo dell' TestState API per il debug dell'elaborazione di input e output, consulta quanto segue: + [Test di uno stato utilizzando il livello di ispezione DEBUG nella console Step Functions](#test-state-debug-level) + [Test di uno stato utilizzando il livello di ispezione DEBUG in AWS CLI](#test-debug-level-cli) In particolare per lo stato della mappa, quando `inspectionLevel` è impostato su`DEBUG`, l'`inspectionData`oggetto include campi aggiuntivi che consentono di controllare come lo stato della mappa estrae e trasforma gli elementi. Puoi saperne di più su questi campi nella sezione [Comprendere i dati di ispezione dello stato della mappa](#understanding-map-inspection-data). ### Comprensione dei dati delle ispezioni statali sulla mappa Quando testate uno stato della mappa con `inspectionLevel` set to`DEBUG`, la risposta dell' TestState API include campi aggiuntivi nell'`inspectionData`oggetto che mostrano come lo stato della mappa elabora i dati: **Nota** `afterItemsPath`viene compilato solo quando viene utilizzato JSONPath come linguaggio di interrogazione. + `afterItemsPath`(String) — L'input effettivo dopo l'applicazione del ItemsPath filtro. Questo mostra la serie di elementi estratti dall'input. + `afterItemsPointer`(String) — L'input effettivo dopo l'applicazione del ItemsPointer filtro. Questo è applicabile solo agli input JSON (non JSONata). + `afterItemSelector`(Array of Strings) — Un array contenente i valori di input dopo l'applicazione della ItemSelector trasformazione. Ogni elemento dell'array rappresenta un elemento trasformato. Questo campo è presente solo durante il test di uno stato della mappa. + `afterItemBatcher`(Array of Strings) — Un array contenente i valori di input dopo l'applicazione del ItemBatcher raggruppamento. Questo mostra come gli elementi vengono raggruppati in batch. Questo campo è presente solo durante il test di uno stato della mappa. + `toleratedFailureCount`(Numero) — La soglia di errore tollerata per uno stato della mappa espressa come conteggio delle iterazioni dello stato della mappa. Questo valore è derivato dal valore specificato in ToleratedFailureCount o dal valore valutato in fase di esecuzione da. ToleratedFailureCountPath + `toleratedFailurePercentage`(Numero) — La soglia di errore tollerata per uno stato della mappa espressa come percentuale di iterazioni dello stato della mappa. Questo valore è derivato dal valore specificato in ToleratedFailurePercentage o dal valore valutato in fase di esecuzione da. ToleratedFailurePercentagePath + `maxConcurrency`(Numero) — L'impostazione di concorrenza massima dello stato della mappa. Questi campi consentono di verificare che le trasformazioni dei dati e le configurazioni di tolleranza agli errori dello stato della mappa funzionino correttamente prima della distribuzione. ## Cosa puoi testare e affermare con l'API TestState L' TestState API consente di scrivere test unitari completi per le macchine a stati. Potete affermarvi su diversi aspetti della logica della vostra macchina a stati, tra cui: + [Gestione degli errori: a quale metodo Catch o Retry si applica](#error-handling-catch-retry) + [Trasformazioni dei dati: elaborazione di input e output](#data-transformations-assert) + [Trasformazioni dello stato della mappa: ItemSelector,, ItemsPath, ItemBatcher ItemsPointer](#map-state-transformations-assert) + [Soglie di errore dello stato della mappa: Stati di test. ExceedToleratedFailureThreshold](#map-failure-thresholds-assert) + [Propagazione degli errori negli stati Map e Parallel](#error-propagation-assert) ### Gestione degli errori: a quale metodo Catch o Retry si applica Quando simuli un errore, puoi utilizzare l' TestState API per vedere quale gestore di errori si attiva. Per i blocchi Catch, puoi affermare: + Quale gestore Catch rileva l'errore (tramite `catchIndex` nella risposta) + Quale sarà lo stato successivo (tramite `nextState` nella risposta) + Quali dati vengono trasmessi al gestore degli errori (tramite `output` nella risposta, considerando ResultPath) Per i blocchi Retry, puoi affermare: + Quale metodo si applica a Retry (tramite `retryIndex` nella risposta) + Qual è la durata del backoff (tramite `retryBackoffIntervalSeconds` nella risposta) + Se i nuovi tentativi sono esauriti e l'errore viene rilevato ### Trasformazioni dei dati: elaborazione di input e output Utilizzando l' TestState API, è possibile convalidare il modo in cui i dati di stato vengono trasformati in ogni fase dell'elaborazione. Puoi affermare su: + Input dopo il InputPath filtro () `afterInputPath` + Dati dopo Parameters/Arguments la trasformazione (`afterParameters`o`afterArguments`) + Risultato dopo ResultSelector (`afterResultSelector`) + Output dopo ResultPath (`afterResultPath`) + Output finale dopo OutputPath (`output`) ### Trasformazioni dello stato della mappa: ItemSelector,, ItemsPath, ItemBatcher ItemsPointer Per gli stati della mappa, puoi utilizzare l' TestState API per vedere come gli elementi vengono estratti e trasformati. Puoi affermare su: + Elementi dopo il ItemsPath filtro () `afterItemsPath` + Elementi dopo il ItemsPointer filtro (`afterItemsPointer`) + Elementi dopo ItemSelector la trasformazione (`afterItemSelector`) + Elementi dopo il ItemBatcher raggruppamento () `afterItemBatcher` ### Soglie di errore dello stato della mappa: Stati di test. ExceedToleratedFailureThreshold Verifica se un numero specifico di iterazioni fallite attiva la soglia di errore tollerata. Puoi affermare su: + Se lo stato della mappa fallisce con States. ExceedToleratedFailureThreshold ### Propagazione degli errori negli stati Map e Parallel Quando si testano gli stati all'interno degli stati Map o Parallel, gli errori si propagano ai gestori degli errori dello stato principale proprio come farebbero in un'esecuzione reale. #### Specificare l'origine dell'errore con State errorCausedBy Quando si simulano gli errori per gli stati Map o Parallel, è necessario specificare quale sottostato ha causato l'errore utilizzando il parametro. `stateConfiguration.errorCausedByState` Ciò è particolarmente importante quando si testano errori con caratteri jolly come. `States.TaskFailed` `States.TaskFailed`è un errore con caratteri jolly che si applica a qualsiasi errore relativo allo stato del task. Per verificare in che modo lo stato Map o Parallel gestisce questo errore, devi identificare lo stato secondario specifico che lo ha generato. Vedi l'esempio seguente: ``` aws stepfunctions test-state \ --definition '{...Map or Parallel state definition...}' \ --input '[...]' \ --state-configuration '{"errorCausedByState": "ProcessItem"}' \ --mock '{"errorOutput": {"error": "States.TaskFailed", "cause": "Task execution failed"}}' ``` In questo esempio, `errorCausedByState` indica TestState che lo stato "ProcessItem" all'interno del Map/Parallel flusso di lavoro ha generato l'errore. I gestori Catch o Retry Map/Parallel dello stato principale elaboreranno l'errore come farebbero durante l'esecuzione effettiva. Il `nextState` campo nella risposta mostra quale gestore degli errori ha rilevato l'errore. Puoi affermare su: + Se gli errori di stato figlio vengono rilevati dai gestori Catch principali + Se gli errori dello stato figlio attivano le politiche Retry dei genitori + Qual è lo stato successivo dopo la propagazione degli errori ## Integrazioni di servizi di simulazione L' TestState API supporta la simulazione dei risultati delle integrazioni di servizi, consentendoti di testare la logica della tua macchina a stati senza richiamare servizi effettivi. AWS ### Quando usare il mocking La presa in giro è utile per: + Unit Testing: definizioni isolate delle macchine a stato + Verifica della gestione degli errori e della logica dei tentativi + Convalida delle trasformazioni dei dati di input e output + Simulazione di varie risposte di servizio e condizioni di errore + Test senza configurare IAM le autorizzazioni Quando si specifica un mock, il `roleArn` parametro diventa facoltativo e consente di concentrarsi sul test della definizione della macchina a stati senza affrontare problemi relativi alle autorizzazioni. **Nota** Il mocking è necessario se è necessario testare i seguenti tipi di stato o modelli di integrazione dei servizi: integrazioni dei servizi Map, Parallel, Activity, .sync e integrazioni dei servizi Token. waitForTask ### Sintassi di simulazione di base Per simulare il risultato di un'integrazione di servizi: ``` 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\"}}"}' ``` Per simulare un errore: ``` 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"}}' ``` **Nota** Non è possibile fornire entrambi `mock.result` e `mock.errorOutput` nella stessa chiamata API. Ciò si traduce in un'eccezione di convalida. ### Modalità di convalida fittizie L' TestState API convalida le risposte simulate rispetto ai modelli di API di AWS servizio per garantire la correttezza. Puoi controllare il comportamento di convalida utilizzando il parametro: `fieldValidationMode` + **STRICT (impostazione predefinita)**: impone i vincoli di denominazione, dimensione, forma e tipo di dati dei campi dai modelli API. AWS Tutti i campi obbligatori devono essere presenti con i tipi corretti. Questa modalità aiuta a garantire che i modelli rappresentino accuratamente le risposte di assistenza reali. + **PRESENT**: convalida solo i campi presenti nel mock. I campi sconosciuti vengono ignorati. Questa modalità è utile quando si desidera flessibilità ma si desidera comunque la convalida su campi noti. + **NESSUNA**: ignora completamente la convalida. Usare con cautela in quanto ciò potrebbe portare a ipotesi e comportamenti errati del test che differiscono dalle esecuzioni effettive. **Nota** La convalida viene eseguita solo sui campi definiti nel modello dell'AWSAPI di servizio. Tutti i campi non specificati nel modello API vengono ignorati durante la convalida, indipendentemente dalla modalità di convalida. Ad esempio, se si utilizza la modalità STRICT per un'API che non definisce campi «obbligatori», una risposta fittizia vuota supererà la convalida. Esempio con modalità di convalida: ``` aws stepfunctions test-state \ --definition '{ "Type": "Task", "Resource": "arn:aws:states:::dynamodb:putItem", "Parameters": {...}, "End": true }' \ --input '{"key": "value"}' \ --mock '{"fieldValidationMode": "STRICT", "result": "{\"Attributes\": {...}}"}' ``` **Importante** La convalida fittizia non è supportata per le integrazioni [HTTP Task](call-https-apis.md), API Gateway, EKS Call ed EKS RunJob . ## Test degli stati di Map e Parallel L' TestState API supporta il test degli stati Map e Parallel quando viene specificato un mock. Ciò consente di testare l'elaborazione di input e output di questi stati di flusso. ### Comprensione dei test dello stato delle mappe Quando testate uno stato della mappa con l' TestState API, state testando l'elaborazione di input e output dello stato della mappa senza eseguire le iterazioni interne. Questo approccio consente di testare: + ItemsPath o ItemsPointer estrazione dall'input + ItemSelector trasformazione applicata a ciascun elemento + ItemBatcher raggruppamento (se specificato) + L'elaborazione dell'output dello stato della mappa (ResultPath, OutputPath) + Soglie di errore tollerate Non stai testando cosa succede all'interno degli ItemProcessor (gli stati che elaborano ogni elemento). ### Test dello stato di una mappa Quando si verifica uno stato della mappa, il risultato simulato deve rappresentare l'output dell'intero stato della mappa. Il risultato fittizio deve essere un array JSON o un oggetto JSON valido a seconda della configurazione dello stato della mappa. Vedi l'esempio seguente: ``` 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 ``` ### Test degli stati delle mappe distribuite Gli stati delle mappe distribuite vengono testati in modo simile agli stati delle mappe in linea. Quando la tua mappa utilizza un ItemReader per leggere da S3, fornisci i dati direttamente nell'input (come se fossero già stati letti da S3). Esempio: ``` 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": "..."}' ``` **Nota** Durante il test dello stato di Distributed Map (modalità impostata su DISTRIBUTED), puoi anche asserirlo su Count. mapIterationFailure Il valore di questo campo non può superare il numero di elementi nell'input o essere uguale al numero di elementi durante il test di uno stato all'interno di una mappa. ### Popolazione automatica del contesto Quando si verifica uno stato all'interno di uno stato della mappa (utilizzando il `stateName` parametro) senza fornire un `context` parametro, popola TestState automaticamente l'oggetto Context con valori predefiniti. Ciò include campi contestuali specifici della mappa come: + `$$.Map.Item.Index`= `0` (prima iterazione) + `$$.Map.Item.Value`= il tuo valore di input + `$$.Map.Item.Key`(per mappe distribuite con determinate ItemReader configurazioni) + `$$.Map.Item.Source`(per le mappe distribuite, indicando la fonte dell'articolo) ### Test degli stati paralleli Quando si testa uno stato parallelo, il risultato simulato deve essere un array JSON con un elemento per ogni ramo, nello stesso ordine in cui i rami appaiono nella definizione. ## Testing Activity, .sync e. waitForTaskStati dei token L' TestState API supporta il test degli stati di attività, dei modelli di integrazione del servizio.sync e. waitForTaskSchemi di token quando viene specificato un mock. Senza un mock, l'invocazione di questi stati tramite TestState API restituirà un'eccezione di convalida. **Nota** Per testare le integrazioni .sync utilizzando l' TestState API, la risposta simulata viene convalidata rispetto allo schema dell'API di polling. Ad esempio, durante il test`startExecution.sync:2`, il mock deve corrispondere allo schema di `DescribeExecution` risposta (che esamina lo stato), non alla rispostaStep Functions. `StartExecution` ## Iterazione attraverso le definizioni delle macchine a stati È possibile fornire una definizione completa della macchina a stati all' TestState API e specificare lo stato da testare utilizzando il `stateName` parametro. Ciò consente di testare quello stato specifico nel contesto della macchina a stati completa. È inoltre possibile concatenare i test utilizzando l'output e NextState da un test come input al successivo. Ciò consente di testare percorsi di esecuzione parziali o completi all'interno della macchina a stati. ## Utilizzo del campo contestuale nell' TestState API Il `context` parametro consente di fornire valori per l'oggetto Context che normalmente verrebbero compilati durante l'esecuzione. Questo è utile per testare gli stati che fanno riferimento a valori di contesto come l'ID di esecuzione, il nome dello stato o l'ora inserita. L'esempio seguente mostra come è possibile utilizzare l'oggetto Context nella chiamata 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\"}"}' ``` ## Test, ripetizione dei tentativi e della gestione degli errori L' TestState API consente di simulare scenari di nuovi tentativi e di testare la logica di gestione degli errori specificando tentativi di ripetizione ed errori di simulazione. ### Simulazione dei tentativi di nuovo tentativo ``` 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 ``` La risposta include i dettagli dell'errore in InspectionData: ``` { "status": "RETRIABLE", "inspectionData": { "errorDetails": { "retryBackoffIntervalSeconds": 4, "retryIndex": 0 } } } ``` Questa risposta indica: + L'errore è recuperabile (status: RETRIABLE) + La durata del backoff è di 4 secondi (2 × 2,0^1) + Si applica il primo tentativo (indice 0) ### Test dei gestori di catch Quando un errore viene simulato e corrisponde a un gestore Catch, il `nextState` campo nella risposta dell' TestState API indica quale stato gestirà l'errore. Nell'esempio seguente: Per la richiesta TestState API indicata di seguito, ``` 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 ``` La risposta API prevista dovrebbe essere: ``` { "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 } } } ``` Questa risposta indica che: + l'errore viene rilevato (status: CAUGHT\$1ERROR) + lo stato successivo è HandleThrottling + le informazioni sull'errore vengono aggiunte all'output tramite ResultPath + il primo gestore Catch (indice 0) ha rilevato l'errore Puoi anche verificare cosa succede quando tutti i tentativi di riprova sono esauriti aumentando RetryCount i valori nell'oggetto contestuale.