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.
Instalación de la CLI del trazador de .NET
Instale o actualice el comando dd-trace usando una de las siguientes formas:
Para instrumentar su conjunto de pruebas, anteponga dd-trace ci run a su comando de prueba. Puede usar --dd-service para establecer el servicio o la biblioteca bajo prueba y --dd-env para establecer el entorno donde se ejecutan las pruebas. Por ejemplo:
dd-trace ci run --dd-service=my-dotnet-app -- VSTest.Console.exe {test_assembly}.dll
Todas las pruebas se instrumentan automáticamente.
Compatibilidad con el paquete nuget Microsoft.CodeCoverage
Desde Microsoft.CodeCoverage versión 17.2.0, Microsoft introdujo la instrumentación dinámica usando .NET CLR Profiling API habilitada de forma predeterminada solo en Windows. La instrumentación automática de Datadog depende de .NET CLR Profiling API. Esta API permite solo un suscriptor (por ejemplo, dd-trace). El uso de la instrumentación dinámica de CodeCoverage interrumpe la instrumentación automática de pruebas.
La solución es cambiar de la instrumentación dinámica a la instrumentación estática. Modifique su archivo .runsettings con las siguientes opciones de configuración:
<?xml version="1.0" encoding="utf-8"?><RunSettings><DataCollectionRunSettings><DataCollectors><DataCollectorfriendlyName="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>
Configuración de ajustes
Puede cambiar la configuración predeterminada de la CLI mediante argumentos de línea de comandos o variables de entorno. Para obtener una lista completa de los ajustes de configuración, ejecute:
dd-trace ci run --help
La siguiente lista muestra los valores predeterminados para los ajustes de configuración clave:
--dd-service (opcional)
Nombre del servicio o biblioteca bajo prueba. Variable de entorno: DD_SERVICE Predeterminado: El nombre del repositorio Ejemplo: my-dotnet-app
--dd-env (opcional)
Nombre del entorno donde se ejecutan las pruebas. Variable de entorno: DD_ENV Predeterminado: none Ejemplos: local, ci
--agent-url (Solo cuando se usa el Datadog Agent)
URL del Datadog Agent para la recopilación de trazas, en el formato http://hostname:port. Variable de entorno: DD_TRACE_AGENT_URL Predeterminado: http://localhost:8126
test_session.name (Solo disponible como variable de entorno)
Identifica un grupo de pruebas, como unit-tests, integration-tests o smoke-tests. Variable de entorno: DD_TEST_SESSION_NAME Predeterminado: El nombre del trabajo de CI y el comando de prueba, o el comando de prueba si el nombre del trabajo de CI no está disponible. Ejemplo: unit-tests, integration-tests, smoke-tests
Puede agregar etiquetas personalizadas a sus pruebas utilizando el tramo activo actual:
// inside your testvarscope=Tracer.Instance.ActiveScope;// from Datadog.Trace;if(scope!=null){scope.Span.SetTag("test_owner","my_team");}// test continues normally// ...
Para crear filtros o group by campos para estas etiquetas, primero debe crear facetas. Para obtener más información sobre cómo agregar etiquetas, consulte la sección Adding Tags de la documentación de instrumentación personalizada de .NET.
Al igual que con las etiquetas, puede agregar medidas personalizadas a sus pruebas utilizando el tramo activo actual:
// inside your testvarscope=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 debe crear facetas. Para obtener más información sobre cómo agregar etiquetas, consulte la sección Adding Tags de la documentación de instrumentación personalizada de .NET.
Cuando Code Coverage está disponible, el trazador de Datadog (v2.31.0 o posterior) lo informa bajo la etiqueta test.code_coverage.lines_pct para sus sesiones de prueba.
Si está utilizando Coverlet para calcular su cobertura de código, indique la ruta al 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 formato OpenCover o Cobertura. Alternativamente, puede habilitar el cálculo de Code Coverage integrado del trazador de Datadog con la variable de entorno DD_CIVISIBILITY_CODE_COVERAGE_ENABLED=true.
Nota: Al usar Test Impact Analysis, el Code Coverage integrado del SDK se habilita de forma predeterminada.
Puede ver la evolución de Code Coverage en la pestaña Coverage de una sesión de prueba.
Para obtener más información sobre las opciones de exclusión, consulte Code Coverage.
Instrumentación de pruebas de BenchmarkDotNet
Para instrumentar sus pruebas de referencia, necesita:
Configure su proyecto para usar el exportador Datadog.Trace.BenchmarkDotNet usando el atributo DatadogDiagnoser o el método de extensión WithDatadog(). Por ejemplo:
Ejecute el proyecto de referencia como lo hace normalmente; todas las pruebas 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
Nota: La configuración de su instrumentación personalizada depende de la dd-trace versión. Para usar la instrumentación personalizada, debe mantener las versiones de los paquetes de dd-trace y Datadog.Trace NuGet sincronizadas.
Para usar la instrumentación personalizada en su aplicación .NET:
Ejecute dd-trace --version para obtener la versión de la herramienta.
Agregue el Datadog.Tracepaquete NuGet con la misma versión a su aplicación.
En el código de su aplicación, acceda al rastreador global a través de la propiedad Datadog.Trace.Tracer.Instance para crear nuevos tramos.
Nota: Para usar la API de pruebas manuales, debe agregar el Datadog.Trace paquete NuGet en el proyecto de .NET de destino.
Si utiliza XUnit, NUnit o MSTest con sus proyectos .NET, Test Optimization los instrumenta automáticamente y envía los resultados de las pruebas a Datadog. Si utiliza un marco de pruebas no compatible o si tiene un mecanismo de prueba diferente, puede utilizar la API para informar los resultados de las pruebas a Datadog.
La API se basa en tres conceptos: módulo de prueba, conjuntos de pruebas y pruebas.
Módulo de prueba
Un módulo de prueba representa el ensamblado de .NET que incluye las pruebas.
Para iniciar un módulo de prueba, llame a TestModule.Create() y pase el nombre del módulo o el nombre del ensamblado de .NET donde se encuentran las pruebas.
Cuando todas sus pruebas hayan finalizado, llame a module.Close() o module.CloseAsync(), lo cual fuerza a la biblioteca a enviar todos los resultados de prueba restantes al backend.
Conjuntos de pruebas
Un conjunto de pruebas comprende un conjunto de pruebas. Pueden tener métodos comunes de inicialización y finalización y compartir algunas variables. En .NET, generalmente se implementan como una clase de prueba o accesorio que contiene múltiples métodos de prueba. Un conjunto de pruebas puede tener opcionalmente información adicional como atributos o información de error.
Cree conjuntos de pruebas en el módulo de prueba llamando a module.GetOrCreateSuite() y pasando el nombre del conjunto de pruebas.
Llame a suite.Close() cuando todas las pruebas relacionadas en el conjunto hayan finalizado su ejecución.
Pruebas
Cada prueba se ejecuta dentro de un conjunto de pruebas y debe terminar en uno de estos tres estados: TestStatus.Pass, TestStatus.Fail o TestStatus.Skip.
Una prueba puede tener opcionalmente información adicional como:
Parámetros
Atributos
Información de error
Características de la prueba
Datos de referencia
Cree pruebas en un conjunto de pruebas llamando a suite.CreateTest() y pasando el nombre de la prueba. Cuando una prueba finalice, llame a test.Close() con uno de los estados predefinidos.
Ejemplo de código
El siguiente código representa un uso simple de la API:
Llame siempre a module.Close() o module.CloseAsync() al final para que todos los datos de prueba se envíen a Datadog.
Mejores prácticas
Nombre de la sesión de prueba DD_TEST_SESSION_NAME
Use DD_TEST_SESSION_NAME para definir el nombre de la sesión de prueba y el grupo de pruebas relacionado. 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 predeterminado es el nombre del trabajo de CI y el comando de prueba. Si el nombre del trabajo de CI no está disponible, se utiliza el comando de prueba.
El nombre de la sesión de prueba debe ser único dentro de un repositorio para ayudarle a distinguir diferentes grupos de pruebas.
Cuándo usar DD_TEST_SESSION_NAME
Existe un conjunto de parámetros que Datadog verifica para establecer la correspondencia entre las sesiones de prueba. El comando de prueba utilizado para ejecutar las pruebas es uno de ellos. Si el comando de prueba 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 usar DD_TEST_SESSION_NAME si sus comandos de prueba varían entre ejecuciones.
Lecturas adicionales
Documentación, enlaces y artículos útiles adicionales: