Importer des fichiers de rapport de test JUnit dans Datadog

Présentation

Les fichiers de rapport de test JUnit sont des fichiers XML qui contiennent des informations sur l’exécution des tests, notamment les noms des tests et des suites de tests, leur statut (réussite ou échec), leur durée et parfois des logs d’erreurs. Bien que ce format ait été créé dans le cadre du framework de test JUnit, de nombreux autres frameworks populaires peuvent l’utiliser pour générer leurs résultats.

Si votre framework de test permet de générer des rapports de test XML JUnit, vous pouvez les utiliser comme alternative légère à l’instrumentation native de vos tests à l’aide des traceurs Datadog. Les résultats de test importés par le biais de rapports XML JUnit s’affichent en même temps que les données de test envoyées par les traceurs.

Compatibilité

Bibliothèque de tracing Datadog prise en charge :

Installer l’interface de ligne de commande Datadog CI

Installez l’interface de ligne de commande datadog-ci de façon globale avec npm :

npm install -g @datadog/datadog-ci

Binaire standalone (bêta)

Si l’installation de Node.js via l’interface de ligne de commande n’est pas possible, des binaires standalone sont intégrés aux versions de l’interface Datadog CI. Seuls linux-x64, darwin-x64 (MacOS) et win-x64 (Windows) sont pris en charge. Pour l’installer, exécutez les commandes suivantes à partir de votre terminal :

curl -L --fail "https://github.com/DataDog/datadog-ci/releases/latest/download/datadog-ci_linux-x64" --output "/usr/local/bin/datadog-ci" && chmod +x /usr/local/bin/datadog-ci

datadog-ci version

curl -L --fail "https://github.com/DataDog/datadog-ci/releases/latest/download/datadog-ci_darwin-x64" --output "/usr/local/bin/datadog-ci" && chmod +x /usr/local/bin/datadog-ci

datadog-ci version

Invoke-WebRequest -Uri "https://github.com/DataDog/datadog-ci/releases/latest/download/datadog-ci_win-x64.exe" -OutFile "datadog-ci.exe"

Start-Process -FilePath "./datadog-ci.exe" -ArgumentList version

Importer des rapports de test

Pour importer vos rapports de test XML JUnit dans Datadog, exécutez la commande ci-dessous. Vous devrez spécifier le nom du service ou de la bibliothèque testé(e) à l’aide du paramètre --service, ainsi qu’un ou plusieurs chemins pointant vers les fichiers de rapport XML directement ou vers les dossiers dans lesquels ils se trouvent :

datadog-ci junit upload --service <nom_service> <path> [<chemin> ...]

Indiquez une clé d’API Datadog valide dans la variable d’environnement DATADOG_API_KEY, et l’environnement dans lequel les tests ont été exécutés (par exemple, local si vous importez des résultats depuis la machine d’un développeur, ou ci si vous les importez depuis un fournisseur de CI) dans la variable d’environnement DD_ENV. Par exemple :

DD_ENV=ci DATADOG_API_KEY=<clé_api> DATADOG_SITE= datadog-ci junit upload \
  --service my-api-service \
  unit-tests/junit-reports e2e-tests/single-report.xml

steps:
  - name: Run tests
    run: ./run-tests.sh
  - name: Upload test results to Datadog
    if: always()
    run: datadog-ci junit upload --service nom_service ./junit.xml

test:
  stage: test
  script:
    - ./run-tests.sh
  after_script:
    - datadog-ci junit upload --service nom_service ./junit.xml

pipeline {
  agent any
  stages {
    stage('Run tests') {
      steps {
        sh './run-tests.sh'
      }
      post {
        always {
          sh 'datadog-ci junit upload --service nom_service ./junit.xml'
        }
      }
    }
  }
}

$(./run-tests.sh); export tests_exit_code=$?
datadog-ci junit upload --service nom_service ./junit.xml
if [ $tests_exit_code -ne 0 ]; then exit $tests_exit_code; fi

Les rapports de plus de 250 MiB peuvent ne pas être entièrement traités, entraînant alors des tests ou des logs manquants. Pour une expérience optimale, veillez à ce que les rapports soient inférieurs à 250 MiB.

Paramètres de configuration

Voici la liste complète des options disponibles lorsque la commande datadog-ci junit upload est utilisée :

--service (requis)

Nom du service ou de la bibliothèque testé(e).
Variable d’environnement : DD_SERVICE
Exemple : my-api-service

--env

Environnement dans lequel les tests ont été exécutés.
Variable d’environnement : DD_ENV
Exemple : ci

--tags

Paires key/value au format key:value à associer à l’ensemble des tests (le paramètre --tags peut être fourni plusieurs fois). Lorsque vous spécifiez des tags avec DD_TAGS, séparez-les avec des virgules (par exemple, team:backend,priority:high).
Variable d’environnement : DD_TAGS
Valeur par défaut : (aucune)
Exemple : team:backend
Remarque : les tags spécifiés avec --tags et avec la variable d’environnement DD_TAGS sont fusionnés. Si --tags et DD_TAGS comportent la même clé, la valeur de DD_TAGS est prioritaire.

--metrics

Paire numériques key-value au format key:number à associer à l’ensemble des tests (le paramètre --metrics peut être spécifié plusieurs fois). Lorsque vous spécifiez des métriques avec DD_METRICS, séparez-les avec des virgules (par exemple, memory_allocations:13,test_importance:2).
Variable d’environnement : DD_METRICS
Valeur par défaut : (aucune)
Exemple : memory_allocations:13
Remarque : les métriques spécifiées avec --metrics et avec la variable d’environnement DD_METRICS sont fusionnées. Si --metrics et DD_METRICS comportent la même clé, la valeur de DD_METRICS est prioritaire.

--report-tags

Paires key-value au format key:value. Fonctionne comme le paramètre --tags, mais ces tags sont uniquement appliqués au niveau de la session et ne sont pas fusionnés avec la variable d’environnement DD_TAGS
Valeur par défaut : (aucune)
Exemple : test.code_coverage.enabled:true

--report-metrics

Paires key-value au format key:123. Fonctionne comme le paramètre --metrics, mais ces tags sont uniquement appliqués au niveau de la session et ne sont pas fusionnés avec la variable d’environnement DD_METRICS
Valeur par défaut : (aucune)
Exemple : test.code_coverage.lines_pct:82

--xpath-tag

Clé et expression xpath au format key=expression. Permettent de personnaliser les tags du test dans le fichier (le paramètre --xpath-tag peut être spécifié plusieurs fois).
Consultez la section Ajouter des métadonnées avec des expressions XPath pour en savoir plus sur les expressions prises en charge.
Valeur par défaut : (aucune)
Exemple : test.suite=/testcase/@classname
Remarque : les tags spécifiés avec --xpath-tag et --tags ou la variable d’environnement DD_TAGS sont fusionnés. La valeur de xpath-tag est appliquée en priorité, car elle est généralement différente pour chaque test.

--logs

Activer la transmission du contenu des rapports XML sous forme de logs. Le contenu de <system-out>, <system-err> et <failure> est recueilli sous forme de logs. Les logs des éléments au sein d’un <testcase> sont automatiquement associés au test.
Variable d’environnement : DD_CIVISIBILITY_LOGS_ENABLED
Valeur par défaut : false
Remarque : les logs et CI Visibility sont facturés séparément.

--max-concurrency

Nombre maximal d’importations simultanées via l’API.
Valeur par défaut : 20

--dry-run

Permet d’exécuter la commande sans que le fichier ne soit réellement importé dans Datadog. Toutes les autres vérifications sont effectuées.
Valeur par défaut : false

--skip-git-metadata-upload

Flag utilisé pour ignorer l’importation des métadonnées git. Si vous souhaitez les importer, vous pouvez passer le paramètre –skip-git-metadata-upload=0 ou –skip-git-metadata-upload=false.
Valeur par défaut : true

--git-repository-url

L’URL du dépôt à partir duquel récupérer les métadonnées git. Si ce paramètre n’est pas passé, l"URL est récupérée depuis le dépôt git local.
Valeur par défaut : dépôt git local
Exemple : git@github.com:DataDog/documentation.git

--verbose

Flag utilisé pour augmenter le niveau de détail de la sortie de la commande
Valeur par défaut : false

Arguments positionnels

Les chemins vers les rapports XML JUnit ou vers les dossiers dans lesquels ils sont situés. Si vous spécifiez un dossier, l’interface de ligne de commande recherche tous les fichiers .xml qui s’y trouvent.

Les variables d’environnement suivantes sont prises en charge :

DATADOG_API_KEY (requis)

La clé d’API Datadog utilisée pour authentifier les requêtes.
Valeur par défaut : (aucune)

En outre, configurez le site Datadog de façon à utiliser celui que vous avez sélectionné () :

DATADOG_SITE (requis)

Le site Datadog vers lequel importer les résultats.
Valeur par défaut : datadoghq.com
Site sélectionné :

Recueillir les métadonnées Git

Datadog uses Git information for visualizing your test results and grouping them by repository, branch, and commit. Git metadata is automatically collected by the test instrumentation from CI provider environment variables and the local .git folder in the project path, if available.

If you are running tests in non-supported CI providers or with no .git folder, you can set the Git information manually using environment variables. These environment variables take precedence over any auto-detected information. Set the following environment variables to provide Git information:

DD_GIT_REPOSITORY_URL

URL of the repository where the code is stored. Both HTTP and SSH URLs are supported.
Example: git@github.com:MyCompany/MyApp.git, https://github.com/MyCompany/MyApp.git

DD_GIT_BRANCH

Git branch being tested. Leave empty if providing tag information instead.
Example: develop

DD_GIT_TAG

Git tag being tested (if applicable). Leave empty if providing branch information instead.
Example: 1.0.1

DD_GIT_COMMIT_SHA

Full commit hash.
Example: a18ebf361cc831f5535e58ec4fae04ffd98d8152

DD_GIT_COMMIT_MESSAGE

Commit message.
Example: Set release number

DD_GIT_COMMIT_AUTHOR_NAME

Commit author name.
Example: John Smith

DD_GIT_COMMIT_AUTHOR_EMAIL

Commit author email.
Example: john@example.com

DD_GIT_COMMIT_AUTHOR_DATE

Commit author date in ISO 8601 format.
Example: 2021-03-12T16:00:28Z

DD_GIT_COMMIT_COMMITTER_NAME

Commit committer name.
Example: Jane Smith

DD_GIT_COMMIT_COMMITTER_EMAIL

Commit committer email.
Example: jane@example.com

DD_GIT_COMMIT_COMMITTER_DATE

Commit committer date in ISO 8601 format.
Example: 2021-03-12T16:00:28Z

Importer les métadonnées Git

À partir de la version 2.9.0 de datadog-ci, CI Visibility importe automatiquement les métadonnées Git (historique de commits). Ces métadonnées contiennent les noms des fichiers mais pas leur contenu. Si vous souhaitez désactiver ce comportement, passez le flag --skip-git-metadata-upload.

Recueillir les métadonnées de configuration de l’environnement

Datadog utilise des tags spéciaux dédiés pour identifier la configuration de l’environnement dans lequel les tests sont exécutés, notamment le système d’exploitation, le runtime et les détails de l’appareil, le cas échéant. Lorsque le même test pour le même commit est exécuté sous plusieurs configurations différentes (par exemple, sous Windows et sous Linux), les tags sont utilisés pour différencier les configurations en cas d’échec du test ou d’irrégularité.

Vous pouvez spécifier ces tags spéciaux à l’aide du paramètre --tags lorsque vous utilisez la commande datadog-ci junit upload, ou en définissant la variable d’environnement DD_TAGS.

Tous ces tags sont facultatifs, et seuls ceux que vous spécifiez seront utilisés pour identifier les différentes configurations de l’environnement.

test.bundle

Permet d’exécuter des groupes de suites de tests séparément.
Exemples : ApplicationUITests, ModelTests

os.platform

Nom du système d’exploitation.
Exemples : windows, linux, darwin

os.version

Version du système d’exploitation.
Exemples : 10.15.4, 14.3.2, 95

os.architecture

Architecture du système d’exploitation.
Exemples : x64, x86, arm64

runtime.name

Nom de l’interpréteur du langage ou du runtime de programmation.
Exemples : .NET, .NET Core, OpenJDK Runtime Environment, Java(TM) SE Runtime Environment, CPython

runtime.version

Version du runtime.
Exemples : 5.0.0, 3.1.7

runtime.vendor

Nom du fournisseur du runtime, le cas échéant. Les exemples sont donnés dans le cas d’un runtime Java.
Exemples : AdoptOpenJDK, Oracle Corporation

runtime.architecture

Architecture du runtime.
Exemples : x64, x86, arm64

Pour les applications mobiles (Swift, Android) :

device.model

Modèle de l’appareil testé.
Exemples : iPhone11,4, AppleTV5,3

device.name

Nom de l’appareil testé.
Exemples : iPhone 12 Pro Simulator, iPhone 13 (QA team)

Ajouter des métadonnées avec des expressions XPath

En plus du paramètre d’interface de ligne de commande --tags et de la variable d’environnement DD_TAGS, qui appliquent des tags personnalisés à tous les tests inclus dans le rapport XML importé, le paramètre --xpath-tag fournit des règles personnalisées pour ajouter à chaque test des tags provenant de différents attributs du XML.

Le paramètre fourni doit correspondre au format key=expression, où key est le nom du tag personnalisé à ajouter et où expression est une expression XPath valide parmi celles prises en charge.

Même si la syntaxe XPath est utilisée pour plus de simplicité, seules les expressions suivantes sont prises en charge :

/testcase/@attribute-name

L’attribut XML issu de <testcase attribute-name="value">.

/testcase/../@attribute-name

L’attribut XML issu du <testsuite attribute-name="value"> parent du <testcase> actuel.

/testcase/..//property[@name='property-name']

L’attribut value du <property name="property-name" value="value"> au sein du <testsuite> parent du <testcase> actuel.

/testcase//property[@name='property-name']

L’attribut value du <property name="property-name" value="value"> au sein du <testcase> actuel.

Exemples :

<?xml version="1.0" encoding="UTF-8"?>
<testsuites>
  <testsuite tests="1" failures="0" time="0.030000" name="value 1">
    <testcase classname="SomeTestSuiteClass" name="test_something" time="0.030000"></testcase>
  </testsuite>
  <testsuite tests="1" failures="0" time="0.021300" name="value 2">
    <testcase classname="OtherTestSuiteClass" name="test_something" time="0.021300"></testcase>
  </testsuite>
</testsuites>

datadog-ci junit upload --service nom_service \
  --xpath-tag test.suite=/testcase/@classname ./junit.xml

<?xml version="1.0" encoding="UTF-8"?>
<testsuites>
  <testsuite tests="1" failures="0" time="0.020000" name="SomeTestSuiteClass">
    <testcase name="test_something" time="0.010000" attr="value 1"></testcase>
    <testcase name="test_other" time="0.010000" attr="value 2"></testcase>
  </testsuite>
</testsuites>

datadog-ci junit upload --service nom_service \
  --xpath-tag custom_tag=/testcase/@attr ./junit.xml

<?xml version="1.0" encoding="UTF-8"?>
<testsuites>
  <testsuite tests="1" failures="0" time="0.030000" name="SomeTestSuiteClass">
    <properties>
      <property name="prop" value="value 1"></property>
    </properties>
    <testcase name="test_something" time="0.030000" attr="value 1"></testcase>
  </testsuite>
  <testsuite tests="1" failures="0" time="0.021300" name="OtherTestSuiteClass">
    <properties>
      <property name="prop" value="value 1"></property>
    </properties>
    <testcase name="test_something" time="0.021300" attr="value 1"></testcase>
  </testsuite>
</testsuites>

datadog-ci junit upload --service nom_service \
  --xpath-tag custom_tag=/testcase/..//property[@name=\'prop\'] ./junit.xml

Ajouter des métadonnées via des éléments property

Vous avez également la possibilité d’appliquer des tags supplémentaires à des tests spécifiques en ajoutant des éléments <property name="dd_tags[key]" value="value"> au sein d’un élément <testsuite> ou <testcase>. Lorsque vous ajoutez des tags à un élément <testcase>, ils sont stockés dans la span du test. Lorsque vous ajoutez des tags à un élément <testsuite>, ils sont stockés dans toutes les spans de test de la suite concernée.

Pour être traité, l’attribut name dans l’élément <property> doit respecter le format dd_tags[key], où key correspond au nom du tag custom à ajouter. Les autres propriétés sont ignorées.

Exemple : ajout de tags à un élément <testcase>.

<?xml version="1.0" encoding="UTF-8"?>
<testsuites>
  <testsuite tests="1" failures="0" time="0.030000" name="SomeTestSuiteClass">
    <testcase classname="SomeTestSuiteClass" name="test_something" time="0.010000">
      <properties>
        <property name="dd_tags[custom_tag]" value="valeur quelconque"></property>
        <property name="dd_tags[runtime.name]" value="CPython"></property>
      </properties>
    </testcase>
  </testsuite>
</testsuites>

Exemple : ajout de tags à un élément <testsuite>.

<?xml version="1.0" encoding="UTF-8"?>
<testsuites>
  <testsuite tests="1" failures="0" time="0.030000" name="SomeTestSuiteClass">
    <properties>
      <property name="dd_tags[custom_tag]" value="valeur quelconque"></property>
      <property name="dd_tags[runtime.name]" value="CPython"></property>
    </properties>
    <testcase classname="SomeTestSuiteClass" name="test_something" time="0.010000"></testcase>
  </testsuite>
</testsuites>

Les valeurs que vous envoyez à Datadog sont des chaînes de caractères, ce qui signifie que les facettes sont affichées dans l’ordre lexicographique. Pour envoyer des entiers au lieu de chaînes, utilisez le flag --metrics et la variable d’environnement DD_METRICS.

Transmission de la couverture du code

Il est possible de transmettre la couverture du code pour un rapport JUnit donné via l’option --report-metrics. Pour ce faire, définissez la métrique test.code_coverage.lines_pct :

datadog-ci junit upload --service my-api-service --report-metrics test.code_coverage.lines_pct:82 unit-tests/junit-reports e2e-tests/single-report.xml

Pour en savoir plus, consultez la section Couverture du code.

Pour aller plus loin

Documentation, liens et articles supplémentaires utiles:

Explorer les résultats de test et les performancesDOCUMENTATION Dépannage de CI VisibilityDOCUMENTATION