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 bibliothèque CloudWatch Synthetics pour Node.js suivantes sont utiles pour tous les scripts Canary.

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 l'ARN du script canary.

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);

Classe SyntheticsConfiguration

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

Vous pouvez utiliser la classe SyntheticsConfiguration pour configurer le comportement des fonctions de 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 les configurations CloudWatch Synthetics au niveau global afin de les appliquer à toutes les étapes des scripts Canary. Il est également possible de remplacer ces configurations au niveau d’une étape en passant des paires clé-valeur de configuration.

Vous pouvez transmettre des options au niveau de l'étape. Pour obtenir des exemples, veuillez consulter async executeStep(stepName, functionToExecute, [stepConfig]); et executeHttpStep(stepName, requestOptions, [callback], [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 scripts Canary

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

setConfig(options) concernant les métriques CloudWatch

Pour les scripts Canary utilisant syn-nodejs-puppeteer-3.1 ou version ultérieure, les (options) pour setConfig peuvent inclure les paramètres booléens suivants qui déterminent les métriques publiées par le script Canary. 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

disableAggregatedRequestMetrics()

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.

enableAggregatedRequestMetrics()

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.

get2xxMetric()

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

get4xxMetric()

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

get5xxMetric()

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

getAggregated2xxMetric()

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

getAggregated4xxMetric()

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.

getAggregated5xxMetric()

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

getFailedCanaryMetric()

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

getFailedRequestsMetric()

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

getStepDurationMetric()

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

getStepSuccessMetric()

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

with2xxMetric(_2xxMetric)

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

with4xxMetric(_4xxMetric)

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

with5xxMetric(_5xxMetric)

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

withAggregated2xxMetric(aggregated2xxMetric)

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

withAggregated4xxMetric(aggregated4xxMetric)

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

withAggregated5xxMetric(aggregated5xxMetric)

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

withAggregatedFailedCanaryMetric(aggregatedFailedCanaryMetric)

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

withAggregatedFailedRequestsMetric(aggregatedFailedRequestsMetric)

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

withFailedCanaryMetric(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.

withFailedRequestsMetric(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.

withStepDurationMetric(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.

withStepSuccessMetric(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 spécifie s'il faut créer un fichier HAR pour ce script Canary.

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.

withIncludeUrlPassword()

Accepte un argument booléen qui spécifie s'il faut inclure dans les journaux et les rapports les mots de passe qui apparaissent dans les URL.

withRestrictedUrlParameters()

Accepte un tableau des paramètres de chemin d'URL ou de requête à effacer. Cette option s'applique aux URL apparaissant dans les journaux, les rapports et les erreurs. Vous pouvez utiliser un astérisque (*) en tant que valeur pour effacer toutes les valeurs de paramètre de chemin d'URL et 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.

withLogRequestBody()

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

withLogResponseBody()

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

withLogRequestHeaders()

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

withLogResponseHeaders()

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()

Renvoie une valeur indiquant si le script Canary crée un fichier HAR.

getStepsReport()

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

getIncludeUrlPassword()

Renvoie une valeur indiquant si le script Canary inclut dans les journaux et les rapports les mots de passe qui apparaissent dans les URL.

getRestrictedUrlParameters()

Renvoie une valeur indiquant si le script Canary supprime les paramètres de chemin d'URL ou 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.

getLogRequestBody()

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

getLogResponseBody()

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

getLogRequestHeaders()

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

getLogResponseHeaders()

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 scripts Canary d'interface utilisateur

Pour les scripts Canary d'interface utilisateur, setConfig peut 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 (screenshotOnStepStart, screenshotOnStepSuccess et screenshotOnStepFailure).

enableStepScreenshots()

Active toutes les options de capture d'écran (screenshotOnStepStart, screenshotOnStepSuccess et screenshotOnStepFailure). 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(screenshotOnStepStart)

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

withScreenshotOnStepSuccess(screenshotOnStepSuccess)

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

withScreenshotOnStepFailure(screenshotOnStepFailure)

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();

Ensuite, définissez la configuration de chaque option en appelant la méthode setConfig à 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 fonction disableStepScreenshots() comme indiqué dans l’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 les scripts Canary d'API

Pour les scripts Canary d'API, setConfig peut 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 scripts Canary exécutant syn-marionnettier-node-3.2 et version ultérieure. 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 Classe SyntheticsConfiguration.

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 du script Canary, vous pouvez utiliser la console CloudWatch pour modifier le script Canary afin d'effectuer l'une des opérations suivantes :

Pour plus d'informations sur l'utilisation de la console CloudWatch pour modifier un script Canary, consultez Modification 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 journaux dans la console et dans un fichier journal local au même niveau de journalisation. 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 dans le fichier journal local sont précédées de « DEBUG: », « INFO: », etc., pour respecter le niveau de journalisation de la fonction appelée.

Vous pouvez utiliser SyntheticsLogger, en supposant que vous souhaitez exécuter la bibliothèque Synthetics au même niveau de journalisation que celui de vos scripts Canary Synthetics.

L'utilisation de SyntheticsLogger n'est pas nécessaire pour créer un fichier journal qui est chargé vers votre emplacement de résultats dans 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 à consigner. ex est l'exception, le cas échéant, à consigner.

Exemple :

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

log.error(message, ex);

Paramètres : message est le message à consigner. ex est l'exception, le cas échéant, à consigner.

Exemple :

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

log.info(message, ex);

Paramètres : message est le message à consigner. ex est l'exception, le cas échéant, à consigner.

Exemple :

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

log.log(message, ex);

Ceci est un alias pour log.info.

Paramètres : message est le message à consigner. ex est l'exception, le cas échéant, à consigner.

Exemple :

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

log.warn(message, ex);

Paramètres : message est le message à consigner. ex est l'exception, le cas échéant, à consigner.

Exemple :

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

Classe SyntheticsLogHelper

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

getSanitizedUrl(url, stepConfig = null)

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 d'effacer les paramètres d'URL sensibles tels que les mots de passe et access_token en définissant la propriété restrictedUrlParameters. Par défaut, les mots de passe dans les URL sont effacés. Vous pouvez activer les mots de passe d'URL si nécessaire en définissant includeUrlPassword sur true (vrai).

Cette fonction lève une erreur si l'URL transmise n'est pas une URL valide.

Paramètres

Exemple :

Cet exemple utilise l'exemple d'URL suivant : 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'];
});
// Import SyntheticsLogHelper dependency
const syntheticsLogHelper = require('SyntheticsLogHelper');

const sanitizedUrl = syntheticsLogHelper.getSanitizedUrl('URL');



const urlConfig = {
   restrictedUrlParameters = ['*']
};
const sanitizedUrl = syntheticsLogHelper.getSanitizedUrl('URL', urlConfig);
logger.info('My example url is: ' + sanitizedUrl);
              

Ensuite, nettoyez et journalisez l'URL

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

const sanitizedUrl = syntheticsLogHelper.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 d'une URL en transmettant un paramètre facultatif contenant des options de configuration Synthetics, comme dans l'exemple suivant.

const urlConfig = {
   restrictedUrlParameters = ['*']
};
const sanitizedUrl = syntheticsLogHelper.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

getSanitizedErrorMessage

Cette fonction est disponible dans syn-nodejs-puppeteer-3.2 et versions ultérieures. Elle renvoie des chaînes d'erreur nettoyées en nettoyant toutes les URL présentes en fonction de la configuration 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 = syntheticsLogHelper.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(headers, 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 propriété restrictedHeaders sont effacés des journaux, des fichiers HAR 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 pour Node.js suivantes sont utiles uniquement pour les scripts Canary d'interface utilisateur.

Classe Synthetics

Les fonctions suivantes sont dans la classe Synthetics.

async addUserAgent(page, userAgentString);

Cette fonction ajoute userAgentString à l'en-tête d'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

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

Exécute l'étape fournie, en l'enveloppant avec la journalisation start/pass/fail, les captures d'écran start/pass/fail et les métriques de durée et pass/fail.

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 [RÉUSSITE/ÉCHEC]), le motif de l'échec (en cas d'échec) et les captures d'écran prises 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

À partir de syn-nodejs-2.2, vous pouvez éventuellement transmettre 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 Classe SyntheticsConfiguration.

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);

getDefaultLaunchOptions();

La fonction getDefaultLaunchOptions() 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();

getPage();

Retourne la page ouverte actuelle en tant qu'objet Puppeteer. Pour de plus amples informations, reportez-vous à l'API Puppeteer v1.14.0.

Exemple :

let page = await synthetics.getPage();

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 Type d’options de lancement.

Si vous appelez cette fonction sans options, Synthetics lance un navigateur avec des arguments par défaut, executablePath et defaultViewport. Les dimensions de la fenêtre d'affichage par défaut dans CloudWatch Synthetics sont de 1 920 par 1 080.

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 paramètre ignoreHTTPSErrors aux paramètres de lancement CloudWatch Synthetics :

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

Vous pouvez désactiver la sécurité web en ajoutant un indicateur --disable-web-security 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
  });

Classe RequestResponseLogHelper

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(name, suffix);

Effectue une capture d'écran (.PNG) de la page actuelle avec un nom et un 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.

Les scripts canary CloudWatch Synthetics prennent automatiquement des captures d'écran avant de commencer une étape (la fonction executeStep) et après la fin de l'étape (sauf si vous configurez le script canary 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')

Classe BrokenLinkCheckerReport

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.

getTotalBrokenLinks()

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

getTotalLinksChecked()

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

Utilisation de 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.

Classe SyntheticsLink

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)

url est une chaîne d'URL. 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)

parentUrl est une chaîne représentant l'URL parent (page source). 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 bibliothèque Node.js qui s'appliquent uniquement aux scripts Canary d'API

Les fonctions de bibliothèque CloudWatch Synthetics pour Node.js suivantes sont utiles uniquement pour les scripts Canary d'API.

executeHttpStep(stepName, requestOptions, [callback], [stepConfig])

Exécute la requête HTTP fournie en tant qu'étape et publie les métriques SuccessPercent (réussite/échec) et Duration.

executeHttpStep utilise en coulisses des fonctions natives HTTP ou HTTPS en fonction du protocole spécifié dans la requête.

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 requête HTTP, tels que les suivants :

Paramètres

stepName(chaîne)

Spécifie le nom de l'étape. Ce nom est également utilisé pour publier des métriques CloudWatch pour cette étape.

requestOptions(objet ou chaîne)

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

En plus de ces options Node.js, requestOptions prend en charge le paramètre supplémentaire body. Vous pouvez utiliser le paramètre body pour transmettre des données en tant que corps de requête.

callback(réponse)

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

stepConfig(objet)

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

Exemples d'utilisation de l'option 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 une 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 callback, CloudWatch Synthetics valide 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 CloudWatch Synthetics globale. 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
};

Cet exemple final transmet votre requête à executeHttpStep et nomme l'étape.

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

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

Vous verrez les métriques successPercent et duration pour l'étape Verify GET products API. Vous pouvez contrôler les performances de vos API en contrôlant les métriques des étapes d'appel de vos API.

Pour obtenir un exemple de script complet qui utilise ces fonctions, consultez Script Canary d'API à plusieurs étapes.