Compatibilidad

Frameworks para tests compatibles:

La instrumentación funciona en tiempo de ejecución, por lo que cualquier transpilador como TypeScript, Webpack o Babel es compatible desde el primer momento.

Configuración del método de notificación

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

Instalación del rastreador de JavaScript

Para instalar el JavaScript Tracer, ejecuta:

yarn add --dev dd-trace

Para obtener más información, consulta la Documentación sobre la instalación de JavaScript Tracer.

Instrumenta tus tests

NODE_OPTIONS="-r dd-trace/ci/init" DD_TEST_SESSION_NAME=unit-tests yarn test

{
  "scripts": {
    "test": "NODE_OPTIONS=\"--max-old-space-size=12288 ${NODE_OPTIONS:-}\" jest"
  }
}

  it('sum function can sum', () => {
    const testSpan = require('dd-trace').scope().active()
    testSpan.setTag('team_owner', 'my_team')
    // test continues normally
    // ...
  })

  it('sum function can sum', () => {
    const testSpan = require('dd-trace').scope().active()
    testSpan.setTag('memory_allocations', 16)
    // test continues normally
    // ...
  })

NODE_OPTIONS="-r dd-trace/ci/init" DD_TEST_SESSION_NAME=e2e-tests yarn test:e2e

{
  "scripts": {
    "test": "NODE_OPTIONS=\"--max-old-space-size=12288 ${NODE_OPTIONS:-}\" jest"
  }
}

test('user profile', async ({ page }) => {
  test.info().annotations.push({
    type: 'DD_TAGS[test.memory.usage]', // DD_TAGS is mandatory and case sensitive
    description: 'low',
  });
  test.info().annotations.push({
    type: 'DD_TAGS[test.task.id]',
    description: '41123',
  });
  // ...
});

test('landing page', async ({ page }) => {
  test.info().annotations.push({
    type: 'DD_TAGS[test.cpu.usage]',
    description: 'high',
  });
  // ...
});

{
  "type": "DD_TAGS[$TAG_NAME]",
  "description": "$TAG_VALUE"
}

test('user profile', async ({ page }) => {
  test.info().annotations.push({
    type: 'DD_TAGS[test.memory.allocations]', // DD_TAGS is mandatory and case sensitive
    description: 16, // this is a number
  });
});

{
  "type": "DD_TAGS[$TAG_NAME]",
  "description": $TAG_VALUE
}

NODE_OPTIONS="-r dd-trace/ci/init" DD_TEST_SESSION_NAME=integration-tests yarn test:integration

{
  "scripts": {
    "test": "NODE_OPTIONS=\"--max-old-space-size=12288 ${NODE_OPTIONS:-}\" jest"
  }
}

  When('the function is called', function () {
    const stepSpan = require('dd-trace').scope().active()
    testSpan.setTag('team_owner', 'my_team')
    // test continúa normalment
    // ...
  })

  When('the function is called', function () {
    const stepSpan = require('dd-trace').scope().active()
    testSpan.setTag('memory_allocations', 16)
    // test continues normally
    // ...
  })

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    setupNodeEvents: require('dd-trace/ci/cypress/plugin'),
    supportFile: 'cypress/support/e2e.js'
  }
})

// Tu código puede ir antes de esta línea
// require('./commands')
require('dd-trace/ci/cypress/support')
// También compatible:
// import 'dd-trace/ci/cypress/support'
// Tu código también puede ir después de esta línea
// Cypress.Commands.add('login', (email, pw) => {})

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      // tu código anterior está antes de esta línea
      return require('dd-trace/ci/cypress/plugin')(on, config)
    }
  }
})

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      require('dd-trace/ci/cypress/plugin')(on, config)
      // otros complementos
      on('after:run', (details) => {
        // otros manejadores 'after:run'
        // importante que se devuelva esta función
        return require('dd-trace/ci/cypress/after-run')(details)
      })
    }
  }
})

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      require('dd-trace/ci/cypress/plugin')(on, config)
      // otros complementos
      on('after:spec', (...args) => {
        // otros manejadores 'after:spec'
        // Importante que se devuelva esta función
        // Importante que todos los argumentos se pasen
        return require('dd-trace/ci/cypress/after-spec')(...args)
      })
    }
  }
})

{
  "pluginsFile": "dd-trace/ci/cypress/plugin"
}

module.exports = (on, config) => {
  // tu código anterior está antes de esta línea
  return require('dd-trace (traza)/ci/cypress/plugin')(on, config)
}

// Tu código puede estar antes de esta línea
// require('./commands')
require('dd-trace/ci/cypress/support')
// Tu código también puede estar después de esta línea
// Cypress.Commands.add('login', (email, pw) => {})

module.exports = (on, config) => {
  // tu código anterior va antes de esta línea
  require('dd-trace/ci/cypress/plugin')(on, config)
  on('after:run', (details) => {
    // otros manejadores 'after:run'
    // importante que se devuelva esta llamada a la función
    return require('dd-trace/ci/cypress/after-run')(details)
  })
}

module.exports = (on, config) => {
  // tu código anterior va antes de esta línea
  require('dd-trace/ci/cypress/plugin')(on, config)
  on('after:spec', (...args) => {
    // otros manejadores 'after:spec'
    // Importante que se devuelva esta llamada a la función
    // Importante que todos los argumentos se pasen
    return require('dd-trace/ci/cypress/after-run')(...args)
  })
}

DD_TEST_SESSION_NAME=ui-tests yarn test:ui

beforeEach(() => {
  cy.task('dd:addTags', {
    'before.each': 'certain.information'
  })
})
it('renders a hello world', () => {
  cy.task('dd:addTags', {
    'team.owner': 'ui'
  })
  cy.get('.hello-world')
    .should('have.text', 'Hello World')
})

it('renders a hello world', () => {
  cy.task('dd:addTags', {
    'memory_allocations': 16
  })
  cy.get('.hello-world')
    .should('have.text', 'Hello World')
})

NODE_OPTIONS="--import dd-trace/register.js -r dd-trace/ci/init" DD_TEST_SESSION_NAME=smoke-tests yarn test:smoke

{
  "scripts": {
    "test": "NODE_OPTIONS=\"--max-old-space-size=12288 ${NODE_OPTIONS:-}\" vitest run"
  }
}

Cómo solucionar los errores “No se encuentra el módulo ‘dd-trace/ci/init’”.

Al utilizar dd-trace, es posible que aparezca el siguiente mensaje de error:

 Error: Cannot find module 'dd-trace/ci/init'

Esto puede deberse a un uso incorrecto de NODE_OPTIONS.

Por ejemplo, si tu acción de GitHub tiene este aspecto:

jobs:
  my-job:
    name: Run tests
    runs-on: ubuntu-latest
    # Invalid NODE_OPTIONS
    env:
      NODE_OPTIONS: -r dd-trace/ci/init
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3
      - name: Install node
        uses: actions/setup-node@v3
      - name: Install dependencies
        run: npm install
      - name: Run tests
        run: npm test

Nota: Esto no funciona porque NODE_OPTIONS es interpretado por cada proceso de nodo, incluido npm install. Si intentas importar dd-trace/ci/init antes de que esté instalado, este paso falla.

Tu acción de GitHub debería tener este aspecto:

jobs:
  my-job:
    name: Run tests
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3
      - name: Install node
        uses: actions/setup-node@v3
      - name: Install dependencies
        run: npm install
      - name: Run tests
        run: npm test
        env:
          NODE_OPTIONS: -r dd-trace/ci/init

Sigue estas prácticas recomendadas:

• Asegúrate de que la variable de entorno NODE_OPTIONS solo está configurada en el proceso que ejecuta los tests.
• En concreto, evita definir NODE_OPTIONS en la configuración de variables globales de entorno en la definición de tu proceso o trabajo.

Con Yarn 2 o posterior

Si utilizas yarn>=2 y un archivo .pnp.cjs, también puedes obtener el mismo error:

 Error: Cannot find module 'dd-trace/ci/init'

Puedes solucionarlo configurando NODE_OPTIONS de la siguiente manera:

NODE_OPTIONS="-r $(pwd)/.pnp.cjs -r dd-trace/ci/init" yarn test

Informar sobre la cobertura del código

Cuando los tests se instrumentan con Istambul, el rastreador de Datadog (v3.20.0 o posterior) informa de ello en la etiqueta test.code_coverage.lines_pct para tus sesiones de test.

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, consulta Cobertura del código.

Ajustes de configuración

A continuación, se muestra una lista de los ajustes más importantes de configuración que se pueden utilizar con el rastreador.

test_session.name

Se utiliza para identificar un grupo de tests, como integration-tests, unit-tests o smoke-tests.
Variable de entorno: DD_TEST_SESSION_NAME
Predeterminado: (nombre del job (generic) de integración continua + comando de test)
Ejemplo: unit-tests, integration-tests, smoke-tests

service

nombre del servicio o biblioteca en proceso de test.
**Variable de entorno **: DD_SERVICE
Por defecto: (nombre del framework de test)
Ejemplo: my-ui

env

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

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

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

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

API para tests manuales

Si utilizas Jest, Mocha, Cypress, Playwright, Cucumber o Vitest, no utilices la API de tests manuales, ya que Test Optimization (optimización de tests) los instrumenta automáticamente y envía los resultados de los tests a Datadog. La API de test manual es incompatible con los frameworks de tests ya admitidos.

Utiliza la API de tests manuales solo si utilizas un framework de test no compatible o tienes un mecanismo de test diferente.

La API de tests manuales aprovecha el módulo node:diagnostics_channel de Node.js y se basa en canales en los que se puede publicar:

const { channel } = require('node:diagnostics_channel')

const { describe, test, beforeEach, afterEach, assert } = require('my-custom-test-framework')

const testStartCh = channel('dd-trace:ci:manual:test:start')
const testFinishCh = channel('dd-trace:ci:manual:test:finish')
const testSuite = __filename

describe('can run tests', () => {
  beforeEach((testName) => {
    testStartCh.publish({ testName, testSuite })
  })
  afterEach((status, error) => {
    testFinishCh.publish({ status, error })
  })
  test('first test will pass', () => {
    assert.equal(1, 1)
  })
})

Canal de inicio del test

Toma este canal por su ID dd-trace:ci:manual:test:start para publicar que se está iniciando un test. Un buen lugar para hacer esto es un hook beforeEach o similar.

const { channel } = require('node:diagnostics_channel')
const testStartCh = channel('dd-trace:ci:manual:test:start')

// ... el código para tu framework de test va aquí
  beforeEach(() => {
    const testDefinition = {
      testName: 'a-string-that-identifies-this-test',
      testSuite: 'what-suite-this-test-is-from.js'
    }
    testStartCh.publish(testDefinition)
  })
// el código para tu framework de test continúa aquí ...

La carga útil que se va a publicar tiene los atributos testName y testSuite, ambos cadenas, que identifican el test que está a punto de comenzar.

Canal de finalización del test

Toma este canal por su ID dd-trace:ci:manual:test:finish para publicar que se está finalizando un test. Un buen lugar para hacer esto es un hook afterEach o similar.

const { channel } = require('node:diagnostics_channel')
const testFinishCh = channel('dd-trace:ci:manual:test:finish')

// ... el código para tu framework de test va aquí
  afterEach(() => {
    const testStatusPayload = {
      status: 'fail',
      error: new Error('assertion error')
    }
    testStartCh.publish(testStatusPayload)
  })
// el código para tu framework de test continúa aquí ...

La carga útil que se va a publicar tiene los atributos status y error:

• status es una cadena que toma uno de tres valores:

  • 'pass' cuando se supera un test.
  • 'fail' cuando falla un test.
  • 'skip' cuando se ha omitido un test.

• error es un objeto Error que contiene la razón por la que ha fallado un test.

Añadir etiquetas de canal

Toma este canal por su ID dd-trace:ci:manual:test:addTags para publicar que un test necesita etiquetas personalizadas. Esto puede hacerse dentro de la función de test:

const { channel } = require('node:diagnostics_channel')
const testAddTagsCh = channel('dd-trace:ci:manual:test:addTags')

// ... el código para tu framework de test va aquí
  test('can sum', () => {
    testAddTagsCh.publish({ 'test.owner': 'my-team', 'number.assertions': 3 })
    const result = sum(2, 1)
    assert.equal(result, 3)
  })
// el código para tu framework de test continúa aquí ...

La carga útil que se publica es un diccionario <string, string|number> de etiquetas o medidas que se añaden al test.

Ejecutar los tests

Cuando los canales de inicio y fin del test estén en tu código, ejecuta tu framework de test como lo haces normalmente, incluyendo las siguientes variables de entorno:

NODE_OPTIONS="-r dd-trace/ci/init" DD_TEST_SESSION_NAME=custom-tests yarn run-my-test-framework

Limitaciones conocidas

Tests de navegador

Los tests de navegador ejecutados con mocha, jest, cucumber, cypress, playwright y vitest son instrumentados por dd-trace-js, pero la visibilidad de la sesión del navegador en sí no se proporciona por defecto (por ejemplo, llamadas de red, acciones del usuario, cargas de páginas, etc.).

Si deseas tener visibilidad del proceso del navegador, considera el uso de RUM y repetición de sesión. Cuando se utiliza Cypress o Playwright, los resultados de test y sus sesiones de navegador de RUM generadas y las repeticiones de sesión se vinculan automáticamente. Para obtener más información, consulta la Guía para Instrumentar tus tests del navegador con RUM.

Modo interactivo de Cypress

El modo interactivo de Cypress (al que puedes entrar ejecutando cypress open) no es compatible con Test Optimization (optimización de tests) porque algunos eventos de cypress, como before:run, no se disparan. Si deseas probarlo de todas formas, pasa experimentalInteractiveRunEvents: true al archivo de configuración de cypress.

--workerThreads de Jest

La opción workerThreads de Jest no es compatible.

test.concurrent de Jest

test.concurrent de Jest no es compatible.

--forceExit de Jest

La opción –forceExit de Jest puede provocar la pérdida de datos. Datadog intenta enviar datos inmediatamente después de que finalicen tus tests, pero el cierre abrupto del proceso puede hacer que fallen algunas solicitudes. Utiliza --forceExit con precaución.

--exit de Mocha

La opción –exit de Mocha puede provocar la pérdida de datos. Datadog intenta enviar los datos inmediatamente después de que finalicen tus tests, pero el cierre abrupto del proceso puede hacer que fallen algunas solicitudes. Utiliza --exit con precaución.

Modo navegador de Vitest

El modo navegador de Vitest no es compatible.

Prácticas recomendadas

Siga estas prácticas para aprovechar al máximo el framework testing y la optimización de test (optimización de tests).

Tests parametrizados

Siempre que sea posible, aprovecha las herramientas que ofrecen los frameworks de test para realizar tests parametrizados. Por ejemplo, para jest:

Evita esto:

[[1,2,3], [3,4,7]].forEach((a,b,expected) => {
  test('sums correctly', () => {
    expect(a+b).toEqual(expected)
  })
})

Y usa test.each en su lugar:

test.each([[1,2,3], [3,4,7]])('sums correctly %i and %i', (a,b,expected) => {
  expect(a+b).toEqual(expected)
})

Para mocha, utiliza mocha-each:

const forEach = require('mocha-each');
forEach([
  [1,2,3],
  [3,4,7]
])
.it('adds %i and %i then returns %i', (a,b,expected) => {
  expect(a+b).to.equal(expected)
});

Cuando se utiliza este enfoque, tanto el framework de testing como test Optimization (optimización de tests) pueden distinguir sus tests.

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 predeterminado utilizado es una combinación de:

• Nombre del job (generic) de CI
• Comando utilizado para ejecutar los tests (como yarn test)

El nombre de la sesión de tests debe ser único dentro de un repositorio para ayudarte 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:

• yarn test --temp-dir=/var/folders/t1/rs2htfh55mz9px2j4prmpg_c0000gq/T
• pnpm vitest --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 Acelera tus jobs (generic) de test con el análisis del efecto de los testsDOCUMENTACIÓN Solucionar problemas de Test Optimization (optimización de tests)DOCUMENTACIÓN