Tests .NET

Ce produit n'est pas pris en charge par le site Datadog que vous avez sélectionné. ().

Compatibilité

Pour obtenir une liste des runtimes et plateformes pris en charge, consultez Compatibilité .NET Framework et Compatibilité .NET/.NET Core.

Frameworks de test pris en charge :

Framework de testVersion
xUnit >= 2.2
NUnit >= 3.0
MsTestV2 >= 14
BenchmarkDotNet >= 0.13.2

Configuration de la méthode de rapport

Pour signaler les résultats des tests à Datadog, vous devez configurer la bibliothèque .NET de Datadog :

    We support auto-instrumentation for the following CI providers:

    CI ProviderAuto-Instrumentation method
    GitHub ActionsDatadog Test Visibility Github Action
    JenkinsUI-based configuration with Datadog Jenkins plugin
    GitLabDatadog Test Visibility GitLab Script
    CircleCIDatadog Test Visibility CircleCI Orb

    Auto-instrumentation runs on the CI executor and does not automatically apply to tests in a separate container. Before using it for containerized tests, see Tests in Containers.

    If the auto-instrumentation step configures the process that runs your tests, you can skip the rest of the setup steps below.

    If you are using a cloud CI provider without access to the underlying worker nodes, such as GitHub Actions or CircleCI, configure the library to use the Agentless mode. For this, set the following environment variables:

    Set these variables before starting the test process. For parallel test runners, set them on the parent process so every worker inherits them.

    DD_CIVISIBILITY_AGENTLESS_ENABLED=true selects Agentless mode. DD_API_KEY provides authentication but does not enable Agentless mode.

    DD_CIVISIBILITY_AGENTLESS_ENABLED=true (Required for Agentless mode)
    Enables Agentless mode to send test results directly to Datadog.
    Default: false
    DD_API_KEY (Required for Agentless mode)
    The Datadog API key used to authenticate test result uploads.
    Default: (empty)

    If you use a Datadog site other than US1, set the following variable:

    DD_SITE (Optional for Agentless mode)
    The Datadog site to upload results to.
    Default: datadoghq.com

    If you are running tests on an on-premises CI provider, such as Jenkins or self-managed GitLab CI, install the Datadog Agent on each worker node by following the Agent installation instructions. This is the recommended option as it allows you to automatically link test results to logs and underlying host metrics.

    If you are using a Kubernetes executor, Datadog recommends using the Datadog Operator. The operator includes Datadog Admission Controller which can automatically inject the tracer library into the build pods. Note: If you use the Datadog Operator, there is no need to download and inject the tracer library since the Admission Controller can do this for you, so you can skip the corresponding step below. However, you still need to make sure that your pods set the environment variables or command-line parameters necessary to enable Test Visibility.

    If you are not using Kubernetes or can’t use the Datadog Admission Controller and the CI provider is using a container-based executor, set the DD_TRACE_AGENT_URL environment variable (which defaults to http://localhost:8126) in the build container running the tracer to an endpoint that is accessible from within that container. Note: Using localhost inside the build references the container itself and not the underlying worker node or any container where the Agent might be running in.

    DD_TRACE_AGENT_URL includes the protocol and port (for example, http://localhost:8126) and takes precedence over DD_AGENT_HOST and DD_TRACE_AGENT_PORT, and is the recommended configuration parameter to configure the Datadog Agent’s URL for CI Visibility.

    If you still have issues connecting to the Datadog Agent, use the Agentless Mode. Note: When using this method, tests are not correlated with logs and infrastructure metrics.

    Installation de l’interface de ligne de commande du traceur .NET

    Installez ou mettez à jour la commande dd-trace en utilisant l’une des méthodes suivantes :

    Instrumentation des tests

    Pour BenchmarkDotNet, suivez ces instructions.

    Pour instrumenter votre collection de tests, faites précéder votre commande de test par dd-trace ci run. Vous pouvez utiliser --dd-service pour définir le service ou la bibliothèque en cours de test et --dd-env pour définir l’environnement dans lequel les tests sont exécutés. Exemple :

      En utilisant dotnet test :

      dd-trace ci run --dd-service=my-dotnet-app -- dotnet test

      En utilisant VSTest.Console.exe :

      dd-trace ci run --dd-service=my-dotnet-app -- VSTest.Console.exe {test_assembly}.dll

      Tous les tests sont automatiquement instrumentés.

      Compatibilité avec le package nuget Microsoft.CodeCoverage

      Depuis la version Microsoft.CodeCoverage 17.2.0, Microsoft a introduit l’instrumentation dynamique utilisant .NET CLR Profiling API activée par défaut uniquement sur Windows. L’instrumentation automatique de Datadog repose sur .NET CLR Profiling API. Cette API n’autorise qu’un seul abonné (par exemple, dd-trace). L’utilisation de l’instrumentation dynamique de CodeCoverage interrompt l’instrumentation automatique des tests.

      La solution consiste à passer de l’instrumentation dynamique à l’instrumentation statique. Modifiez votre fichier .runsettings avec les paramètres de configuration suivants :

      <?xml version="1.0" encoding="utf-8"?>
<RunSettings>
    <DataCollectionRunSettings>
        <DataCollectors>
            <DataCollector friendlyName="Code Coverage">
              <Configuration>
                <CodeCoverage>
                  <!-- Switching to static instrumentation (dynamic instrumentation collides with dd-trace instrumentation) -->
                  <EnableStaticManagedInstrumentation>True</EnableStaticManagedInstrumentation>
                  <EnableDynamicManagedInstrumentation>False</EnableDynamicManagedInstrumentation>
                  <UseVerifiableInstrumentation>False</UseVerifiableInstrumentation>
                  <EnableStaticNativeInstrumentation>True</EnableStaticNativeInstrumentation>
                  <EnableDynamicNativeInstrumentation>False</EnableDynamicNativeInstrumentation>
                  ...
                </CodeCoverage>
              </Configuration>
            </DataCollector>
        </DataCollectors>
    </DataCollectionRunSettings>
</RunSettings>

      Paramètres de configuration

      Vous pouvez modifier la configuration par défaut de l’interface de ligne de commande en utilisant des arguments de ligne de commande ou des variables d’environnement. Pour obtenir une liste complète des paramètres de configuration, exécutez :

      dd-trace ci run --help

      La liste suivante indique les valeurs par défaut des paramètres de configuration clé :

      --dd-service (Facultatif)
      Nom du service ou de la bibliothèque à tester.
      Variable d’environnement: DD_SERVICE
      Par défaut: Le nom du dépôt
      Exemple: my-dotnet-app
      --dd-env (Facultatif)
      Nom de l’environnement où les tests sont exécutés.
      Variable d’environnement : DD_ENV
      Par défaut : none
      Exemples : local, ci
      --agent-url (Uniquement lors de l’utilisation du Datadog Agent)
      L’URL du Datadog Agent pour la collecte des traces, sous la forme http://hostname:port.
      Variable d’environnement : DD_TRACE_AGENT_URL
      Par défaut : http://localhost:8126
      test_session.name (Disponible uniquement en tant que variable d’environnement)
      Identifie un groupe de tests, tel que unit-tests, integration-tests ou smoke-tests.
      Variable d’environnement : DD_TEST_SESSION_NAME
      Par défaut: Le nom du job CI et la commande de test, ou la commande de test si le nom du job CI n’est pas disponible.
      Exemple: unit-tests, integration-tests, smoke-tests

      Pour plus d’informations sur les tags réservés service et env, consultez Unified Service Tagging. Vous pouvez également utiliser toutes les autres options de configuration du traceur Datadog.

      Ajout de tags personnalisés aux tests

      Pour ajouter des tags personnalisés aux tests, configurez d’abord l’instrumentation personnalisée.

      Vous pouvez ajouter des tags personnalisés à vos tests en utilisant la span actuellement active :

      // inside your test
var scope = Tracer.Instance.ActiveScope; // from Datadog.Trace;
if (scope != null) {
    scope.Span.SetTag("test_owner", "my_team");
}
// test continues normally
// ...

      Pour créer des filtres ou des champs group by pour ces tags, vous devez d’abord créer des facettes. Pour plus d’informations sur l’ajout de tags, consultez la section Ajout de tags de la documentation sur l’instrumentation personnalisée .NET.

      Ajout de mesures personnalisées aux tests

      Pour ajouter des mesures personnalisées aux tests, configurez d’abord l’instrumentation personnalisée.

      Tout comme pour les tags, vous pouvez ajouter des mesures personnalisées à vos tests en utilisant le span actif :

      // inside your test
var scope = Tracer.Instance.ActiveScope; // from Datadog.Trace;
if (scope != null) {
    scope.Span.SetTag("memory_allocations", 16);
}
// test continues normally
// ...

      Pour créer des filtres ou des visualisations pour ces tags, vous devez d’abord créer des facettes. Pour plus d’informations sur l’ajout de tags, consultez la section Ajout de tags de la documentation sur l’instrumentation personnalisée .NET.

      En savoir plus sur les mesures personnalisées dans le Guide d’ajout de mesures personnalisées.

      Rapporter la couverture de code

      Lorsque la couverture de code est disponible, le Datadog Tracer (v2.31.0 ou ultérieure) la rapporte sous le tag test.code_coverage.lines_pct pour vos sessions de test.

      Si vous utilisez Coverlet pour calculer votre couverture de code, indiquez le chemin vers le fichier de rapport dans la variable d’environnement DD_CIVISIBILITY_EXTERNAL_CODE_COVERAGE_PATH lors de l’exécution de dd-trace. Le fichier de rapport doit être au format OpenCover ou Cobertura. Alternativement, vous pouvez activer le calcul de couverture de code intégré du Datadog Tracer avec la variable d’environnement DD_CIVISIBILITY_CODE_COVERAGE_ENABLED=true.

      Remarque : Lorsque vous utilisez Test Impact Analysis, la couverture de code intégrée du SDK est activée par défaut.

      Vous pouvez voir l’évolution de la couverture des tests dans l’onglet Coverage d’une session de test.

      Pour plus d’informations sur les options d’exclusion, consultez Code Coverage.

      Instrumentation des tests BenchmarkDotNet

      Pour instrumenter vos tests BenchmarkDotNet, vous devez :

      1. Ajoutez le Datadog.Trace.BenchmarkDotNet package NuGet à votre projet (par exemple, en utilisant dotnet add package Datadog.Trace.BenchmarkDotNet).
      2. Configurez votre projet pour utiliser l’exportateur Datadog.Trace.BenchmarkDotNet en utilisant l’attribut DatadogDiagnoser ou la méthode d’extension WithDatadog(). Exemple :
        using BenchmarkDotNet.Attributes;
using Datadog.Trace.BenchmarkDotNet;

[DatadogDiagnoser]
[MemoryDiagnoser]
public class OperationBenchmark
{
    [Benchmark]
    public void Operation()
    {
        // ...
    }
}
        using BenchmarkDotNet.Configs;
using BenchmarkDotNet.Running;
using Datadog.Trace.BenchmarkDotNet;

var config = DefaultConfig.Instance
              .WithDatadog();

BenchmarkRunner.Run<OperationBenchmark>(config);
        1. Configurez la méthode de rapport.
        2. Exécutez le projet BenchmarkDotNet comme vous le faites habituellement, tous les tests BenchmarkDotNet seront automatiquement instrumentés.

        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

        Instrumentation personnalisée

        Remarque : Votre configuration d'instrumentation personnalisée dépend de la dd-trace version. Pour utiliser l'instrumentation personnalisée, vous devez maintenir synchronisées les versions des packages NuGet. dd-trace et Datadog.Trace Les packages NuGet doivent être synchronisés.

        Pour utiliser l’instrumentation personnalisée dans votre application .NET, procédez comme suit :

        1. Exécutez dd-trace --version pour obtenir la version de l’outil.
        2. Ajoutez le Datadog.Trace package NuGet avec la même version à votre application.
        3. Dans le code de votre application, accédez au traceur global via la propriété Datadog.Trace.Tracer.Instance pour créer de nouveaux spans.

        Pour découvrir comment ajouter des spans et des tags pour l’instrumentation personnalisée, consultez la documentation relative à l’instrumentation personnalisée .NET.

        API de test manuel

        Remarque : Pour utiliser l'API de test manuel, vous devez ajouter le Datadog.Trace package NuGet dans le projet .NET cible.

        Si vous utilisez XUnit, NUnit ou MSTest avec vos projets .NET, Test Optimization les instrumente automatiquement et envoie les résultats des tests à Datadog. Si vous utilisez un framework de test non pris en charge ou si vous disposez d’un mécanisme de test différent, vous pouvez utiliser l’API pour signaler les résultats des tests à Datadog.

        L’API repose sur trois concepts, à savoir le module de test, les collections de tests et les tests.

        Module de test

        Un module de test représente l’assemblage .NET qui comprend les tests.

        Pour démarrer un module de test, appelez TestModule.Create() et transmettez le nom du module ou le nom de l’assembly .NET où se trouvent les tests.

        Lorsque tous vos tests sont terminés, appelez module.Close() ou module.CloseAsync(), ce qui force la bibliothèque à envoyer tous les résultats de test restants au backend.

        Collections de tests

        Une collection de tests comprend un ensemble de tests. Ils peuvent avoir des méthodes d’initialisation et de nettoyage communes et partager certaines variables. Dans .NET, ils sont généralement implémentés sous forme de classe de test ou de fixture contenant plusieurs méthodes de test. Une collection de tests peut éventuellement comporter des informations supplémentaires comme des attributs ou des informations d’erreur.

        Créez des collections de tests dans le module de test en appelant module.GetOrCreateSuite() et en transmettant le nom de la collection de tests.

        Appelez suite.Close() lorsque tous les tests associés dans la suite ont terminé leur exécution.

        Tests

        Chaque test s’exécute au sein d’une suite et doit se terminer par l’un de ces trois statuts : TestStatus.Pass, TestStatus.Fail ou TestStatus.Skip.

        Un test peut éventuellement comporter des informations supplémentaires telles que :

        • Paramètres
        • Attributs
        • Informations d’erreur
        • Traits de test
        • Données de benchmark

        Créez des tests dans une suite en appelant suite.CreateTest() et en transmettant le nom du test. Lorsqu’un test se termine, appelez test.Close() avec l’un des statuts prédéfinis.

        Exemple de code

        Le code suivant permet d’utiliser les fonctionnalités de base de l’API :

        using System.Reflection;
using Datadog.Trace.Ci;

var module = TestModule.Create(Assembly.GetExecutingAssembly().GetName().Name ?? "(dyn_module)");
module.SetTag("ModuleTag", "Value");

var suite = module.GetOrCreateSuite("MySuite");
suite.SetTag("SuiteTag", 42);

var test = suite.CreateTest("Test01");
test.SetTag("TestTag", "Value");
test.SetParameters(new TestParameters
{
    Arguments = new Dictionary<string, object>
    {
        ["a"] = 42,
        ["b"] = 0,
    }
});
test.SetTraits(new Dictionary<string, List<string>>
{
    ["Category"] = new () { "UnitTest" }
});

try
{
    var a = 42;
    var b = 0;
    var c = a / b;
}
catch (Exception ex)
{
    test.SetErrorInfo(ex);
}

test.Close(TestStatus.Fail);
suite.Close();
await module.CloseAsync();

        Appelez toujours module.Close() ou module.CloseAsync() à la fin afin que toutes les données de test soient transmises à Datadog.

        Bonnes pratiques

        Nom de la session de test DD_TEST_SESSION_NAME

        Utilisez DD_TEST_SESSION_NAME pour définir le nom de la session de test et le groupe de tests associé. Voici des exemples de valeurs pour ce tag :

        • unit-tests
        • integration-tests
        • smoke-tests
        • flaky-tests
        • ui-tests
        • backend-tests

        Si DD_TEST_SESSION_NAME n’est pas spécifié, la valeur par défaut est le nom du job CI et la commande de test. Si le nom du job CI n’est pas disponible, la commande de test est utilisée.

        Le nom de la session de test doit être unique au sein d’un dépôt pour vous aider à distinguer différents groupes de tests.

        Quand utiliser DD_TEST_SESSION_NAME {#when-to-use-dd-test-session-name} :

        Il existe un ensemble de paramètres que Datadog vérifie pour établir une correspondance entre les sessions de test. La commande de test utilisée pour exécuter les tests en fait partie. Si la commande de test contient une chaîne qui change à chaque exécution, comme un dossier temporaire, Datadog considère que les sessions ne sont pas liées entre elles. Exemple :

        • dotnet test --temp-dir=/var/folders/t1/rs2htfh55mz9px2j4prmpg_c0000gq/T

        Datadog recommande d’utiliser DD_TEST_SESSION_NAME si vos commandes de test varient entre les exécutions.

        Pour aller plus loin

        Documentation, liens et articles supplémentaires utiles:

        Transmettre des variables d'environnement pour des tests dans ContainersDOCUMENTATION more more Explorer les résultats de test et la performanceDOCUMENTATION more more Accélérez vos jobs de test avec Test Impact AnalysisDOCUMENTATION more more Dépannage Test OptimizationDOCUMENTATION more more