Présentation des tests avec sam local invoke

Utilisez la AWS Serverless Application Model sam local invoke sous-commande Command Line Interface (AWS SAMCLI) pour lancer un appel unique d'une AWS Lambda fonction localement.

• Pour une introduction à la AWS SAMCLI, voirQu'est-ce que c'est AWS SAMCLI ?.

• Pour obtenir la liste des options de commande sam local invoke, consultez sam local invoke.

• Pour un exemple d'utilisation de sam local invoke dans le cadre d'un flux de travail de développement classique, consultez Étape 7 : (Facultatif) testez votre application localement.

Prérequis

Pour utiliser sam local invoke, installez la CLI AWS SAM en procédant comme suit :

• AWS SAM prérequis.

• Installer la CLI  AWS SAM.

Avant d'utiliser sam local invoke, nous vous recommandons d'avoir des connaissances de base sur les points suivants :

• Configuration de la CLI  AWS SAM.

• Créez votre application à l'aide de la sam init commande.

• Présentation de la construction avec la sam build commande.

• Présentation du déploiement à l'aide de la sam deploy commande.

Appel d'une fonction Lambda localement

Lorsque vous utilisez sam local invoke, la CLI AWS SAM suppose que le répertoire de travail actuel est le répertoire racine du projet. La CLI AWS SAM recherche d'abord un fichier template.[yaml|yml] dans un sous-dossier .aws-sam. Si elle ne le trouve pas, la CLI AWS SAM recherche un fichier template.[yaml|yml] dans votre répertoire de travail actuel.

Pour appeler une fonction Lambda localement

1. À partir du répertoire racine de votre projet, effectuez les actions suivantes :

   $ sam local invoke <options>

2. Si votre application contient plusieurs fonctions, indiquez l'identifiant logique de la fonction. Voici un exemple :

   $ sam local invoke HelloWorldFunction

3. La CLI  AWS SAM crée votre fonction dans un conteneur local à l'aide de Docker. Elle invoque ensuite votre fonction et génère la réponse de votre fonction.

   Voici un exemple :

   $ sam local invoke
   Invoking app.lambda_handler (python3.9)
   Local image is out of date and will be updated to the latest runtime. To skip this, pass in the parameter --skip-pull-image
   Building image....................................................................................................................
   Using local image: public.ecr.aws/lambda/python:3.9-rapid-x86_64.
   
   Mounting /Users/.../sam-app/.aws-sam/build/HelloWorldFunction as /var/task:ro,delegated, inside runtime container
   START RequestId: 64bf7e54-5509-4762-a97c-3d740498d3df Version: $LATEST
   END RequestId: 64bf7e54-5509-4762-a97c-3d740498d3df
   REPORT RequestId: 64bf7e54-5509-4762-a97c-3d740498d3df  Init Duration: 1.09 ms  Duration: 608.42 ms       Billed Duration: 609 ms Memory Size: 128 MB     Max Memory Used: 128 MB
   {"statusCode": 200, "body": "{\"message\": \"hello world\"}"}% 

Gestion des journaux

Lorsque vous utilisez sam local invoke, le résultat d'exécution de la fonction Lambda (par exemple, les journaux) sort vers stderr et le résultat de la fonction Lambda sors vers stdout.

Voici un exemple de fonction Lambda de base :

def handler(event, context):
    print("some log") # this goes to stderr
    return "hello world" # this goes to stdout

Vous pouvez enregistrer ces résultats standard. Voici un exemple :

$ sam local invoke 1> stdout.log
...

$ cat stdout.log
"hello world"

$ sam local invoke 2> stderr.log
...

$ cat stderr.log
Invoking app.lambda_handler (python3.9)
Local image is up-to-date
Using local image: public.ecr.aws/lambda/python:3.9-rapid-x86_64.
Mounting /Users/.../sam-app/.aws-sam/build/HelloWorldFunction as /var/task:ro,delegated, inside runtime container
START RequestId: 0b46e646-3bdf-4b58-8beb-242d00912c46 Version: $LATEST
some log
END RequestId: 0b46e646-3bdf-4b58-8beb-242d00912c46
REPORT RequestId: 0b46e646-3bdf-4b58-8beb-242d00912c46  Init Duration: 0.91 ms  Duration: 589.19 ms Billed Duration: 590 ms Memory Size: 128 MB Max Memory Used: 128 MB 

Vous pouvez utiliser ces résultats standard pour automatiser davantage vos processus de développement locaux.

Options

Transmettez des événements personnalisés pour appeler la fonction Lambda

Pour transmettre un événement à la fonction Lambda, utilisez l'option --event. Voici un exemple :

$ sam local invoke --event events/s3.json S3JsonLoggerFunction

Vous pouvez créer des événements à l'aide de la sous-commande sam local generate-event. Pour en savoir plus, veuillez consulter la section Présentation des tests avec sam local generate-event.

Transmettre des variables d'environnement lors de l'appel de votre fonction Lambda

Si votre fonction Lambda utilise des variables d'environnement, vous pouvez les transmettre lors des tests locaux à l'aide de l'option --env-vars. C'est un excellent moyen de tester une fonction Lambda localement avec des services de votre application qui sont déjà déployés dans le cloud. Voici un exemple :

$ sam local invoke --env-vars locals.json

Spécifier un modèle ou une fonction

Pour spécifier un modèle à référencer par la CLI AWS SAM, utilisez l'option --template. Ils AWS SAMCLI chargeront uniquement ce AWS SAM modèle et les ressources vers lesquelles il pointe.

Pour appeler une fonction d'une application ou d'une pile imbriquée, fournissez l'identifiant logique de l'application ou de la pile avec l'identifiant logique. Voici un exemple :

$ sam local invoke StackLogicalId/FunctionLogicalId

Tester une fonction Lambda à partir de votre projet Terraform

Utilisez l'option --hook-name pour tester localement les fonctions Lambda de vos projets Terraform. Pour en savoir plus, veuillez consulter la section Utilisation de la CLI  AWS SAM avec Terraform pour le débogage et les tests locaux.

Voici un exemple :

$ sam local invoke --hook-name terraform --beta-features

Bonnes pratiques

Si votre application possède un répertoire .aws-sam qui exécute sam build, assurez-vous d'exécuter sam build chaque fois que vous mettez à jour le code de votre fonction. Exécutez ensuite sam local invoke pour tester localement votre code de fonction mis à jour.

Les tests locaux constituent une excellente solution pour un développement et des tests rapides avant le déploiement dans le cloud. Toutefois, les tests locaux ne valident pas tout, notamment les autorisations entre vos ressources dans le cloud. Dans la mesure du possible, testez vos applications dans le cloud. Nous vous recommandons d'utiliser sam sync pour accélérer vos flux de travail de test dans le cloud.

Exemples

Générer un exemple d'événement Amazon API Gateway et l'utiliser pour appeler une fonction Lambda localement

Tout d'abord, nous générons une charge utile d'événement API HTTP API Gateway et l'enregistrons dans notre dossier events.

$ sam local generate-event apigateway http-api-proxy > events/apigateway_event.json

Ensuite, nous modifions notre fonction Lambda pour qu'elle renvoie une valeur de paramètre à partir de l'événement.

def lambda_handler(event, context):
    print("HelloWorldFunction invoked")
    return {
        "statusCode": 200,
        "body": json.dumps({
            "message": event['queryStringParameters']['parameter2'],
        }),
    }

Ensuite, nous invoquons localement notre fonction Lambda et fournissons notre événement personnalisé.

$ sam local invoke --event events/apigateway_event.json

Invoking app.lambda_handler (python3.9)
Local image is up-to-date
Using local image: public.ecr.aws/lambda/python:3.9-rapid-x86_64.

Mounting /Users/...sam-app/.aws-sam/build/HelloWorldFunction as /var/task:ro,delegated, inside runtime container
START RequestId: 59535d0d-3d9e-493d-8c98-6264e8e961b8 Version: $LATEST
some log
END RequestId: 59535d0d-3d9e-493d-8c98-6264e8e961b8
REPORT RequestId: 59535d0d-3d9e-493d-8c98-6264e8e961b8  Init Duration: 1.63 ms  Duration: 564.07 ms       Billed Duration: 565 ms Memory Size: 128 MB     Max Memory Used: 128 MB
{"statusCode": 200, "body": "{\"message\": \"value\"}"}%

Transmettre des variables d'environnement lors de l'appel d'une fonction Lambda localement

Cette application possède une fonction Lambda qui utilise une variable d'environnement pour un nom de table Amazon DynamoDB. Voici un exemple de la fonction définie dans le AWS SAM modèle :

AWSTemplateFormatVersion: 2010-09-09
Transform: AWS::Serverless-2016-10-31
...
Resources:
  getAllItemsFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: src/get-all-items.getAllItemsHandler
      Description: get all items
      Policies:
        - DynamoDBReadPolicy:
            TableName: !Ref SampleTable
      Environment:
        Variables:
          SAMPLE_TABLE: !Ref SampleTable
...

Nous souhaitons tester localement notre fonction Lambda tout en la faisant interagir avec notre table DynamoDB dans le cloud. Pour ce faire, nous créons notre fichier de variables d'environnement et l'enregistrons dans le répertoire racine de notre projet sous le nom locals.json. La valeur fournie ici pour SAMPLE_TABLE fait référence à notre table DynamoDB dans le cloud.

{
    "getAllItemsFunction": {
        "SAMPLE_TABLE": "dev-demo-SampleTable-1U991234LD5UM98"
    }
}

Ensuite, nous exécutons sam local invoke et transmettons nos variables d'environnement avec l'option --env-vars.

$ sam local invoke getAllItemsFunction --env-vars locals.json

Mounting /Users/...sam-app/.aws-sam/build/HelloWorldFunction as /var/task:ro,delegated, inside runtime container
START RequestId: 59535d0d-3d9e-493d-8c98-6264e8e961b8 Version: $LATEST
some log
END RequestId: 59535d0d-3d9e-493d-8c98-6264e8e961b8
REPORT RequestId: 59535d0d-3d9e-493d-8c98-6264e8e961b8  Init Duration: 1.63 ms  Duration: 564.07 ms       Billed Duration: 565 ms Memory Size: 128 MB     Max Memory Used: 128 MB
{"statusCode":200,"body":"{}"}

En savoir plus

Pour obtenir la liste de toutes les options sam local invoke, consultez sam local invoke.

Pour une démonstration de l'utilisation de sam local, consultez AWS SAM pour le développement local. Tester AWS Cloud des ressources issues d'environnements de développement locaux dans le cadre de la série Serverless Land Sessions with SAM on YouTube.