Tests JavaScript

La solution CI Visibility n'est actuellement pas disponible pour le site que vous avez sélectionné ().

Compatibilité

Frameworks de test pris en charge :

  • Jest 24.8.0+
    • Seuls les environnements de test jsdom (dans le package jest-environment-jsdom) et node (dans le package jest-environment-node) peuvent être utilisés. Les environnements personnalisés, comme @jest-runner/electron/environment dans jest-electron-runner, ne sont pas pris en charge.
    • Seuls les testRunners jest-circus et jest-jasmine2 sont pris en charge.
    • Jest 28+ est uniquement pris en charge à partir de dd-trace>=2.7.0.
  • Mocha 5.2.0+
    • Mocha 9.0.0+ : [prise en charge partielle](#limites connues)
  • Cucumber-js 7.0.0+
  • Cypress 6.7.0+
    • À partir de dd-trace>=1.4.0

Prérequis

Installez l’Agent Datadog pour recueillir des données sur les tests.

Le mode sans Agent est disponible en version bêta. Pour le tester, suivez les instructions dédiées indiquées plus bas.

Installer le traceur JavaScript

Pour installer le traceur JavaScript, exécutez ce qui suit :

yarn add --dev dd-trace

Pour en savoir plus, consultez la section relative à l’installation du traceur JavaScript.

Instrumenter vos tests

  1. Configurez un testEnvironment personnalisé dans votre jest.config.js ou à l’emplacement où vous configurez jest :
module.exports = {
  // ...
  // Le chemin peut être modifié. Il fait référence au fichier ci-dessous.
  testEnvironment: '<rootDir>/testEnvironment.js',
  // ...
}
  1. Dans testEnvironment.js :

// Active uniquement l'instrumentation de tests sur l'environnement de CI
if (process.env.DD_ENV === 'ci') {
  require('dd-trace/ci/jest/env')
}
// L'option jest-environment-jsdom est également acceptée
module.exports = require('jest-environment-node')

Jest@28

Si vous utilisez jest@28 et jest-environment-node, suivez la documentation jest pour modifier votre environnement :


if (process.env.DD_ENV === 'ci') {
  require('dd-trace/ci/jest/env')
}

module.exports = require('jest-environment-node').default

Puisque jest-environment-jsdom n’est pas inclus avec jest@28, vous devez l’installer séparément. Les versions 28+ de jest sont uniquement prises en charge à partir de dd-trace>=2.7.0.

Remarque : à compter de la version 27 de Jest, jest-environment-node, jest-environment-jsdom, jest-jasmine2, et jest-circus sont fournis avec jest. Ils n'apparaissent donc normalement pas dans votre package.json. Si vous avez extrait une ou plusieurs de ces bibliothèques dans votre package.json, vérifiez que les versions installées correspondent à celles de jest.

Exécutez normalement vos tests, en spécifiant l’environnement concerné (par exemple, local pour des tests exécutés sur la machine d’un développeur, ou ci pour des tests exécutés sur un fournisseur de CI) dans la variable d’environnement DD_ENV. Exemple :

DD_ENV=ci DD_SERVICE=my-javascript-app npm test

Ajoutez --require dd-trace/ci/init à la commande d’exécution de vos tests mocha. Par exemple, dans votre package.json :

"scripts": {
  "test": "mocha --require dd-trace/ci/init"
},

Exécutez normalement vos tests, en spécifiant l’environnement concerné (par exemple, local pour des tests exécutés sur la machine d’un développeur, ou ci pour des tests exécutés sur un fournisseur de CI) dans la variable d’environnement DD_ENV. Exemple :

DD_ENV=ci DD_SERVICE=my-javascript-app npm test

Ajoutez --require-module dd-trace/ci/init à l’emplacement où vous exécutez normalement vos tests cucumber-js. Par exemple, dans votre package.json :

package.json

"scripts": {
  "test": "cucumber-js --require-module=dd-trace/ci/init"
},

Exécutez normalement vos tests, en spécifiant l’environnement concerné (par exemple, local pour des tests exécutés sur la machine d’un développeur, ou ci pour des tests exécutés sur un fournisseur de CI) dans la variable d’environnement DD_ENV. Exemple :

DD_ENV=ci DD_SERVICE=my-javascript-app npm test
  1. Définissez pluginsFile sur "dd-trace/ci/cypress/plugin", par exemple avec cypress.json :

cypress.json

{
  "pluginsFile": "dd-trace/ci/cypress/plugin"
}

Si vous avez déjà défini un pluginsFile, vous pouvez tout de même initialiser l’instrumentation avec :

cypress/plugins/index.js

module.exports = (on, config) => {
  // votre ancien code se trouve avant ce commentaire
  require('dd-trace/ci/cypress/plugin')(on, config)
}
  1. Ajoutez la ligne suivante à supportFile :

cypress/support/index.js

// votre ancien code se trouve avant ce commentaire
require('dd-trace/ci/cypress/support')

Exécutez normalement vos tests, en spécifiant l’environnement concerné (par exemple, local pour des tests exécutés sur la machine d’un développeur, ou ci pour des tests exécutés sur un fournisseur de CI) dans la variable d’environnement DD_ENV. Exemple :

DD_ENV=ci DD_SERVICE=my-ui-app npm test

Ajouter des tags supplémentaires

Pour ajouter des informations supplémentaires à vos tests, par exemple le propriétaire de l’équipe, utilisez cy.task('dd:addTags', { yourTags: 'here' }) dans votre test ou vos hooks.

Par exemple :

beforeEach(() => {
  cy.task('dd:addTags', { 'before.each': 'certain.information' })
})
it('affiche un message Hello world', () => {
  cy.task('dd:addTags', { 'team.owner': 'ui' })
  cy.get('.hello-world')
    .should('have.text', 'Hello World')
})

Intégration RUM

Si l’application Browser testée est instrumentée avec RUM, les résultats de vos tests Cypress ainsi que les sessions Browser RUM et les replays générés sont automatiquement associés. Pour en savoir plus, consultez la section relative à l’intégration RUM.

Paramètres de configuration

La liste suivante répertorie les principaux paramètres de configuration pouvant être utilisés avec le traceur. Vous pouvez les transmettre avec la fonction init() ou sous la forme de variables d’environnement :

service
Nom du service ou de la bibliothèque concerné(e) par les tests.
Variable d’environnement : DD_SERVICE
Valeur par défaut : (nom du framework de test)
Exemple : my-ui
env
Nom de l’environnement dans lequel sont exécutés les tests.
Variable d’environnement : DD_ENV
Valeur par défaut : none
Exemples : local, ci
url
URL de l’Agent Datadog pour la collecte de traces, au format http://hostname:port.
Variable d’environnement : DD_TRACE_AGENT_URL
Valeur par défaut : http://localhost:8126

Vous pouvez également utiliser toutes les autres options de configuration du traceur Datadog.

Recueillir les métadonnées Git

Datadog tire profit des données Git pour vous présenter les résultats de vos tests et les regrouper par référentiel, branche et commit. Les métadonnées Git sont automatiquement recueillies par l’instrumentation de test, à partir des variables d’environnement du fournisseur de CI et du dossier local .git dans le chemin du projet, le cas échéant.

Si vous exécutez des tests dans des fournisseurs de CI non pris en charge, ou sans dossier .git, vous pouvez configurer manuellement les données Git à l’aide de variables d’environnement. Ces dernières sont prioritaires et remplacent les informations détectées automatiquement. Configurez les variables d’environnement suivantes pour obtenir des données Git :

DD_GIT_REPOSITORY_URL
URL du référentiel dans lequel le code est stocké. Les URL HTTP et SSH sont prises en charge.
Exemple : git@github.com:MyCompany/MyApp.git, https://github.com/MyCompany/MyApp.git
DD_GIT_BRANCH
Branche Git testée. Ne renseignez pas cette variable si vous fournissez à la place des informations sur les tags.
Exemple : develop
DD_GIT_TAG
Tag Git testé (le cas échéant). Ne renseignez pas cette variable si vous fournissez à la place des informations sur la branche.
Exemple : 1.0.1
DD_GIT_COMMIT_SHA
Hash entier du commit.
Exemple : a18ebf361cc831f5535e58ec4fae04ffd98d8152
DD_GIT_COMMIT_MESSAGE
Message du commit.
Exemple : Set release number
DD_GIT_COMMIT_AUTHOR_NAME
Nom de l’auteur du commit.
Exemple : John Smith
DD_GIT_COMMIT_AUTHOR_EMAIL
E-mail de l’auteur du commit.
Exemple : john@example.com
DD_GIT_COMMIT_AUTHOR_DATE
Date de l’auteur du commit, au format ISO 8601.
Exemple : 2021-03-12T16:00:28Z
DD_GIT_COMMIT_COMMITTER_NAME
Nom du responsable du commit.
Exemple : Jane Smith
DD_GIT_COMMIT_COMMITTER_EMAIL
E-mail du responsable du commit.
Exemple : jane@example.com
DD_GIT_COMMIT_COMMITTER_DATE
Date du responsable du commit, au format ISO 8601.
Exemple : 2021-03-12T16:00:28Z

Mode sans Agent (version bêta)

Pour instrumenter votre collection de tests sans Agent, configurez les variables d’environnement suivantes :

DD_CIVISIBILITY_AGENTLESS_ENABLED (requis)
Active ou désactive le mode sans Agent.
Valeur par défaut : false
DD_API_KEY (requis)
La clé d’API Datadog utilisée pour importer les résultats de test.
Valeur par défaut: (vide)

En outre, configurez le site Datadog vers lequel vous souhaitez envoyer vos données. Votre site Datadog est .

DD_SITE (requis)
Le [site Datadog][92] vers lequel importer les résultats.
Valeur par défaut : datadoghq.com
Site sélectionné :

Limites connues

Modules ES

Mocha >=9.0.0 adopte une approche axée sur ESM pour charger les fichiers de test. Ainsi, si vous utilisez des modules ES (par exemple, si vous avez défini des fichiers de test avec l’extension .mjs), l’instrumentation est limitée. Les tests sont détectés, mais vous n’avez aucune visibilité sur ces derniers. Pour en savoir plus les modules ES, consultez la documentation NodeJS (en anglais).

Tests Browser

Les tests Browser exécutés avec mocha, jest, cucumber et cypress sont instrumentés par dd-trace-js. Toutefois, par défaut, vous ne pouvez pas visualiser les données sur la session Browser (par exemple, les appels réseau, les actions utilisateur, les chargements de page, etc.).

Pour y remédier, utilisez les solutions RUM et Session Replay. Avec Cypress, les résultats de test ainsi que les sessions Browser RUM et les replays générés sont automatiquement associés. Pour en savoir plus, consultez la section relative à l’intégration RUM.

Meilleures pratiques

Suivez les recommandations suivantes pour tirer pleinement profit du framework de test et de la solution CI Visibility.

Paramétrage des tests

Utilisez tant que possible les outils des frameworks de test afin de paramétrer vos tests. Par exemple, pour jest :

Évitez ce qui suit :

[[1,2,3], [3,4,7]].forEach((a,b,expected) => {
  test('sums correctly', () => {
    expect(a+b).toEqual(expected)
  })
})

Et privilégiez plutôt test.each :

test.each([[1,2,3], [3,4,7]])('sums correctly %i and %i', (a,b,expected) => {
  expect(a+b).toEqual(expected)
})

Pour mocha, utilisez mocha-each :

const forEach = require('mocha-each');
forEach([
  [1,2,3],
  [3,4,7]
])
.it('adds %i and %i then returns %i', (a,b,expected) => {
  expect(a+b).to.equal(expected)
});

Avec cette approche, le framework de test et la solution CI Visibility peuvent différencier vos tests.

Pour aller plus loin