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.

Fonctions de bibliothèque disponibles pour les scripts Canary Node.js utilisant Puppeteer

Cette section décrit les fonctions de bibliothèque disponibles pour les scripts Canary Node.js.

Classes et fonctions de bibliothèque Node.js qui s'appliquent à tous les scripts Canary

Les fonctions de la bibliothèque CloudWatch Synthetics suivantes pour Node.js sont utiles pour tous les canaris.

Classe Synthetics

Les fonctions suivantes pour tous les scripts Canary sont dans la classe Synthetics.

addExecutionError(errorMessage, ex) ;

errorMessage décrit l'erreur et ex est l'exception rencontrée.

Vous pouvez utiliser addExecutionError pour définir les erreurs d'exécution pour votre script Canary. Ce code fait échouer le script Canary sans interrompre l'exécution du script. Cela n'a pas non plus d'impact sur vos métriques successPercent.

Vous ne devriez suivre les erreurs comme des erreurs d'exécution que si elles ne sont pas importantes pour indiquer le succès ou l'échec de votre script Canary.

L'exemple suivant illustre l'utilisation de addExecutionError. Vous surveillez la disponibilité de votre point de terminaison et vous prenez des captures d'écran après le chargement de la page. Étant donné que l'échec de la prise d'une capture d'écran ne détermine pas la disponibilité du point de terminaison, vous pouvez détecter toutes les erreurs rencontrées lors de la prise de captures d'écran et les ajouter en tant qu'erreurs d'exécution. Vos métriques de disponibilité indiqueront toujours que le point de terminaison est opérationnel, mais le statut de votre script Canary indiquera qu'il a échoué. L'exemple de bloc de code suivant détecte une telle erreur et l'ajoute en tant qu'erreur d'exécution.

try {
    await synthetics.takeScreenshot(stepName, "loaded");
} catch(ex) {
    synthetics.addExecutionError('Unable to take screenshot ', ex);
}

getCanaryName();

Renvoie le nom du script Canary.

getCanaryArn();

Renvoie le ARN nom du canari.

getCanaryUserAgentString();

Renvoie l'agent utilisateur personnalisé du script canary.

getRuntimeVersion();

Cette fonction est disponible dans la version d'exécution syn-nodejs-puppeteer-3.0 et versions ultérieures. Elle renvoie la version d'exécution Synthetics du script Canary. Par exemple, la valeur renvoyée peut être syn-nodejs-puppeteer-3.0.

getLogLevel();

Récupère le niveau de journalisation actuel pour la bibliothèque Synthetics. Les valeurs possibles sont les suivantes :

Exemple :

let logLevel = synthetics.getLogLevel();

setLogLevel();

Définit le niveau de journalisation pour la bibliothèque Synthetics. Les valeurs possibles sont les suivantes :

Exemple :

synthetics.setLogLevel(0);

SyntheticsConfiguration classe

Cette classe est disponible uniquement dans la version d'exécution syn-nodejs-2.1 ou version ultérieure.

Vous pouvez utiliser la SyntheticsConfiguration classe pour configurer le comportement des fonctions de la bibliothèque Synthetics. Par exemple, vous pouvez utiliser cette classe pour configurer la fonction executeStep() pour ne pas prendre de captures d'écran.

Vous pouvez définir CloudWatch des configurations Synthetics au niveau global, qui sont appliquées à toutes les étapes des canaris. Vous pouvez également remplacer ces configurations au niveau de l'étape en transmettant des paires de clés et de valeurs de configuration.

Vous pouvez transmettre des options au niveau de l'étape. Pour obtenir des exemples, veuillez consulter asynchrone executeStep (stepName, functionToExecute, [stepConfig]) ; et executeHttpStep(stepNamerequestOptions, [rappel], [stepConfig])

setConfig(options)

options est un objet, qui est un ensemble d'options configurables pour votre script Canary. Les sections suivantes expliquent les champs possibles dans options.

setConfig(options) pour tous les canaris

Pour les canaris utilisant syn-nodejs-puppeteer-3.2 ou version ultérieure, les (options) pour setConfigpeuvent inclure les paramètres suivants :

setConfig(options) concernant les CloudWatch métriques

Pour les canaris utilisant syn-nodejs-puppeteer-3.1 ou version ultérieure, les (options) pour setConfigpeuvent inclure les paramètres booléens suivants qui déterminent les métriques publiées par le canari. La valeur par défaut de chacune de ces options est true. Les options qui commencent par aggregated déterminent si la métrique est émise sans la dimension CanaryName. Vous pouvez utiliser ces métriques pour afficher les résultats agrégés de tous vos scripts Canary. Les autres options déterminent si la métrique est émise avec la dimension CanaryName. Vous pouvez utiliser ces métriques pour afficher les résultats de chaque script Canary individuel.

Méthodes pour activer ou désactiver les métriques

disableAggregatedRequestMétriques ()

Désactive l'émission par le script Canary de toutes les métriques de demande émises sans dimension CanaryName.

disableRequestMetrics()

Désactive toutes les métriques de demande, y compris les métriques par script Canary et les métriques agrégées pour tous les scripts Canary.

disableStepMetrics()

Désactive toutes les métriques d'étapes, y compris les métriques de succès des étapes et les métriques de durée des étapes.

enableAggregatedRequestMétriques ()

Active l'émission par le script Canary de toutes les métriques de demande émises sans dimension CanaryName.

enableRequestMetrics()

Active toutes les métriques de demande, y compris les métriques par script Canary et les métriques agrégées pour tous les scripts Canary.

enableStepMetrics()

Active toutes les métriques d'étapes, y compris les métriques de succès des étapes et les métriques de durée des étapes.

obtenir 2 xxMetric ()

Renvoie une valeur indiquant si le script Canary émet une métrique 2xx avec la dimension CanaryName.

obtenir 4 xxMetric ()

Renvoie une valeur indiquant si le script Canary émet une métrique 4xx avec la dimension CanaryName.

obtenir 5 xxMetric ()

Renvoie une valeur indiquant si le script Canary émet une métrique 5xx avec la dimension CanaryName.

getAggregatedxxMetric(2)

Renvoie une valeur indiquant si le script Canary émet une métrique 2xx sans dimension.

getAggregatedxxMetric(4)

Renvoie une valeur indiquant si le script Canary émet une métrique 4xx sans dimension.

getAggregatedFailedCanaryMetric()

Renvoie une valeur indiquant si le script Canary émet une métrique Failed sans dimension.

getAggregatedFailedRequestsMetric()

Renvoie une valeur indiquant si le script Canary émet une métrique Failed requests sans dimension.

getAggregatedxxMetric(5)

Renvoie une valeur indiquant si le script Canary émet une métrique 5xx sans dimension.

getFailedCanaryMétrique ()

Renvoie une valeur indiquant si le script Canary émet une métrique Failed avec la dimension CanaryName.

getFailedRequestsMétrique ()

Renvoie une valeur indiquant si le script Canary émet une métrique Failed requests avec la dimension CanaryName.

getStepDurationMétrique ()

Renvoie une valeur indiquant si le script Canary émet une métrique Duration avec la dimension CanaryName pour ce script Canary.

getStepSuccessMétrique ()

Renvoie une valeur indiquant si le script Canary émet une métrique StepSuccess avec la dimension CanaryName pour ce script Canary.

avec 2 xxMetric (xxMetric_2)

Accepte un argument booléen qui spécifie s'il faut émettre une métrique 2xx avec la dimension CanaryName pour ce script Canary.

avec 4 xxMetric (xxMetric_4)

Accepte un argument booléen qui spécifie s'il faut émettre une métrique 4xx avec la dimension CanaryName pour ce script Canary.

avec 5 xxMetric (xxMetric_5)

Accepte un argument booléen qui spécifie s'il faut émettre une métrique 5xx avec la dimension CanaryName pour ce script Canary.

withAggregated2 xxMetric (total de 2) xxMetric

Accepte un argument booléen qui spécifie s'il faut émettre une métrique 2xx sans dimension pour ce script Canary.

withAggregated4 xxMetric (total de 4) xxMetric

Accepte un argument booléen qui spécifie s'il faut émettre une métrique 4xx sans dimension pour ce script Canary.

withAggregated5 xxMetric (5 au totalxxMetric)

Accepte un argument booléen qui spécifie s'il faut émettre une métrique 5xx sans dimension pour ce script Canary.

withAggregatedFailedCanaryMetric(aggregatedFailedCanaryMétrique)

Accepte un argument booléen qui spécifie s'il faut émettre une métrique Failed sans dimension pour ce script Canary.

withAggregatedFailedRequestsMetric(aggregatedFailedRequestsMétrique)

Accepte un argument booléen qui spécifie s'il faut émettre une métrique Failed requests sans dimension pour ce script Canary.

withFailedCanaryMétrique (failedCanaryMetric)

Accepte un argument booléen qui spécifie s'il faut émettre une métrique Failed avec la dimension CanaryName pour ce script Canary.

withFailedRequestsMétrique (failedRequestsMetric)

Accepte un argument booléen qui spécifie s'il faut émettre une métrique Failed requests avec la dimension CanaryName pour ce script Canary.

withStepDurationMétrique (stepDurationMetric)

Accepte un argument booléen qui spécifie s'il faut émettre une métrique Duration avec la dimension CanaryName pour ce script Canary.

withStepSuccessMétrique (stepSuccessMetric)

Accepte un argument booléen qui spécifie s'il faut émettre une métrique StepSuccess avec la dimension CanaryName pour ce script Canary.

Méthodes pour activer ou désactiver d'autres fonctions

withHarFile()

Accepte un argument booléen, qui indique s'il faut créer un HAR fichier pour ce canari.

withStepsReport()

Accepte un argument booléen qui spécifie s'il faut créer un rapport avec un résumé de l'exécution des étapes pour ce script Canary.

withIncludeUrlMot de passe ()

Accepte un argument booléen, qui indique s'il faut inclure les mots de passe qui apparaissent URLs dans les journaux et les rapports.

withRestrictedUrlParamètres ()

Accepte un tableau de paramètres de URL chemin ou de requête à supprimer. Cela s'applique à URLs l'affichage dans les journaux, les rapports et les erreurs. Vous pouvez passer un astérisque (*) comme valeur pour supprimer toutes les valeurs de URL chemin et de paramètre de requête

withLogRequest()

Accepte un argument booléen qui spécifie si chaque demande doit être journalisée dans les journaux du script Canary.

withLogResponse()

Accepte un argument booléen qui spécifie si chaque réponse doit être journalisée dans les journaux du script Canary.

withLogRequestCorps ()

Accepte un argument booléen qui spécifie si chaque corps de requête doit être journalisé dans les journaux du script Canary.

withLogResponseCorps ()

Accepte un argument booléen qui spécifie si chaque corps de réponse doit être journalisé dans les journaux du script Canary.

withLogRequestEn-têtes ()

Accepte un argument booléen qui spécifie si chaque en-tête de demande doit être journalisé dans les journaux du script Canary.

withLogResponseEn-têtes ()

Accepte un argument booléen qui spécifie si chaque en-tête de réponse doit être journalisé dans les journaux du script Canary.

getHarFile()

Indique si le canari crée un HAR fichier.

getStepsReport()

Renvoie une valeur indiquant si le script Canary génère un rapport avec un résumé de l'exécution des étapes.

getIncludeUrlMot de passe ()

Indique si le canari inclut les mots de passe qui apparaissent URLs dans les journaux et les rapports.

getRestrictedUrlParamètres ()

Indique si le canari expédie le URL chemin ou les paramètres de requête.

getLogRequest()

Renvoie une valeur indiquant si le script Canary journalise chaque demande dans les journaux du script Canary.

getLogResponse()

Renvoie une valeur indiquant si le script Canary journalise chaque réponse dans les journaux du script Canary.

getLogRequestCorps ()

Renvoie une valeur indiquant si le script Canary journalise chaque corps de requête dans les journaux du script Canary.

getLogResponseCorps ()

Renvoie une valeur indiquant si le script Canary journalise chaque corps de réponse dans les journaux du script Canary.

getLogRequestEn-têtes ()

Renvoie une valeur indiquant si le script Canary journalise chaque en-tête de demande dans les journaux du script Canary.

getLogResponseEn-têtes ()

Renvoie une valeur indiquant si le script Canary journalise chaque en-tête de réponse dans les journaux du script Canary.

Fonctions pour tous les scripts canary

setConfig(options) pour les canaris de l'interface utilisateur

Pour les canaris de l'interface utilisateur, setConfigvous pouvez inclure les paramètres booléens suivants :

Méthodes pour activer ou désactiver les captures d'écran

disableStepScreenshots()

Désactive toutes les options de capture d'écran (screenshotOnStepdémarrage, screenshotOnStep réussite et screenshotOnStep échec).

enableStepScreenshots()

Active toutes les options de capture d'écran (screenshotOnStepdémarrage, screenshotOnStep réussite et screenshotOnStep échec). Par défaut, toutes ces méthodes sont activées.

getScreenshotOnStepFailure()

Renvoie une valeur indiquant si le script Canary prend une capture d'écran après l'échec d'une étape.

getScreenshotOnStepStart()

Renvoie une valeur indiquant si le script Canary prend une capture d'écran avant de commencer une étape.

getScreenshotOnStepSuccess()

Renvoie une valeur indiquant si le script Canary prend une capture d'écran après la réussite d'une étape.

withScreenshotOnStepStart(screenshotOnStepDémarrer)

Accepte un argument booléen qui indique s'il faut prendre une capture d'écran avant de commencer une étape.

withScreenshotOnStepSuccess(screenshotOnStepSuccès)

Accepte un argument booléen qui indique s'il faut prendre une capture d'écran après la réussite d'une étape.

withScreenshotOnStepFailure(screenshotOnStepÉchec)

Accepte un argument booléen qui indique s'il faut prendre une capture d'écran après l'échec d'une étape.

Utilisation dans les scripts canary d'interface utilisateur

Tout d'abord, importez la dépendance Synthetics et récupérez la configuration.

// Import Synthetics dependency
const synthetics = require('Synthetics');

// Get Synthetics configuration
const synConfig = synthetics.getConfiguration();

Définissez ensuite la configuration de chaque option en appelant la setConfig méthode à l'aide de l'une des options suivantes.

// Set configuration values
    synConfig.setConfig({
        screenshotOnStepStart: true, 
        screenshotOnStepSuccess: false,
        screenshotOnStepFailure: false
    });

Ou

synConfig.withScreenshotOnStepStart(false).withScreenshotOnStepSuccess(true).withScreenshotOnStepFailure(true)

Pour désactiver toutes les captures d'écran, utilisez la disableStepScreenshots() fonction décrite dans cet exemple.

synConfig.disableStepScreenshots();

Vous pouvez activer et désactiver des captures d'écran à tout moment dans le code. Par exemple, pour désactiver les captures d'écran pour une seule étape, désactivez-les avant d'exécuter cette étape, puis activez-les après l'étape.

setConfig(options) pour API canaris

Pour les API canaris, setConfigvous pouvez inclure les paramètres booléens suivants :

Surveillance visuelle

La surveillance visuelle compare les captures d'écran prises lors de l'exécution d'un script Canary aux captures d'écran prises lors de l'exécution d'un script Canary de référence. Si l'écart entre les deux captures d'écran dépasse un pourcentage de seuil, le script Canary échoue et les zones présentant des différences sont mises en évidence en couleur dans le rapport d'exécution du script Canary. La surveillance visuelle est prise en charge dans les canaris utilisant syn-puppeteer-node-3.2 et versions ultérieures. Elle n'est actuellement pas prise en charge dans les scripts Canary exécutant Python et Selenium.

Pour activer la surveillance visuelle, ajoutez la ligne de code suivante au script Canary. Pour en savoir plus, consultez SyntheticsConfiguration classe.

syntheticsConfiguration.withVisualCompareWithBaseRun(true);

La première fois que le script Canary s'exécute avec succès après l'ajout de cette ligne au script, il utilise les captures d'écran prises au cours de cette exécution comme référence pour les comparaisons. Après cette première exécution de Canary, vous pouvez utiliser la CloudWatch console pour modifier le Canary afin d'effectuer l'une des opérations suivantes :

Pour plus d'informations sur l'utilisation de la CloudWatch console pour modifier un canari, consultezModification ou suppression d'un canary.

Autres options pour la surveillance visuelle

syntheticsConfiguration.withVisualVarianceThresholdPercentage(desiredPercentage)

Définissez le pourcentage d'écart acceptable entre les captures d'écran lors des comparaisons visuelles.

syntheticsConfiguration. withVisualVarianceHighlightHexColor(» #fafa00 «)

Définissez la couleur de surbrillance qui désigne les zones d'écart lorsque vous consultez les rapports d'exécution des scripts Canary qui utilisent la surveillance visuelle.

syntheticsConfiguration.withFailCanaryRunOnVisualVariance(failCanary)

Définissez si le script Canary échoue ou non lorsqu'il y a une différence visuelle supérieure au seuil. La valeur par défaut est de faire échouer le script Canary.

Enregistreur Synthetics

SyntheticsLogger écrit les déconnexions à la fois dans la console et dans un fichier journal local au même niveau de journal. Ce fichier journal est écrit dans les deux emplacements seulement si le niveau de journalisation est égal ou inférieur au niveau de journalisation souhaité de la fonction de journalisation qui a été appelée.

Les instructions de journalisation du fichier journal local sont précédées de « DEBUG : », « INFO : », etc. pour correspondre au niveau de journalisation de la fonction appelée.

Vous pouvez utiliser le SyntheticsLogger, en supposant que vous souhaitiez exécuter la bibliothèque Synthetics au même niveau de journalisation que votre journalisation Synthetics Canary.

SyntheticsLogger Il n'est pas nécessaire d'utiliser le pour créer un fichier journal qui est téléchargé vers votre emplacement de résultats S3. Vous pouvez créer à la place un autre fichier journal dans le dossier /tmp. Tous les fichiers créés sous le dossier /tmp sont chargés vers l'emplacement des résultats dans S3 en tant qu'artefacts.

Pour utiliser l'enregistreur de la bibliothèque Synthetics :

const log = require('SyntheticsLogger');

Définitions de fonctions utiles :

log.debug (,) ; message ex

Paramètres : message est le message à enregistrer. exest l'exception, le cas échéant, à la journalisation.

Exemple :

log.debug("Starting step - login.");

log.error (message,) ; ex

Paramètres : message est le message à enregistrer. exest l'exception, le cas échéant, à la journalisation.

Exemple :

try {
  await login();
catch (ex) {
  log.error("Error encountered in step - login.", ex);
}

log.info (message,ex) ;

Paramètres : message est le message à enregistrer. exest l'exception, le cas échéant, à la journalisation.

Exemple :

log.info("Successfully completed step - login.");

log.log (message,ex) ;

Ceci est un alias pour log.info.

Paramètres : message est le message à enregistrer. exest l'exception, le cas échéant, à la journalisation.

Exemple :

 log.log("Successfully completed step - login.");

log.warn (message,) ; ex

Paramètres : message est le message à enregistrer. exest l'exception, le cas échéant, à la journalisation.

Exemple :

log.warn("Exception encountered trying to publish CloudWatch Metric.", ex);

SyntheticsLogHelper classe

La classe SyntheticsLogHelper est disponible dans l'exécution syn-nodejs-puppeteer-3.2 et versions ultérieures. Il est déjà initialisé dans la bibliothèque CloudWatch Synthetics et est configuré avec la configuration Synthetics. Vous pouvez l'ajouter en tant que dépendance dans votre script. Cette classe vous permet de nettoyer les en-têtes et URLs les messages d'erreur afin de supprimer des informations sensibles.

getSanitizedUrl(url, stepConfig = nul)

Cette fonction est disponible dans syn-nodejs-puppeteer-3.2 et versions ultérieures. Elle renvoie des chaînes d'URL nettoyées en fonction de la configuration. Vous pouvez choisir de supprimer les URL paramètres sensibles tels que le mot de passe et le jeton d'accès en définissant la propriété. restrictedUrlParameters Par défaut, les mots de passe saisis URLs sont expurgés. Vous pouvez activer les URL mots de passe si nécessaire en les includeUrlPassword réglant sur true.

Cette fonction génère une erreur si le message URL transmis n'est pas valideURL.

Paramètres

Exemple :

Cet exemple utilise l'exemple suivant URL :https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200. Dans cet exemple, access_token contient vos informations sensibles qui ne doivent pas être journalisées. Notez que les services Synthetics ne stockent pas d'artefacts d'exécution de script Canary. Les artefacts tels que les journaux, les captures d'écran et les rapports sont tous stockés dans un compartiment Amazon S3 sur votre compte client.

La première étape consiste à définir la configuration Synthetics.

// Import Synthetics dependency
const synthetics = require('Synthetics');

// Import Synthetics logger for logging url
const log = require('SyntheticsLogger');

// Get Synthetics configuration
const synConfig = synthetics.getConfiguration();

// Set restricted parameters
synConfig.setConfig({
   restrictedUrlParameters: ['access_token'];
});

Ensuite, désinfectez et enregistrez le URL

// Import SyntheticsLogHelper dependency
const syntheticsLogHelper = require('SyntheticsLogHelper');

const sanitizedUrl = synthetics.getSanitizedUrl('https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200');

Ceci journalise ce qui suit dans votre journal de script Canary.

My example url is: https://example.com/learn/home?access_token=REDACTED&token_type=Bearer&expires_in=1200

Vous pouvez remplacer la configuration Synthetics pour URL un en transmettant un paramètre facultatif contenant les options de configuration Synthetics, comme dans l'exemple suivant.

const urlConfig = {
   restrictedUrlParameters = ['*']
};
const sanitizedUrl = synthetics.getSanitizedUrl('https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200', urlConfig);
logger.info('My example url is: ' + sanitizedUrl);

L'exemple précédent efface tous les paramètres de requête et est journalisé comme suit :

My example url is: https://example.com/learn/home?access_token=REDACTED&token_type=REDACTED&expires_in=REDACTED

getSanitizedErrorUn message

Cette fonction est disponible dans syn-nodejs-puppeteer-3.2 et versions ultérieures. Il renvoie des chaînes d'erreur nettoyées en nettoyant tous les URLs présents en fonction de la configuration de Synthetics. Vous pouvez choisir de remplacer la configuration Synthetics globale lorsque vous appelez cette fonction en transmettant un paramètre stepConfig facultatif.

Paramètres

Exemple :

Cet exemple utilise l'erreur suivante : Failed to load url: https://example.com/learn/home?access_token=12345&token_type=Bearer&expires_in=1200

La première étape consiste à définir la configuration Synthetics.

// Import Synthetics dependency
const synthetics = require('Synthetics');

// Import Synthetics logger for logging url
const log = require('SyntheticsLogger');

// Get Synthetics configuration
const synConfig = synthetics.getConfiguration();

// Set restricted parameters
synConfig.setConfig({
   restrictedUrlParameters: ['access_token'];
});

Ensuite, nettoyez et journalisez le message d'erreur

// Import SyntheticsLogHelper dependency
const syntheticsLogHelper = require('SyntheticsLogHelper');

try {
   // Your code which can throw an error containing url which your script logs
} catch (error) {
    const sanitizedErrorMessage = synthetics.getSanitizedErrorMessage(errorMessage);
    logger.info(sanitizedErrorMessage);
}

Ceci journalise ce qui suit dans votre journal de script Canary.

Failed to load url: https://example.com/learn/home?access_token=REDACTED&token_type=Bearer&expires_in=1200

getSanitizedHeaders(en-têtes, stepConfig =null)

Cette fonction est disponible dans syn-nodejs-puppeteer-3.2 et versions ultérieures. Elle renvoie les en-têtes nettoyés en fonction de la propriété restrictedHeaders de syntheticsConfiguration. Les en-têtes spécifiés dans la restrictedHeaders propriété sont supprimés des journaux, des HAR fichiers et des rapports.

Paramètres

Classes et fonctions de bibliothèque Node.js qui s'appliquent uniquement aux scripts Canary d'interface utilisateur

Les fonctions de bibliothèque CloudWatch Synthetics suivantes pour Node.js ne sont utiles que pour les canaris de l'interface utilisateur.

Classe Synthetics

Les fonctions suivantes sont dans la classe Synthetics.

asynchrone addUserAgent (page, userAgentString) ;

Cette fonction s'ajoute userAgentString à l'en-tête de l'agent utilisateur de la page spécifiée.

Exemple :

await synthetics.addUserAgent(page, "MyApp-1.0");

Il en résulte que l'en-tête d'agent utilisateur de la page est défini sur browsers-user-agent-header-valueMyApp-1.0

asynchrone executeStep (stepName, functionToExecute, [stepConfig]) ;

Exécute l'étape fournie, en l'enveloppant avec start/pass/fail logging, start/pass/fail screenshots, and pass/fail des métriques de durée.

La fonction executeStep effectue également les opérations suivantes :

Si le script Canary utilise l'exécution syn-nodejs-2.0 ou version ultérieure, cette fonction ajoute également un résumé de l'exécution des étapes au rapport du script Canary. Le résumé inclut des détails sur chaque étape, tels que l'heure de début, l'heure de fin, le statut (PASSED/FAILED), la raison de l'échec (en cas d'échec), ainsi que des captures d'écran capturées lors de l'exécution de chaque étape.

Exemple :

await synthetics.executeStep('navigateToUrl', async function (timeoutInMillis = 30000) {
           await page.goto(url, {waitUntil: ['load', 'networkidle0'], timeout: timeoutInMillis});});

Réponse :

Retourne ce que functionToExecute retourne.

Mises à jour avec syn-nodejs-2.2

En commençant parsyn-nodejs-2.2, vous pouvez éventuellement passer des configurations d'étape pour remplacer les configurations CloudWatch Synthetics au niveau de l'étape. Pour obtenir la liste des options que vous pouvez transmettre à executeStep, consultez SyntheticsConfiguration classe.

L'exemple suivant remplace la configuration par défaut false pour continueOnStepFailure par true et spécifie quand prendre des captures d'écran.

var stepConfig = {
    'continueOnStepFailure': true,
    'screenshotOnStepStart': false,
    'screenshotOnStepSuccess': true,
    'screenshotOnStepFailure': false
}

await executeStep('Navigate to amazon', async function (timeoutInMillis = 30000) {
      await page.goto(url, {waitUntil: ['load', 'networkidle0'], timeout: timeoutInMillis});
 }, stepConfig);

getDefaultLaunchDes options () ;

La getDefaultLaunchOptions() fonction renvoie les options de lancement du navigateur utilisées par CloudWatch Synthetics. Pour plus d'informations, voir Launch options type

// This function returns default launch options used by Synthetics.
const defaultOptions = await synthetics.getDefaultLaunchOptions();

newPage();

Retourne la page ouverte actuelle en tant qu'objet Puppeteer. Pour plus d'informations, consultez Puppeteer API v1.14.0.

Exemple :

let page = synthetics.newPage();

Réponse :

La page (objet Puppeteer) actuellement ouverte dans la session de navigateur en cours.

getRequestResponseLogHelper();

Utilisez cette fonction comme modèle de générateur pour ajuster les indicateurs de journalisation des demandes et des réponses.

Exemple :

synthetics.setRequestResponseLogHelper(getRequestResponseLogHelper().withLogRequestHeaders(false));;

Réponse :

{RequestResponseLogHelper}

launch(options)

Les options de cette fonction ne sont disponibles que dans l'exécution syn-nodejs-2.1 ou version ultérieure.

Cette fonction est utilisée uniquement pour les scripts Canary d'interface utilisateur. Elle ferme le navigateur existant et en lance un nouveau.

(options) est un ensemble configurable d'options à définir sur le navigateur. Pour plus d'informations, consultez Launch options type.

Si vous appelez cette fonction sans options, Synthetics lance un navigateur avec des arguments par défaut, executablePath et defaultViewport. La fenêtre d'affichage par défaut dans CloudWatch Synthetics est 1920 x 1080.

Vous pouvez remplacer les paramètres de lancement utilisés par CloudWatch Synthetics et transmettre des paramètres supplémentaires lors du lancement du navigateur. Par exemple, l'extrait de code suivant lance un navigateur avec des arguments par défaut et un chemin d'accès au fichier exécutable par défaut, mais avec une fenêtre d'affichage de 800 x 600.

await synthetics.launch({
        defaultViewport: { 
            "deviceScaleFactor": 1, 
            "width": 800,
            "height": 600 
    }});

L'exemple de code suivant ajoute un nouveau ignoreHTTPSErrors paramètre aux paramètres de lancement de CloudWatch Synthetics :

await synthetics.launch({
        ignoreHTTPSErrors: true
 });

Vous pouvez désactiver la sécurité Web en ajoutant un --disable-web-security indicateur aux arguments dans les paramètres de lancement de CloudWatch Synthetics :

// This function adds the --disable-web-security flag to the launch parameters
const defaultOptions = await synthetics.getDefaultLaunchOptions();
const launchArgs = [...defaultOptions.args, '--disable-web-security'];
await synthetics.launch({
     args: launchArgs
  });

RequestResponseLogHelper classe

Elle gère la configuration précise et la création de représentations chaînes des charges utiles de demandes et de réponses.

class RequestResponseLogHelper {
 
    constructor () {
        this.request = {url: true, resourceType: false, method: false, headers: false, postData: false};
        this.response = {status: true, statusText: true, url: true, remoteAddress: false, headers: false};
    }
 
    withLogRequestUrl(logRequestUrl);
    
    withLogRequestResourceType(logRequestResourceType);
    
    withLogRequestMethod(logRequestMethod);
    
    withLogRequestHeaders(logRequestHeaders);
    
    withLogRequestPostData(logRequestPostData);

        
    withLogResponseStatus(logResponseStatus);
    
    withLogResponseStatusText(logResponseStatusText);
   
    withLogResponseUrl(logResponseUrl);
 
    withLogResponseRemoteAddress(logResponseRemoteAddress);
    
    withLogResponseHeaders(logResponseHeaders);

Exemple :

synthetics.setRequestResponseLogHelper(getRequestResponseLogHelper()
.withLogRequestPostData(true)
.withLogRequestHeaders(true)
.withLogResponseHeaders(true));

Réponse :

{RequestResponseLogHelper}

setRequestResponseLogHelper();

Utilisez cette fonction comme modèle de générateur pour définir les indicateurs de journalisation de demandes et de réponses.

Exemple :

synthetics.setRequestResponseLogHelper().withLogRequestHeaders(true).withLogResponseHeaders(true);

Réponse :

{RequestResponseLogHelper}

async takeScreenshot (nom, suffixe) ;

Prend une capture d'écran (. PNG) de la page en cours avec le nom et le suffixe (facultatif).

Exemple :

await synthetics.takeScreenshot("navigateToUrl", "loaded")

Cet exemple effectue et télécharge une capture d'écran nommée 01-navigateToUrl-loaded.png dans le compartiment S3 du script Canary.

Vous pouvez prendre une capture d'écran pour une étape spécifique d'un script Canary en transmettant stepName en tant que premier paramètre. Les captures d'écran sont liées à l'étape du script Canary dans vos rapports afin de vous aider à suivre chaque étape lors du débogage.

CloudWatch Synthetics Canaries prend automatiquement des captures d'écran avant de commencer une étape (executeStepla fonction) et une fois l'étape terminée (sauf si vous configurez le canari pour désactiver les captures d'écran). Vous pouvez prendre plus de captures d'écran en transmettant le nom de l'étape dans la fonction takeScreenshot.

L'exemple suivant prend une capture d'écran avec signupForm comme valeur de la propriété stepName. La capture d'écran sera nommée 02-signupForm-address et sera liée à l'étape nommée signupForm dans le rapport du script Canary.

await synthetics.takeScreenshot('signupForm', 'address')

BrokenLinkCheckerReport classe

Cette classe fournit des méthodes pour ajouter un lien Synthetics. Elle n'est prise en charge que sur les scripts Canary qui utilisent la version syn-nodejs-2.0-beta ou ultérieure de l'exécution.

Pour utiliser BrokenLinkCheckerReport, incluez les lignes suivantes dans le script :

const BrokenLinkCheckerReport = require('BrokenLinkCheckerReport');
            
const brokenLinkCheckerReport = new BrokenLinkCheckerReport();

Définitions de fonctions utiles :

addLink(syntheticsLink, isBroken)

syntheticsLink est un objet SyntheticsLink représentant un lien. Cette fonction ajoute le lien en fonction du code de statut. Par défaut, elle considère qu'un lien est rompu si le code de statut n'est pas disponible ou s'il est 400 ou plus. Vous pouvez remplacer ce comportement par défaut en transmettant le paramètre facultatif isBrokenLink avec une valeur true ou false.

Cette fonction n'a pas de valeur de retour.

getLinks()

Cette fonction renvoie un tableau d'objets SyntheticsLink qui sont inclus dans le rapport du vérificateur de liens rompus.

getTotalBrokenLiens ()

Cette fonction renvoie un nombre représentant le nombre total de liens rompus.

getTotalLinksVérifié ()

Cette fonction renvoie un nombre représentant le nombre total de liens inclus dans le rapport.

Comment utiliser BrokenLinkCheckerReport

L'extrait de code de script Canary suivant illustre un exemple de navigation vers un lien et de l'ajout de celui-ci au rapport du vérificateur de liens rompus.

SyntheticsLink classe

Cette classe fournit des méthodes pour envelopper les informations. Elle n'est prise en charge que sur les scripts Canary qui utilisent la version syn-nodejs-2.0-beta ou ultérieure de l'exécution.

Pour utiliser SyntheticsLink, incluez les lignes suivantes dans le script :

const SyntheticsLink = require('SyntheticsLink');

const syntheticsLink = new SyntheticsLink("https://www.amazon.com");

Cette fonction retourne syntheticsLinkObject.

Définitions de fonctions utiles :

withUrl(url)

urlest une URL chaîne. Cette fonction retourne syntheticsLinkObject.

withText(text)

text est une chaîne représentant le texte d'ancrage. Cette fonction retourne syntheticsLinkObject. Elle ajoute le texte d'ancrage correspondant au lien.

withParentUrl(parentUrl)

parentUrlest une chaîne représentant le parent (page source)URL. Cette fonction retourne syntheticsLinkObject.

withStatusCode(statusCode)

statusCode est une chaîne représentant le code de statut. Cette fonction retourne syntheticsLinkObject.

withFailureReason(failureReason)

failureReason est une chaîne représentant la raison de l'échec. Cette fonction retourne syntheticsLinkObject.

addScreenshotResult(screenshotResult)

screenshotResult est un objet. Il s'agit d'une instance de ScreenshotResult qui a été retournée par la fonction Synthetics takeScreenshot. L'objet inclut les éléments suivants :

Classes et fonctions de la bibliothèque Node.js qui s'appliquent uniquement aux API canaris

Les fonctions de bibliothèque CloudWatch Synthetics suivantes pour Node.js ne sont utiles que pour les canaris. API

executeHttpStep(stepNamerequestOptions, [rappel], [stepConfig])

Exécute la HTTP demande fournie sous forme d'étape et publie SuccessPercent (réussite/échec) et les métriques. Duration

executeHttpSteputilise l'une HTTP ou l'autre des fonctions HTTPS natives sous le capot, selon le protocole spécifié dans la demande.

Cette fonction ajoute également un résumé de l'exécution des étapes au rapport du script Canary. Le résumé inclut des détails sur chaque HTTP demande, tels que les suivants :

Paramètres

stepName(String)

Spécifie le nom de l'étape. Ce nom est également utilisé pour publier CloudWatch les statistiques de cette étape.

requestOptions(Object or String)

La valeur de ce paramètre peut être uneURL, une URL chaîne ou un objet. S'il s'agit d'un objet, il doit s'agir d'un ensemble d'options configurables pour effectuer une HTTP demande. Il prend en charge toutes les options dans http.request(options[, callback]) dans la documentation de Node.js.

Outre ces options Node.js, requestOptionsprend en charge le paramètre supplémentairebody. Vous pouvez utiliser le paramètre body pour transmettre des données en tant que corps de requête.

rappel () response

(Facultatif) Il s'agit d'une fonction utilisateur qui est invoquée avec la HTTP réponse. La réponse est du type Class : http. IncomingMessage.

stepConfig(object)

(Facultatif) Utilisez ce paramètre pour remplacer les configurations Synthetics globales par une configuration différente pour cette étape.

Exemples d'utilisation executeHttpStep

Les exemples suivants s'inspirent les uns des autres pour illustrer les différentes utilisations de cette option.

Ce premier exemple configure les paramètres de requête. Vous pouvez transmettre un message URL en tant que requestOptions:

let requestOptions = 'https://www.amazon.com';

Vous pouvez également transmettre un ensemble d'options :

let requestOptions = {
        'hostname': 'myproductsEndpoint.com',
        'method': 'GET',
        'path': '/test/product/validProductName',
        'port': 443,
        'protocol': 'https:'
    };

L'exemple suivant crée une fonction de rappel qui accepte une réponse. Par défaut, si vous ne spécifiez pas de rappel, CloudWatch Synthetics vérifie que le statut est compris entre 200 et 299 inclus.

// Handle validation for positive scenario
    const callback = async function(res) {
        return new Promise((resolve, reject) => {
            if (res.statusCode < 200 || res.statusCode > 299) {
                throw res.statusCode + ' ' + res.statusMessage;
            }
     
            let responseBody = '';
            res.on('data', (d) => {
                responseBody += d;
            });
     
            res.on('end', () => {
                // Add validation on 'responseBody' here if required. For ex, your status code is 200 but data might be empty
                resolve();
            });
        });
    };

L'exemple suivant crée une configuration pour cette étape qui remplace la configuration globale de CloudWatch Synthetics. La configuration d'étape dans cet exemple autorise les en-têtes de requête, les en-têtes de réponse, le corps de requête (données de publication) et le corps de réponse dans votre rapport et restreint les valeurs d'en-tête 'X-Amz-Security-Token' et 'Authorization'. Par défaut, ces valeurs ne sont pas incluses dans le rapport pour des raisons de sécurité. Si vous choisissez de les inclure, les données sont stockées uniquement dans votre compartiment S3.

// By default headers, post data, and response body are not included in the report for security reasons. 
// Change the configuration at global level or add as step configuration for individual steps
let stepConfig = {
    includeRequestHeaders: true, 
    includeResponseHeaders: true,
    restrictedHeaders: ['X-Amz-Security-Token', 'Authorization'], // Restricted header values do not appear in report generated.
    includeRequestBody: true,
    includeResponseBody: true
};

Ce dernier exemple transmet votre demande à l'étape executeHttpStepet lui donne un nom.

await synthetics.executeHttpStep('Verify GET products API', requestOptions, callback, stepConfig);

À l'aide de cet ensemble d'exemples, CloudWatch Synthetics ajoute les détails de chaque étape de votre rapport et produit des métriques pour chaque étape en utilisant. stepName

Vous verrez les métriques successPercent et duration pour l'étape Verify GET products API. Vous pouvez surveiller vos API performances en surveillant les indicateurs relatifs aux étapes de vos API appels.

Pour obtenir un exemple de script complet qui utilise ces fonctions, consultez Canari en plusieurs étapes API.