Analyse du système de test du Framwork Serverless : des tests unitaires à la configuration de l'environnement d'intégration AWS

Vue d'ensemble du système de test : Tests unitaires et d'intégration

Le dépôt divise ses tests en deux catégories, comme défini au début du fichier TESTING.md :

• Tests Unitaires (Unit Tests) : Ces tests ne dépendent d’aucune ressource externe (pas de compte AWS ou de Dashboard), et sont situés dans le répertoire test de chaque package.
• Tests d'Intégration (Integration Tests) : Ils nécessitent une configuration préalable incluant un compte AWS, un organisation Serverless Dashboard et Terraform Cloud. Ces tests s'exécutent automatiquement dans CI lors de la soumission d'une Pull Request, mais peuvent également être lancés localement si les conditions préalables mentionnées dans ce document sont satisfaites.

Le principal espace de travail pour les tests est packages/sf-core (nom du package npm @serverlessinc/sf-core, dont la version actuelle peut être consultée dans le champ version du fichier package.json). Dans le fichier jest.config.cjs, on trouve plusieurs configurations clés :

• testTimeout: 600000 (10 minutes par cas de test) — nécessaire car les tests d'intégration impliquent le déploiement réel de ressources AWS, ce qui prend plus de temps que les 5 secondes par défaut.
• transform: {} désactive la transformation Babel, indiquant que toute la pile de tests fonctionne en mode ESM natif ("type": "module" dans package.json).
• modulePathIgnorePatterns: ['<rootDir>/tests/python/tests/'] — exclut les fixtures Python, car elles constituent des projets indépendants plutôt que des modules du package.

Exécution de tous les tests d'intégration

Pour exécuter tous les tests d'intégration depuis le répertoire racine :

npm test -w @serverlessinc/sf-core

Ce script correspond à la définition complète suivante dans package.json :

cross-env NODE_OPTIONS="$NODE_OPTIONS --experimental-vm-modules" NODE_NO_WARNINGS=1 \
  jest "tests/integration/.*" \
  --testPathIgnorePatterns=/node_modules/ \
  --testPathIgnorePatterns=tests/integration/domains \
  --testPathIgnorePatterns=tests/integration/mcp/

Deux ensembles de tests sont exclus par défaut, conformément aux recommandations de TESTING.md :

Ensembles Exclus	Méthode d'exécution	Raison d'exclusion
domains	npm run test:domains -w @serverlessinc/sf-core	Nécessite l'utilisation de noms de domaine réels ; le script utilise également --runInBand pour une exécution séquentielle.
mcp (Serveurs MCP)	npm run test:mcp -w @serverlessinc/sf-core	Déploie des API REST réelles et est déclenché uniquement lorsque des modifications concernant ces serveurs sont effectuées.

Exécution de tests spécifiques

Le fichier package.json de packages/sf-core fournit des scripts individuels pour chaque ensemble de tests d'intégration. Par exemple :

# Exécute les tests d'intégration pour les résolveurs (répertoire tests/resolvers/)
npm run test:resolvers -w @serverlessinc/sf-core

# Autres scripts courants :
npm run test:sam                 # tests/integration/sam/**
npm run test:simple:nodejs       # tests/integration/simple-nodejs/**
npm run test:simple:python       # tests/integration/simple-python/**
npm run test:simple:dashboard    # tests/integration/simple-dashboard/**
npm run test:simple:compose      # tests/integration/simple-compose/**
npm run test:compose:dev        # tests/integration/compose-dev/**
npm run test:compose:subset     # tests/integration/compose-service-subset/**
npm run test:sandboxes          # tests/integration/sandboxes/**
npm run test:esbuild            # tests/integration/esbuild/**
npm run test:state              # tests/integration/state/**
npm run test:deployment-bucket  # tests/integration/deployment-bucket/**
npm run test:license-key        # tests/integration/license-key/**
npm run test:mcp                # tests/integration/mcp/（--maxWorkers=2）

La définition complète du script test:mcp mérite une attention particulière :

cross-env NODE_OPTIONS="$NODE_OPTIONS --experimental-vm-modules" NODE_NO_WARNINGS=1 \
  jest tests/integration/mcp/ --testPathIgnorePatterns=/node_modules/ --maxWorkers=2

L'option --maxWorkers=2 est intentionnelle, car cet ensemble de tests déploie simultanément plusieurs API Gateway + Lambda réels, et un nombre excessif de workers pourrait provoquer des limites d'API AWS.

Préparation de l'environnement de test : Variables d'environnement nécessaires

Avant d'exécuter les tests d'intégration localement, exportez les deux variables suivantes :

export SERVERLESS_LICENSE_KEY_DEV="votre-clé-de-license"
export SERVERLESS_ACCESS_KEY_DEV="votre-clé-d'accès"

SERVERLESS_LICENSE_KEY_DEV est utilisé pour la validation liée à la licence du framework, tandis que SERVERLESS_ACCESS_KEY_DEV est la clé d'accès au Serverless Dashboard. Dans CI, ces secrets sont injectés via le fichier .github/workflows/ci-mcp.yml. Des paramètres supplémentaires y sont également définis :

• TEST_STAGE: pr-${{ github.event.pull_request.user.login }} : Génère un stage avec un préfixe spécifique à l'auteur pour éviter tout conflit entre différentes PRs.
• SLS_AWS_SDK: 3 et AWS_MAX_ATTEMPTS: 7 : Spécifie explicitement l'utilisation d'AWS SDK v3 avec un nombre accru de tentatives pour compenser d'éventuelles fluctuations temporaires après déploiement.

Le gestionnaire de tests traite également la période où les ressources viennent d'être déployées mais ne sont pas encore pleinement opérationnelles. Dans tests/utils/testUtils.js, la fonction fetchWithRetry tente jusqu'à cinq fois de récupérer une réponse non 2xx, avec un intervalle de 5 secondes entre chaque tentative.

Ressources AWS prérequis

Les ressources AWS nécessaires sont listées en détail dans TESTING.md, segmentées par région.

Paramètres SSM (Parameter Store)

us-east-1 :

Chemin du paramètre	Type	Valeur
/resolvers/sample-param	String	ssm-value
/resolvers/sample-secure-param	SecureString	ssm-value
/resolvers/sample-list-param	StringList	foo,bar
/resolvers/sample-json-param	SecureString	{ "foo": "bar" }
/resolvers/object-secure-param	SecureString	{ "objectKey": "objectValue" }
/serverless-framework/license-key-serverlesstestaccount	SecureString	votre-clé-de-license
/resolvers/terraform-hcp-token	String	votre-jeton-terraform-hcp

eu-west-1 :

Chemin du paramètre	Type	Valeur
/resolvers/sample-param	String	ssm-value
/resolvers/sample-secure-param-eu-west-1	SecureString	ssm-value

Ces paramètres couvrent divers types de branches de résolution de paramètres AWS dans les tests d'intégration des résolveurs.

Secrets Manager

Dans us-east-1, il doit exister un secret nommé resolvers/sample-secret contenant :

{
  "num": 1,
  "str": "secret",
  "arr": [true, false]
}

Buckets S3

Nom du bucket	Exigence
serverless-compose-state-bucket-integration-test	Versioning activé, utilisé pour tester le stockage d'état compose.
terraform-s3-resolver-test-bucket	Versioning activé, utilisé pour tester le résolveur d'état Terraform S3.
resolvers-integration-test	Contient un fichier test.txt avec le contenu file content.

Tables DynamoDB

Dans us-east-1 :

• Table terraform-s3-resolver-test-lock-table avec clé primaire LockID (type String) — utilisée pour tester le mécanisme de verrouillage des résolveurs.

Empilements CloudFormation

Chaque région doit disposer d'un empilement nommé sfc-nodejs-resolvers-integration-test :

Région	Output : ServerlessDeploymentBucketName	Output : Function1LambdaFunctionQualifiedArn
us-east-1	sfc-nodejs-resolvers-inte-serverlessdeploymentbuck-6vskiu5gzt1u	arn:aws:lambda:us-east-1:762003938904:function:sfc-nodejs-resolvers-integration-test-function1:1
eu-west-1	sfc-nodejs-resolvers-inte-serverlessdeploymentbuck-vky0nzemsvvr	arn:aws:lambda:eu-west-1:762003938904:function:sfc-nodejs-resolvers-integration-test-function1:1

Pools Cognito (Spécifique aux tests MCP)

Le fichier mcp-auth.test.js teste les configurations d'autorisation MCP. Il comprend plusieurs scénarios :

1. Autorisateur basé sur un pool utilisateur Cognito.
2. Autorisateurs Lambda de type TOKEN et REQUEST, vérifiant des clés partagées générées dynamiquement.
3. Serveurs sans aucune configuration d'autorisation, validant des flux normaux et des notifications JSON-RPC.
4. Document oauthDiscovery fourni par une route MOCK d'API Gateway.

Déploiement du pool prérequis

Le pool est un prérequis unique, persistant et spécifique au compte, défini par template.yml. Pour le déployer :

cd packages/sf-core/tests/integration/mcp-cognito-prerequisite
serverless deploy --stack mcp-integration-test-cognito --region us-east-1

Cette commande crée notamment :

• Un pool utilisateur Lite (UserPoolTier: LITE) nommé mcp-integration-test.
• Un domaine utilisateur mcp-integration-test-${AWS::AccountId}.
• Une ressource serveur mcp avec une scope personnalisée invoke.

Les identifiants client et secrets sont stockés dans SSM sous forme sécurisée et nettoyés lors de la suppression du stack.

Conditions préalables Serverless Dashboard

Le Dashboard nécessite deux services :

• Service resolvers-custom-test : Paramètre Dashboard dashboard-param = dashboard-value.
• Service resolver-output-producer : Outputs Dashboard définissant des valeurs de type chaîne, numérique et objet.

Conditions préalables Terraform Cloud

• Orgenisation : serverlesstestaccount
• Espace de travail : serverless-test-01

Accompagné du paramètre SSM /resolvers/terraform-hcp-token, il soutient les assertions d'intégration dans tests/integration/resolvers/terraform/.

Comptes de test CI : OIDC remplaçant les clés permanentes

Aucune clé AWS permanente n'est utilisée en CI. Chaque workflow assume un rôle nommé GithubActionsDeploymentRole via le fournisseur OIDC GitHub. Les comptes supplémentaires sont utilisés pour isoler les charges de travail, évitant ainsi les limites d'API AWS partagées.

Autres ensembles de tests

Des scripts supplémentaires sont disponibles dans TESTING.md :

Commande	Description
npm test -w @serverless/engine	Tests unitaires pour packages/engine.
npm test -w @serverless/mcp	Tests MCP server (non exécutés par CI).
npm run test:python -w @serverlessinc/sf-core	Tests du plugin Python.
npm run test:build -w @serverlessinc/sf-core	Tests de fumée pour les builds/distributions.