Tests de Ruby

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

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

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