Compatibilidad

Lenguajes compatibles:

Marcos para tests compatibles:

Ejecutores de tests compatibles:

Configuración del método de notificación

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

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:

source "<https://rubygems.org>"
gem "datadog-ci", "~> 1.0", group: :test

2. Instala el gem ejecutando bundle install

Instrumentación de tus tests

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

DD_ENV=ci bundle exec rake spec

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

DD_ENV=ci bundle exec rake test

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

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

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:

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

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

Reenvío de variables entorno para tests en contenedoresDOCUMENTACIÓN Exploración de los resultados de tests y del rendimientoDOCUMENTACIÓN Solucionar problemas de CI VisibilityDOCUMENTACIÓN