Compatibilidad

Para obtener una lista de los tiempos de ejecución y las plataformas compatibles, consulta Compatibilidad con .NET Framework y Compatibilidad con .NET/.NET Core.

Frameworks para tests compatibles:

Configuración del método de notificación

Para informar de los resultados de tests a Datadog, debes configurar la biblioteca .NET de Datadog:

Instalación de la CLI del rastreador .NET

Instala o actualiza el comando dd-trace de una de las siguientes maneras:

• Con el SDK de .NET ejecutando el comando:

  dotnet tool update -g dd-trace
  

• Descargando la versión adecuada:

  • Win-x64: https://dtdg.co/dd-trace-dotnet-win-x64
  • Linux-x64: https://dtdg.co/dd-trace-dotnet-linux-x64
  • Linux-musl-x64 (Alpine): https://dtdg.co/dd-trace-dotnet-linux-musl-x64

• O descargándolo de la página de la versión de GitHub.

Instrumentación de tests

Para instrumentar tu conjunto de tests, antepone a tu comando de test dd-trace ci run, proporcionando el nombre de servicio o biblioteca en proceso de test como el parámetro --dd-service parameter, and the environment where tests are being run (for example, local when running tests on a developer workstation, or ci when running them on a CI provider) as the --dd-env. Por ejemplo:

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

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

Todos los tests se instrumentan automáticamente.

Compatibilidad con el paquete nuget de Microsoft.CodeCoverage

Desde la versión 17.2.0 de Microsoft.CodeCoverage, Microsoft introdujo la instrumentación dinámica con la .NET CLR Profiling API habilitada por defecto solo en Windows. La instrumentación automática de Datadog se basa en la .NET CLR Profiling API. Esta API solo permite un suscriptor (por ejemplo, dd-trace). El uso de la instrumentación dinámica de CodeCoverage rompe la instrumentación de test automática.

La solución es cambiar de instrumentación dinámica a instrumentación estática. Modifica tu archivo .runsettings con los siguientes mandos de configuración:

<?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>

Ajustes de configuración

Puedes cambiar la configuración predeterminada de la CLI utilizando argumentos de línea de comandos o variables de entorno. Para obtener una lista completa de los ajustes de configuración, ejecuta:

dd-trace ci run --help

En la siguiente lista, se muestran los valores por defecto de los ajustes de configuración clave:

--dd-service

nombre del servicio o biblioteca en proceso de test.
**Variable de entorno **: DD_SERVICE
Por defecto: el nombre del repositorio
Ejemplo: my-dotnet-app

--dd-env

nombre del entorno donde se están ejecutando los tests.
**Variable de entorno **: DD_ENV
Por defecto: none
Ejemplos: local, ci

--agent-url

URL del Datadog Agent para la recopilación de trazas con el formato http://hostname:port.
Variable de entorno: DD_TRACE_AGENT_URL
Por defecto: http://localhost:8126

test_session.name (solo disponible como variable de entorno)

Identifica un grupo de tests, como integration-tests, unit-tests o smoke-tests.
Variable de entorno: DD_TEST_SESSION_NAME
Por defecto: (nombre del trabajo CI (genérico) + comando de test)
Ejemplo: unit-tests, integration-tests, smoke-tests

Para más información sobre etiquetas reservadas service y env, consulta etiquetado de servicios unificado. También se pueden utilizar todas las demás opciones de configuración del rastreador de Datadog.

Añadir etiquetas (tags) personalizadas a los tests

Para añadir etiquetas personalizadas a los tests, configura la instrumentación personalizada primero.

Puedes añadir etiquetas personalizadas a tus tests con el tramo activo en ese momento:

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

Para crear filtros o campos group by para estas etiquetas, primero debes crear facetas. Para obtener más información sobre la adición de etiquetas, consulta la sección Adición de etiquetas de la documentación de instrumentación personalizada de .NET.

Añadir medidas personalizadas a los tests

Para añadir medidas personalizadas a los tests, configura la instrumentación personalizada primero.

Al igual que con las etiquetas, puedes añadir medidas personalizadas a tus tests utilizando el tramo activo en ese momento:

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

Para crear filtros o visualizaciones para estas etiquetas, primero debes crear facetas. Para obtener más información sobre la adición de etiquetas, consulta la sección Adición de etiquetas de la documentación de instrumentación personalizada de .NET.

Más información sobre las medidas personalizadas en la guía para añadir medidas personalizadas.

Informar sobre la cobertura del código

Cuando la cobertura del código está disponible, el rastreador de Datadog (v2.31.0 o posterior) informa de ella en la etiqueta test.code_coverage.lines_pct para tus sesiones de test.

Si utilizas Coverlet para calcular la cobertura del código, indica la ruta del archivo de informe en la variable de entorno DD_CIVISIBILITY_EXTERNAL_CODE_COVERAGE_PATH al ejecutar dd-trace. El archivo de informe debe estar en los formatos OpenCover o Cobertura. Alternativamente, puedes activar el cálculo de cobertura del código integrado del rastreador de Datadog con la variable de entorno DD_CIVISIBILITY_CODE_COVERAGE_ENABLED=true.

Nota: Cuando se utiliza Test Impact Analysis, la cobertura de código integrada en el rastreador está activada por defecto.

Puedes ver la evolución de la cobertura de los tests en la pestaña Coverage (Cobertura) de una sesión de tests.

Para más información sobre las opciones de exclusión, consulta Cobertura del código.

Instrumentación de los tests de BenchmarkDotNet

Para instrumentar tus tests de referencia, debes hacer lo siguiente:

1. Añade el paquete NuGet Datadog.Trace.BenchmarkDotNet a tu proyecto (por ejemplo, con dotnet add package Datadog.Trace.BenchmarkDotNet).
2. Configura tu proyecto para utilizar el exportador Datadog.Trace.BenchmarkDotNet con el atributo DatadogDiagnoser o el método de extensión WithDatadog(). Por ejemplo:

con BenchmarkDotNet.Attributes;
con Datadog.Trace.BenchmarkDotNet;

[DatadogDiagnoser]
[MemoryDiagnoser]
public class OperationBenchmark
{
    [Benchmark]
    public void Operation()
    {
        // ...
    }
}

con BenchmarkDotNet.Configs;
con BenchmarkDotNet.Running;
con Datadog.Trace.BenchmarkDotNet;

var config = DefaultConfig.Instance
              .WithDatadog();

BenchmarkRunner.Run<OperationBenchmark>(config);

3. Configuración del método de notificación.
4. Ejecuta el proyecto de referencia como lo haces normalmente, todos los tests de referencia se instrumentarán automáticamente.

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

Instrumentación personalizada

Para utilizar la instrumentación personalizada en tu aplicación .NET:

1. Ejecuta dd-trace --version para obtener la versión de la herramienta.
2. Añade el paquete de NuGet Datadog.Trace con la misma versión a tu aplicación.
3. En tu código de aplicación, accede al rastreador global a través de la propiedad de Datadog.Trace.Tracer.Instance para crear nuevos tramos.

Para más información sobre cómo añadir tramos y etiquetas para la instrumentación personalizada, consulta la documentación de instrumentación personalizada de .NET.

API para tests manuales

Si utilizas XUnit, NUnit o MSTest con tus proyectos .NET, Test Optimization los instrumenta automáticamente y envía los resultados de los tests a Datadog. Si utilizas un framework no compatible o si tienes un mecanismo de test diferente, puedes utilizar la API para informar de los resultados de los tests a Datadog.

La API se basa en tres conceptos: módulo de test, conjuntos de tests y tests.

Módulo de test

Un módulo de test representa el ensamblado de .NET que incluye los tests.

Para iniciar un módulo de test, llama a TestModule.Create() y pasa el nombre del módulo o el nombre del ensamblado de .NET donde se encuentran los tests.

Cuando todos tus tests hayan finalizado, llama a module.Close() o module.CloseAsync(), lo que obliga a la biblioteca a enviar todos los resultados de los tests restantes al backend.

Conjuntos de tests

Un conjunto de tests comprende un grupo de tests. Pueden tener métodos comunes de inicialización y desmontaje y compartir algunas variables. En .NET, suelen implementarse como una clase de test o fixture que contiene varios métodos de test. Un conjunto de tests puede tener opcionalmente información adicional como atributos o información de error.

Crea conjuntos de tests en el módulo de test llamando a module.GetOrCreateSuite() y pasando el nombre del conjunto de tests.

Llama a suite.Close() cuando todos los tests relacionados en el conjunto hayan finalizado su ejecución.

Tests

Cada test se ejecuta dentro de un conjunto y debe terminar en uno de estos tres estados: TestStatus.Pass, TestStatus.Fail o TestStatus.Skip.

Un test puede tener opcionalmente información adicional como:

• Parámetros
• Atributos
• Información sobre errores
• Rasgos de test
• Datos de referencia

Crea tests en un conjunto llamando a suite.CreateTest() y pasando el nombre del test. Cuando un test finaliza, llama a test.Close() con uno de los estados predefinidos.

Ejemplo de código

El siguiente código representa un uso sencillo de la API:

con System.Reflection;
con 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();

Llama siempre a module.Close() o module.CloseAsync() al final para que todos los datos del test se envíen a Datadog.

Prácticas recomendadas

Nombre de la sesión de test DD_TEST_SESSION_NAME

Utiliza DD_TEST_SESSION_NAME para definir el nombre de la sesión de test y del grupo de tests relacionado. Algunos ejemplos de valores para esta etiqueta serían:

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

Si no se especifica DD_TEST_SESSION_NAME, el valor por defecto utilizado es una combinación de:

• Nombre del trabajo CI
• Comando utilizado para ejecutar los tests (como yarn test)

El nombre de la sesión de test debe ser único dentro de un repositorio para ayudar a distinguir diferentes grupos de tests.

Cuándo utilizar DD_TEST_SESSION_NAME

Hay un conjunto de parámetros que Datadog comprueba para establecer la correspondencia entre las sesiones de test. El comando de test utilizado para ejecutar los tests es uno de ellos. Si el comando de test contiene una cadena que cambia en cada ejecución, como una carpeta temporal, Datadog considera que las sesiones no están relacionadas entre sí. Por ejemplo:

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

Datadog recomienda utilizar DD_TEST_SESSION_NAME si tus comandos de test varían entre diferentes ejecuciones.

Referencias adicionales

Más enlaces, artículos y documentación útiles:

Reenvío de variables de entorno para tests en contenedoresDOCUMENTACIÓN Exploración de los resultados de tests y del rendimientoDOCUMENTACIÓN Acelerar tus tests con Test Impact AnalysisDOCUMENTACIÓN Solucionar problemas de Test OptimizationDOCUMENTACIÓN