Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Écriture d’un script Canary Node.js en utilisant l’exécution Playwright
**Topics**
+ [Empaquetage de vos fichiers Canary Node.js pour l’exécution Playwright](#Synthetics_canary_Nodejs_Playwright_package)
+ [Modification d'un script de dramaturge existant pour l'utiliser comme canari CloudWatch Synthetics](#CloudWatch_Synthetics_canary_edit_Playwright_script)
+ [CloudWatch Configurations Synthetics](#Synthetics_canary_configure_Playwright_script)
## Empaquetage de vos fichiers Canary Node.js pour l’exécution Playwright
Votre script Canary est constitué d’un fichier `.js` (syntaxe CommonJS) ou `.mjs` (syntaxe ES) contenant votre code de gestionnaire Synthetics,ainsi que de tout autre module ou package dont votre code dépend. Les scripts créés au format ES (ECMAScript) doivent utiliser .mjs comme extension ou inclure un fichier package.json avec le champ « type » : « module » défini. Contrairement à d’autres exécutions comme Node.js Puppeteer, il n’est pas nécessaire de respecter une structure de dossiers particulière pour enregistrer vos scripts. Vous pouvez empaqueter vos scripts directement. Utilisez votre utilitaire `zip` préféré pour créer un fichier `.zip` contenant votre fichier gestionnaire à la racine. Si votre script Canary dépend de packages supplémentaires qui ne sont pas inclus dans l’exécution Synthetics, vous pouvez les ajouter dans votre fichier `.zip`. Pour ce faire, vous pouvez installer les bibliothèques requises par votre fonction dans le répertoire `node_modules` à l’aide de la commande `npm install`. L’exemple suivant montre les commandes CLI permettant de créer un fichier `.zip` nommé `my_deployment_package.zip`, contenant le fichier `index.js` ou `index.mjs` (le gestionnaire Synthetics) ainsi que ses dépendances. Dans cet exemple, les dépendances sont installées à l’aide du gestionnaire de packages `npm`.
```
~/my_function
├── index.mjs
├── synthetics.json
├── myhelper-util.mjs
└── node_modules
├── mydependency
```
Créez un fichier `.zip` contenant le contenu de votre dossier de projet à la racine. Utilisez l’option `r` (récursive), comme dans l’exemple ci-dessous, pour que `zip` compresse également les sous-dossiers.
```
zip -r my_deployment_package.zip .
```
Ajoutez un fichier de configuration Synthetics pour configurer le comportement de Synthetics. CloudWatch Vous pouvez créer un fichier `synthetics.json` et l’enregistrer au même emplacement que votre point d’entrée ou fichier gestionnaire.
En option, vous pouvez également enregistrer votre fichier de point d’entrée dans une structure de dossiers de votre choix. Assurez-vous toutefois que le chemin du dossier est indiqué dans le nom de votre gestionnaire.
**Nom du gestionnaire**
Assurez-vous de définir le point d'entrée (gestionnaire) de votre script Canary de sorte que ` myCanaryFilename.functionName` corresponde au nom du fichier du point d'entrée de votre script. Vous pouvez également stocker le script Canary dans un dossier séparé, tel que ` myFolder/my_canary_filename.mjs`. Si vous le stockez dans un dossier séparé, spécifiez ce chemin dans le point d'entrée de votre script, tel que ` myFolder/my_canary_filename.functionName`.
## Modification d'un script de dramaturge existant pour l'utiliser comme canari CloudWatch Synthetics
Vous pouvez modifier un script existant pour Playwright et Node.js afin de l’utiliser comme script Canary. Pour plus d’informations sur Playwright, consultez la documentation de la [bibliothèque Playwright](https://playwright.dev/docs/api/class-playwright).
Vous pouvez utiliser le script Playwright suivant qui est enregistré dans le fichier ` exampleCanary.mjs`.
```
import { chromium } from 'playwright';
import { expect } from '@playwright/test';
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://example.com', {timeout: 30000});
await page.screenshot({path: 'example-home.png'});
const title = await page.title();
expect(title).toEqual("Example Domain");
await browser.close();
```
Pour le convertir le script, procédez comme suit :
1. Créez et exportez une fonction `handler`. Le gestionnaire est la fonction de point d'entrée du script. Vous pouvez choisir n’importe quel nom pour la fonction de gestionnaire, mais celui utilisé dans votre script doit être identique à celui défini dans le gestionnaire Canary. Si le nom de votre script est `exampleCanary.mjs` et que le nom de la fonction de gestionnaire est `myhandler`, alors le gestionnaire Canary s’appelle `exampleCanary.myhandler`. Dans l’exemple suivant, le nom de fonction de gestionnaire est `handler`.
```
exports.handler = async () => {
// Your script here
};
```
1. Importez le `Synthetics Playwright module` en tant que dépendance.
```
import { synthetics } from '@aws/synthetics-playwright';
```
1. Lancez un navigateur à l’aide de la fonction `Launch` Synthetics.
```
const browser = await synthetics.launch();
```
1. Créez une nouvelle page Playwright à l’aide de la fonction Synthetics `newPage`.
```
const page = await synthetics.newPage();
```
Votre script est maintenant prêt à être exécuté en tant que script Canary Synthetics. Exemple de script mis à jour :
**Script mis à jour au ES6 format**
Le fichier de script est enregistré avec une extension `.mjs`.
```
import { synthetics } from '@aws/synthetics-playwright';
import { expect } from '@playwright/test';
export const handler = async (event, context) => {
try {
// Launch a browser
const browser = await synthetics.launch();
// Create a new page
const page = await synthetics.newPage(browser);
// Navigate to a website
await page.goto('https://www.example.com', {timeout: 30000});
// Take screenshot
await page.screenshot({ path: '/tmp/example.png' });
// Verify the page title
const title = await page.title();
expect(title).toEqual("Example Domain");
} finally {
// Ensure browser is closed
await synthetics.close();
}
};
```
**Script mis à jour au format CommonJS**
Le fichier de script est enregistré avec une extension `.js`.
```
const { synthetics } = require('@aws/synthetics-playwright');
const { expect } = require('@playwright/test');
exports.handler = async (event) => {
try {
const browser = await synthetics.launch();
const page = await synthetics.newPage(browser);
await page.goto('https://www.example.com', {timeout: 30000});
await page.screenshot({ path: '/tmp/example.png' });
const title = await page.title();
expect(title).toEqual("Example Domain");
} finally {
await synthetics.close();
}
};
```
## CloudWatch Configurations Synthetics
Vous pouvez configurer le comportement de l’exécution Playwright Synthetics à l’aide d’un fichier de configuration JSON facultatif nommé `synthetics.json`. Ce fichier doit être empaqueté au même emplacement que le fichier gestionnaire. Bien qu'un fichier de configuration soit facultatif, si vous ne fournissez pas de fichier de configuration ou si une clé de configuration est manquante, CloudWatch il utilise les valeurs par défaut.
**Empaquetage de votre fichier de configuration**
Les valeurs de configuration prises en charge et leurs valeurs par défaut sont les suivantes.
```
{
"step": {
"screenshotOnStepStart": false,
"screenshotOnStepSuccess": false,
"screenshotOnStepFailure": false,
"stepSuccessMetric": true,
"stepDurationMetric": true,
"continueOnStepFailure": true,
"stepsReport": true
},
"report": {
"includeRequestHeaders": true,
"includeResponseHeaders": true,
"includeUrlPassword": false,
"includeRequestBody": true,
"includeResponseBody": true,
"restrictedHeaders": ['x-amz-security-token', 'Authorization'], // Value of these headers is redacted from logs and reports
"restrictedUrlParameters": ['Session', 'SigninToken'] // Values of these url parameters are redacted from logs and reports
},
"logging": {
"logRequest": false,
"logResponse": false,
"logResponseBody": false,
"logRequestBody": false,
"logRequestHeaders": false,
"logResponseHeaders": false
},
"httpMetrics": {
"metric_2xx": true,
"metric_4xx": true,
"metric_5xx": true,
"failedRequestsMetric": true,
"aggregatedFailedRequestsMetric": true,
"aggregated2xxMetric": true,
"aggregated4xxMetric": true,
"aggregated5xxMetric": true
},
"canaryMetrics": {
"failedCanaryMetric": true,
"aggregatedFailedCanaryMetric": true
},
"userAgent": "",
"har": true
}
```
**Étapes de configuration**
+ `screenshotOnStepStart` : détermine si Synthetics doit prendre une capture d’écran avant le début de l’étape. La valeur par défaut est `true`.
+ `screenshotOnStepSuccess` : détermine si Synthetics doit prendre une capture d’écran après la réussite d’une étape. La valeur par défaut est `true`.
+ `screenshotOnStepFailure` : détermine si Synthetics doit prendre une capture d’écran après l’échec d’une étape. La valeur par défaut est `true`.
+ `continueOnStepFailure` : détermine si un script doit continuer à s’exécuter même après l’échec d’une étape. La valeur par défaut est `false`.
+ `stepSuccessMetric` : détermine si la métrique ` SuccessPercent` d’une étape est émise. La métrique `SuccessPercent` d’une étape est `100` pour l’exécution du script Canary si l’étape réussit, et `0` si l’étape échoue. La valeur par défaut est `true`.
+ `stepDurationMetric` : détermine si la métrique `Duration` d’une étape est émise. La métrique `Duration` est émise sous forme de durée, en millisecondes, de l’exécution de l’étape. La valeur par défaut est `true`.
**Configurations des rapports**
Inclut tous les rapports générés par CloudWatch Synthetics, tels qu'un fichier HAR et un rapport sur les étapes de Synthetics. Les champs de masquage des données sensibles, `restrictedHeaders` et `restrictedUrlParameters`, s’appliquent également aux journaux générés par Synthetics.
+ `includeRequestHeaders` : indique s’il faut inclure les en-têtes de requête dans le rapport. La valeur par défaut est `false`.
+ `includeResponseHeaders` : s’il faut inclure les en-têtes de réponse dans le rapport. La valeur par défaut est `false`.
+ `includeUrlPassword` : indique s’il faut inclure un mot de passe présent dans l’URL. Par défaut, les mots de passe qui apparaissent dans URLs les journaux et les rapports sont supprimés afin d'empêcher la divulgation de données sensibles. La valeur par défaut est `false`.
+ `includeRequestBody` : indique s’il faut inclure le corps de la requête dans le rapport. La valeur par défaut est `false`.
+ `includeResponseBody` : indique s’il faut inclure le corps de la réponse dans le rapport. La valeur par défaut est `false`.
+ `restrictedHeaders` : une liste d’en-têtes à ignorer lorsque les en-têtes sont inclus. Cela s'applique à la fois aux en-têtes de demande et de réponse. Par exemple, vous pouvez masquer vos identifiants en définissant `includeRequestHeaders` sur « true » et `restrictedHeaders` sur `['Authorization']`.
+ `restrictedUrlParameters` : une liste de chemins d’URL ou de paramètres de requête à masquer. Cela s'applique à URLs ceux qui apparaissent dans les journaux, les rapports et les erreurs. Le paramètre est sensible à la casse. Vous pouvez utiliser un astérisque (`*`) pour masquer toutes les valeurs des chemins et paramètres d’URL. La valeur par défaut est un tableau vide.
+ `har` : indique s’il faut générer une archive HTTP (fichier HAR). La valeur par défaut est `true`.
L’exemple suivant illustre un fichier de configuration de rapports.
```
"includeRequestHeaders": true,
"includeResponseHeaders": true,
"includeUrlPassword": false,
"includeRequestBody": true,
"includeResponseBody": true,
"restrictedHeaders": ['x-amz-security-token', 'Authorization'], // Value of these headers is redacted from logs and reports
"restrictedUrlParameters": ['Session', 'SigninToken'] // Values of these URL parameters are redacted from logs and reports
```
**Configurations d'enregistrement**
S'applique aux journaux générés par CloudWatch Synthetics. Contrôle la verbosité des journaux de requêtes et de réponses.
+ `logRequest` : indique s’il faut journaliser chaque requête dans les journaux du script Canary. Pour les scripts Canary d'interface utilisateur, cette option journalise chaque demande envoyée par le navigateur. La valeur par défaut est ` false`.
+ `logResponse` : indique s’il faut journaliser chaque réponse dans les journaux du script Canary. Pour les scripts Canary d'interface utilisateur, cette option journalise chaque réponse reçue par le navigateur. La valeur par défaut est ` false`.
+ `logRequestBody` : indique s’il faut journaliser le corps des requêtes en même temps que les requêtes dans les journaux du script Canary. Cette configuration s’applique uniquement si `logRequest` est défini sur « true ». La valeur par défaut est `false`.
+ `logResponseBody` : indique s’il faut journaliser le corps des réponses en même temps que les requêtes dans les journaux du script Canary. Cette configuration s’applique uniquement si `logResponse` est défini sur « true ». La valeur par défaut est `false`.
+ `logRequestHeaders` : indique s’il faut journaliser les en-têtes de requête avec les requêtes dans les journaux du script Canary. Cette configuration s’applique uniquement si ` logRequest` est défini sur « true ». La valeur par défaut est `false`.
+ `logResponseHeaders` : indique s’il faut journaliser les en-têtes de réponse avec les réponses dans les journaux du script Canary. Cette configuration s’applique uniquement si ` logResponse` est défini sur « true ». La valeur par défaut est `false`.
**Configurations des métriques HTTP**
Configurations pour les métriques liées au nombre de requêtes réseau avec différents codes d'état HTTP, émises par CloudWatch Synthetics pour ce canari.
+ `metric_2xx` : indique s’il faut émettre la métrique `2xx` (avec la dimension `CanaryName`) pour ce script Canary. La valeur par défaut est ` true`.
+ `metric_4xx` : indique s’il faut émettre la métrique `4xx` (avec la dimension `CanaryName`) pour ce script Canary. La valeur par défaut est ` true`.
+ `metric_5xx` : indique s’il faut émettre la métrique `5xx` (avec la dimension `CanaryName`) pour ce script Canary. La valeur par défaut est ` true`.
+ `failedRequestsMetric` : indique s’il faut émettre la métrique ` failedRequests` (avec la dimension `CanaryName`) pour ce script Canary. La valeur par défaut est `true`.
+ `aggregatedFailedRequestsMetric` : indique s’il faut émettre la métrique ` failedRequests` (sans la dimension `CanaryName`) pour ce script Canary. La valeur par défaut est `true`.
+ `aggregated2xxMetric` : indique s’il faut émettre la métrique `2xx` (sans la dimension `CanaryName`) pour ce script Canary. La valeur par défaut est `true`.
+ `aggregated4xxMetric` : indique s’il faut émettre la métrique `4xx` (sans la dimension `CanaryName`) pour ce script Canary. La valeur par défaut est `true`.
+ `aggregated5xxMetric` : indique s’il faut émettre la métrique `5xx` (sans la dimension `CanaryName`) pour ce script Canary. La valeur par défaut est `true`.
**Configurations des métriques du script Canary**
Configurations pour les autres métriques émises par CloudWatch Synthetics.
+ `failedCanaryMetric` : indique s’il faut émettre la métrique `Failed` (avec la dimension `CanaryName`) pour ce script Canary. La valeur par défaut est ` true`.
+ `aggregatedFailedCanaryMetric` : indique s’il faut émettre la métrique ` Failed` (sans la dimension `CanaryName`) pour ce script Canary. La valeur par défaut est `true`.
**Autres configurations**
+ `userAgent` : chaîne à ajouter à l’agent utilisateur. L'agent utilisateur est une chaîne qui est incluse dans l'en-tête de la demande et qui identifie votre navigateur auprès des sites Web que vous visitez lorsque vous utilisez le navigateur sans en-tête. CloudWatch Synthetics ajoute automatiquement. `CloudWatchSynthetics/{{canary-arn}} to the user agent` La configuration spécifiée est ajoutée à l’agent utilisateur généré. Par défaut, la valeur ajoutée à l’agent est une chaîne vide (`""`).
### CloudWatch Variables d'environnement Synthetics
Configurez le niveau de journalisation et le format des journaux à l’aide de variables d’environnement.
**Format du journal**
Le runtime CloudWatch Synthetics Playwright CloudWatch crée des journaux pour chaque course de Canary. Les journaux sont écrits au format JSON pour faciliter les requêtes. Vous pouvez éventuellement modifier le format du journal en `TEXT`.
+ `Environment variable name` : CW\_SYNTHETICS\_LOG\_FORMAT
+ `Supported values` : JSON, TEXT
+ `Default` : JSON
**Niveaux de journalisation**
Bien que l’activation du mode `Debug` augmente la quantité de détails enregistrés, cela peut s’avérer utile pour la résolution des problèmes.
+ `Environment variable name` : CW\_SYNTHETICS\_LOG\_LEVEL
+ `Supported values` : TRACE, DEBUG, INFO, WARN, ERROR, FATAL
+ `Default` : INFO