En este momento, CI Visibility no está disponible en el sitio () seleccionado.

Compatibilidad

Lenguajes compatibles:

LenguajeVersión
Rubyv2.7 o anterior
JRubyv9.4 o anterior

Marcos para tests compatibles:

Marco para testsVersión
RSpecv3.0.0 o anterior
Minitestv5.0.0 o anterior
Cucumberv3.0 o anterior

Ejecutores de tests compatibles:

Ejecutor de testsVersión
Knapsack Prov7.2.0 o anterior
ci-queuev0.53.0 o anterior

Configuración del método de notificación

Para informar de resultados de tests a Datadog, necesitas configurar el gem datadog-ci:

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:

DD_CIVISIBILITY_AGENTLESS_ENABLED=true (Required)
Enables or disables Agentless mode.
Default: false
DD_API_KEY (Required)
The Datadog API key used to upload the test results.
Default: (empty)

Additionally, configure the Datadog site to which you want to send data.

DD_SITE (Required)
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 biblioteca de visibilidad de tests Ruby

Para instalar la biblioteca de visibilidad de tests Ruby:

  1. Añade el gem datadog-ci en tu Gemfile:

Gemfile

source "<https://rubygems.org>"
gem "datadog-ci", "~> 1.0", group: :test
  1. Instala el gem ejecutando bundle install

Instrumentación de tus tests

La integración RSpec rastrea todas las ejecuciones de ejemplos de grupos y ejemplos, cuando se utiliza el marco para tests rspec.

Para activar tu integración, añade lo siguiente al archivo spec_helper.rb:

require "rspec"
require "datadog/ci"

# Sólo activa la instrumentación de tests en CI
if ENV["DD_ENV"] == "ci"
  Datadog.configure do |c|
    # habilita la visibilidad de los tests
    c.ci.enabled = true

    # Nombre del servicio o de la biblioteca a los que se realizan tests
    c.service = "my-ruby-app"

    # Habilita la instrumentación RSpec
    c.ci.instrument :rspec
  end
end

Ejecuta tus tests como lo haces habitualmente, especificando el entorno en que se ejecutan los tests en la variable de entorno DD_ENV.

Puedes utilizar los siguientes entornos:

  • local cuando ejecutas tests en una estación de trabajo de desarrollador
  • ci cuando los ejecutas en un proveedor CI

Por ejemplo:

DD_ENV=ci bundle exec rake spec

La integración Minitest rastrea todas las ejecuciones de tests, cuando se utiliza el marco minitest.

Para activar tu integración, añade lo siguiente al archivo test_helper.rb:

require "minitest"
require "datadog/ci"

# Sólo activa la instrumentación de tests en CI
if ENV["DD_ENV"] == "ci"
  Datadog.configure do |c|
    # habilita la visibilidad de los tests
    c.ci.enabled = true

    # Nombre del servicio o de la biblioteca a los que se realizan tests
    c.service = "my-ruby-app"

    c.ci.instrument :minitest
  end
end

Ejecuta tus tests como lo haces habitualmente, especificando el entorno en el que se ejecutan los tests en la variable de entorno DD_ENV.

Puedes utilizar los siguientes entornos:

  • local cuando ejecutas tests en una estación de trabajo de desarrollador
  • ci cuando los ejecutas en un proveedor CI

Por ejemplo:

DD_ENV=ci bundle exec rake test
Nota: Cuando utilices `minitest/autorun`, asegúrate de que se te pida `datadog/ci` antes que `minitest/autorun`.

Ejemplo de configuración con minitest/autorun:

require "datadog/ci"
require "minitest/autorun"

if ENV["DD_ENV"] == "ci"
  Datadog.configure do |c|
    c.ci.enabled = true

    c.service = "my-ruby-app"

    c.ci.instrument :minitest
  end
end

La integración Cucumber rastrea ejecuciones de escenarios y pasos cuando se utiliza el marco cucumber.

Para activar tu integración, añade el siguiente código a tu aplicación:

require "cucumber"
require "datadog/ci"

# Sólo activa la instrumentación de tests en CI
if ENV["DD_ENV"] == "ci"
  Datadog.configure do |c|
    # habilita la visibilidad de los tests
    c.ci.enabled = true

    # Nombre del servicio o de la biblioteca a los que se realizan tests
    c.service = "my-ruby-app"

    # Habilita la instrumentación Cucumber
    c.ci.instrument :cucumber
  end
end

Ejecuta tus tests como lo haces habitualmente, especificando el entorno en que se ejecutan los tests en la variable de entorno DD_ENV. Puedes utilizar los siguientes entornos:

  • local cuando ejecutes tests en una estación de trabajo de desarrollador
  • ci cuando los ejecutes en un proveedor CI

Por ejemplo:

DD_ENV=ci bundle exec rake cucumber

Para añadir etiquetas (tags) personalizadas a los tests

Puedes añadir etiquetas personalizadas a tus tests utilizando el test que esté activo en ese momento:

require "datadog/ci"

# dentro de tu test
Datadog::CI.active_test&.set_tag("test_owner", "my_team")
# el test continúa normalmente
# ...

Para crear filtros o campos group by para estas etiquetas, primero debes crear facetas. Para obtener más información sobre cómo añadir etiquetas, consulta la sección Añadir etiquetas en la documentación de instrumentación personalizada de Ruby.

Añadir medidas personalizadas a los tests

Además de las etiquetas, también puedes añadir medidas personalizadas a tus tests utilizando el test que esté activo en ese momento:

require "datadog/ci"

# dentro de tu test
Datadog::CI.active_test&.set_metric("memory_allocations", 16)
# el test continúa normalmente
# ...

Para obtener más información sobre las medidas personalizadas, consulta la guía para añadir medidas personalizadas.

Parámetros de configuración

La siguiente es una lista de los parámetros de configuración más importantes que puedes utilizar con la biblioteca de visibilidad de tests, ya sea en código, utilizando un bloque Datadog.configure, o utilizando variables de entorno:

service
Nombre del servicio o de la biblioteca a los que se realizan tests.
Variable de entorno: DD_SERVICE
Por defecto: $PROGRAM_NAME
Ejemplo: my-ruby-app
env
Nombre del entorno en el que se ejecutan los tests.
**Variable de entorno **: DD_ENV
Por defecto: none
Ejemplos: local, ci

Para obtener más información sobre las etiquetas reservadas service y env, consulta Etiquetado unificado de servicios.

La siguiente variable de entorno puede utilizarse para configurar el localización del Datadog Agent:

DD_TRACE_AGENT_URL
La URL del Datadog Agent URL para recopilar trazas con el formato http://hostname:port.
Por defecto: http://localhost:8126

También puedes utilizar todas las demás opciones de configuración del Datadog Tracer.

Uso de la instrumentación adicional

Puede ser útil disponer de información de seguimiento enriquecida sobre tus tests que incluya el tiempo empleado en realizar operaciones con la base de datos u otras llamadas externas, como se muestra en el siguiente gráfico de llamas:

Rastreo de tests con Redis instrumentado

Para ello, configura la instrumentación adicional en tu bloque configure:

if ENV["DD_ENV"] == "ci"
  Datadog.configure do |c|
    #  ... configuraciones e instrumentación CI aquí ...
    c.tracing.instrument :redis
    c.tracing.instrument :pg
    # ... cualquier otra instrumentación compatible con el gem de Datadog ...
  end
end

También puedes habilitar la instrumentación automática en test_helper/spec_helper:

require "datadog/auto_instrument" if ENV["DD_ENV"] == "ci"

Nota: En modo CI, estas trazas (traces) se envían a CI Visibility y no aparecen en Datadog APM .

Para ver la lista de todos los métodos de instrumentación disponibles, consulta la documentación sobre rastreo.

Webmock/VCR

Webmock y VCR son populares bibliotecas Ruby que agregan stubs a las solicitudes HTTP cuando se ejecutan tests. Por defecto, fallan cuando se utilizan con datadog-ci porque se envían trazas a Datadog con llamadas HTTP.

Para permitir conexiones HTTP para el backend de Datadog, necesitas configurar Webmock y VCR en consecuencia.

# Webmock
# cuando se utiliza el modo Agentless:
WebMock.disable_net_connect!(:allow => /datadoghq/)

# cuando se utiliza el Agent y se lo ejecuta localmente:
WebMock.disable_net_connect!(:allow_localhost => true)

# o, para una configuración más específica, configura la URL de tu Agent. Por ejemplo:
WebMock.disable_net_connect!(:allow => "localhost:8126")

# VCR
VCR.configure do |config|
  # ... tu configuración habitual aquí ...

  # cuando se utiliza el Agent
  config.ignore_hosts "127.0.0.1", "localhost"

  # cuando se utiliza el modo Agentless
  config.ignore_request do |request|
    # ignora todas las solicitudes a hosts datadoghq
    request.uri =~ /datadoghq/
  end
end

Recopilación de metadatos 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

Uso de la API de tests manuales

Si utilizas RSpec, Minitest o Cucumber, no utilices la API de tests manuales, ya que CI Visibility los instrumenta automáticamente y envía los resultados a Datadog. La API de tests manuales es incompatible con los marcos para tests que ya son compatibles.

Utiliza la API de tests manuales sólo si utilizas un marco de tests no compatible o si tienes un mecanismo de test diferente. Toda la documentación de la API pública está disponible en el sitio YARD.

Modelo de dominio

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

Sesión de tests

Una sesión de tests representa la ejecución de un comando de test.

Para iniciar una sesión de tests, llama a Datadog::CI.start_test_session y pasa el servicio y las etiquetas de Datadog (como el marco de test que estás utilizando).

Cuando todos tus tests hayan terminado, llama a Datadog::CI::TestSession#finish. Esto cierra la sesión y envía la traza de la sesión al backend.

Módulo de test

Un módulo de test representa una unidad de trabajo más pequeña dentro de una sesión. Para los marcos para tests compatibles, el módulo de test es siempre igual a la sesión de tests. Para tu caso de uso, podría ser un paquete en tu aplicación componentizada.

Para iniciar un módulo de test, llama a Datadog::CI.start_test_module y pasa el nombre del módulo.

Una vez finalizada la ejecución del módulo, llama a Datadog::CI::TestModule#finish.

Conjunto de tests

Un conjunto de tests incluye un grupo de tests que comprueban funcionalidades similares. Un único conjunto suele corresponder a un único archivo en el que se definen los tests.

Crea conjuntos de tests llamando a Datadog::CI#start_test_suite y pasando el nombre del conjunto de tests.

Llama a Datadog::CI::TestSuite#finish cuando todos los tests relacionados del conjunto hayan terminado de ejecutarse.

Test

Un test representa un único caso de test que se ejecuta como parte de un conjunto de tests. Suele corresponder a un método que contiene la lógica de test.

Crea conjuntos de tests llamando a Datadog::CI#start_test o Datadog::CI.trace_test y pasando el nombre del test y el nombre del conjunto de tests. El nombre del conjunto de tests debe ser el mismo que el del conjunto de tests iniciado en el paso anterior.

Llama a Datadog::CI::Test#finish cuando una prueba haya terminado de ejecutarse.

Ejemplo de código

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

require "datadog/ci"

Datadog.configure do |c|
  c.service = "my-test-service"
  c.ci.enabled = true
end

def run_test_suite(tests, test_suite_name)
  test_suite = Datadog::CI.start_test_suite(test_suite_name)

  run_tests(tests, test_suite_name)

  test_suite.passed!
  test_suite.finish
end

def run_tests(tests, test_suite_name)
  tests.each do |test_name|
    Datadog::CI.trace_test(test_name, test_suite_name) do |test|
      test.passed!
    end
  end
end

Datadog::CI.start_test_session(
  tags: {
    Datadog::CI::Ext::Test::TAG_FRAMEWORK => "my-framework",
    Datadog::CI::Ext::Test::TAG_FRAMEWORK_VERSION => "0.0.1",
  }
)
Datadog::CI.start_test_module("my-test-module")

run_test_suite(["test1", "test2", "test3"], "test-suite-name")

Datadog::CI.active_test_module&.passed!
Datadog::CI.active_test_module&.finish

Datadog::CI.active_test_session&.passed!
Datadog::CI.active_test_session&.finish

Leer más