Compatibilidad

Lenguajes compatibles:

Plataformas compatibles:

Instalación del SDK para tests Swift

Existen tres maneras de instalar el marco para tests:

Uso de un proyecto Xcode

1. Añade el paquete dd-sdk-swift-testing localizado en https://github.com/DataDog/dd-sdk-swift-testing a tu proyecto.

2. Vincula tus objetivos de tests con la biblioteca DatadogSDKTesting del paquete.

3. Si ejecutas tests de interfaz de usuario, vincula también la aplicación que ejecuta los tests con la biblioteca.

Uso de un proyecto Swift Package

1. Añade dd-sdk-swift-testing a la matriz de dependencias de tu paquete. Por ejemplo:

Copy

.package(url: "https://github.com/DataDog/dd-sdk-swift-testing.git", from: "2.2.0")

2. Para añadir el marco para tests a las dependencias de tus objetivos de tests añade la siguiente línea a la matriz de dependencias de tus objetivos de tests:

Copy

.product(name: "DatadogSDKTesting", package: "dd-sdk-swift-testing")

3. Si ejecutas tests de interfaz de usuario, añade también la dependencia a tus aplicaciones que ejecutan los tests.

1. Añade la dependencia DatadogSDKTesting a los objetivos de tests de tu Podfile:

Copy

target 'MyApp' do
  # ...

  target 'MyAppTests' do
    inherit! :search_paths
    pod 'DatadogSDKTesting'
  end
end

2. Si ejecutas tests de interfaz de usuario, añade también la dependencia a la aplicación que ejecuta los tests.

1. Descarga y descomprime DatadogSDKTesting.zip desde la página de la versión.

2. Copia y vincula tus objetivos de tests con el XCFramework resultante.

3. Si ejecutas tests de interfaz de usuario, vincula también la aplicación que ejecuta los tests con esta biblioteca.

Si utilizas GitHub, puedes utilizar la acción para tests de Swift del Marketplace de GitHub para configurar y ejecutar tus tests automáticamente. Por defecto, es posible omitir el resto de la configuración descrita en esta página (excepto la configuración de la acción misma), aunque puedes utilizar las variables de entorno de configuración para deshabilitar o configurar funcionalidades adicionales.

En comparación con otros métodos, como la vinculación de Cocoapods and Framework, puede que la opción de la acción para tests de Swift presente una configuración y una ejecución menos flexibles, pero no requiere cambios de código.

Instrumentación de tus pruebas

Configuración de Datadog

Uso del proyecto Xcode

Para habilitar la instrumentación de los tests añade las siguientes variables de entorno a tu objetivo de test o al archivo Info.plist, como se describe a continuación. Si estás utilizando planes de tests, debes seleccionar tu objetivo principal en Expand variables based on o Target for Variable Expansion:

Para los tests de interfaz de usuario, las variables de entorno sólo deben configurarse en el objetivo del test, ya que el marco inyecta automáticamente estos valores en la aplicación.

Uso del proyecto Swift Package

Para habilitar la instrumentación de los tests debes configurar las siguientes variables de entorno en tu ejecución de línea de comandos para los tests. También puedes configurarlas en el entorno, antes de ejecutar los tests, o puedes anteponerlas al siguiente comando:

DD_TEST_RUNNER=1 DD_API_KEY= DD_APPLICATION_KEY= DD_SITE=us1 SRCROOT=$PWD swift test ...

or

DD_TEST_RUNNER=1 DD_API_KEY= DD_APPLICATION_KEY= DD_SITE=us1 SRCROOT=$PWD xcodebuild test -scheme ...

Configura todas estas variables en tu objetivo de test:

DD_TEST_RUNNER

Habilita o deshabilita la instrumentación de los tests. Define este valor en $(DD_TEST_RUNNER) para poder habilitar o deshabilitar la instrumentación de los tests con una variable de entorno definida fuera del proceso de test (por ejemplo, en la compilación CI).
Por defecto: false
Recomendado: $(DD_TEST_RUNNER)

DD_API_KEY

La clave de API de Datadog utilizada para cargar los resultados de los tests.
Por defecto: (empty)

DD_APPLICATION_KEY

La clave de aplicación de Datadog utilizada para cargar los resultados de los tests.
Por defecto: (empty)

DD_SERVICE

El nombre del servicio o la biblioteca a los que se realizan tests.
Por defecto: El nombre del repositorio.
Ejemplo: my-ios-app

DD_ENV

El nombre del entorno donde se ejecutan los tests. Configura este valor como $(DD_ENV) para poder utilizar una variable de entorno en tiempo de ejecución para configurarlo.
Por defecto: none
Recomendado: $(DD_ENV)
Ejemplos: ci, local

SRCROOT

La ruta de localización del proyecto. Si utilizas Xcode, utiliza $(SRCROOT) para el valor, ya que se define automáticamente por él.
Por defecto: (empty)
Recomendado: $(SRCROOT)
Ejemplo: /Users/ci/source/MyApp

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

Además, configura el sitio Datadog para utilizar el sitio () seleccionado:

DD_SITE (Obligatorio)

El sitio Datadog al que cargar los resultados.
Por defecto: datadoghq.com
Sitio seleccionado:

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

Ejecución de tests

Después de la instalación, ejecuta tus tests como lo haces normalmente; por ejemplo, utilizando el comando xcodebuild test. Los tests, las solicitudes de red y los fallos de aplicaciones se instrumentan automáticamente. Cuando ejecutes tus tests en el CI, pasa tus variables de entorno, por ejemplo:

DD_TEST_RUNNER=1 DD_ENV=ci DD_SITE= xcodebuild \
  -project "MyProject.xcodeproj" \
  -scheme "MyScheme" \
  -destination "platform=macOS,arch=x86_64" \
  test

Tests de interfaz de usuario

En el caso de los tests de interfaz de usuario, tanto el objetivo del test como la aplicación que se ejecuta desde tests de interfaz de usuario, deben vincularse con el marco. Las variables de entorno sólo deben configurarse en el objetivo del test, ya que el marco inyecta automáticamente estos valores en la aplicación.

Integración RUM

Si la aplicación que se está probando está instrumentada con RUM, los resultados de los tests de interfaz de usuario y las sesiones RUM generadas se vinculan automáticamente. Para obtener más información sobre RUM, consulta la guía de la integración RUM iOS. Se necesita una versión 1.10 o anterior de RUM iOS.

Configuración opcional adicional

Para los siguientes parámetros de configuración:

• Las variables Boolean pueden utilizar cualquiera de los siguientes valores: 1, 0, true, false, YES o NO
• Las variables de lista de String aceptan una lista de elementos separados por , o ;

Habilitación de la instrumentación automática

DD_ENABLE_STDOUT_INSTRUMENTATION

Captura los mensajes escritos en stdout (por ejemplo, print()) y los notifica en forma de logs. Esto puede afectar a tu factura. (Booleano)

DD_ENABLE_STDERR_INSTRUMENTATION

Captura los mensajes escritos en stderr (por ejemplo, NSLog(), pasos de test de interfaz de usuario) y los notifica en forma de logs. Esto puede afectar a tu factura. (Booleano)

Deshabilitación de la instrumentación automática

El marco habilita la instrumentación automática de todas los bibliotecas compatibles, pero en algunos casos puede que no quieras que esto ocurra. Puedes deshabilitar la instrumentación automática de algunas bibliotecas configurando las siguientes variables de entorno (o en el archivo Info.plist como se describe a continuación):

DD_DISABLE_NETWORK_INSTRUMENTATION

Deshabilita la instrumentación de toda la red. (Booleano)

DD_DISABLE_RUM_INTEGRATION

Deshabilita la integración con sesiones RUM. (Booleano)

DD_DISABLE_SOURCE_LOCATION

Deshabilita la localización y los codeowners del código de la fuente de los tests. (Booleano)

DD_DISABLE_CRASH_HANDLER

Deshabilita la gestión y la notificación de fallos. (Booleano)

Instrumentación automática de la red

Para la instrumentación automática de la red, puedes configurar los siguientes parámetros adicionales:

DD_DISABLE_HEADERS_INJECTION

Deshabilita cualquier inyección de cabeceras de rastreo. (Booleano)

DD_INSTRUMENTATION_EXTRA_HEADERS

Las cabeceras adicionales específicas que quieres registrar. (Lista de cadenas)

DD_EXCLUDED_URLS

Las URL que no quieres registrar o en las que no quieres inyectar cabeceras. (Lista de cadenas)

DD_ENABLE_RECORD_PAYLOAD

Permite informar un subconjunto (1024 bytes) de cargas útiles en las solicitudes y respuestas. (Booleano)

DD_MAX_PAYLOAD_SIZE

Define el tamaño máximo informado de la carga útil. Por defecto 1024. (Entero)

DD_DISABLE_NETWORK_CALL_STACK

Deshabilita la información de las llamadas del stack tecnológico en los tramos de la red. (Booleano)

DD_ENABLE_NETWORK_CALL_STACK_SYMBOLICATED

Muestra la información de las llamadas del stack tecnológico no sólo con el nombre del método, sino también con la información precisa del archivo y la línea. Puede afectar al rendimiento de los tests. (Booleano)

Correlación de tests con la infraestructura

Si estás ejecutando tests en tu propia infraestructura (tests de macOS o simulador), puedes correlacionar tus tests con las métricas de tu infraestructura instalando el Datadog Agent y configurando lo siguiente:

DD_CIVISIBILITY_REPORT_HOSTNAME

Informa del nombre de host de la máquina que inicia los tests. (Booleano)

También puedes deshabilitar o habilitar una instrumentación automática determinada en algunos de los tests de Swift o Objective-C, importando el módulo DatadogSDKTesting y utilizando la clase: DDInstrumentationControl.

Etiquetas personalizadas

Variables de entorno

Puedes utilizar la variable de entorno DD_TAGS (o en el archivo Info.plist como se describe a continuación). Debe contener pares de key:tag separados por espacios. Por ejemplo:

DD_TAGS=tag-key-0:tag-value-0 tag-key-1:tag-value-1

Si uno de los valores empieza con el carácter $, se sustituye por una variable de entorno con el mismo nombre (si existe). Por ejemplo:

DD_TAGS=home:$HOME

El uso del carácter $ también permite sustituir una variable de entorno al principio de un valor si contiene caracteres no compatibles con la variable de entorno (a-z, A-Z o _). Por ejemplo:

FOO = BAR
DD_TAGS=key1:$FOO-v1 // expected: key1:BAR-v1

OpenTelemetry

Nota: El uso de OpenTelemetry sólo es compatible con Swift.

El marco para tests Swift de Datadog utiliza OpenTelemetry como la tecnología de rastreo subyacente. Puedes acceder al rastreador OpenTelemetry utilizando DDInstrumentationControl.openTelemetryTracer y utilizar cualquier API de OpenTelemetry. Por ejemplo, para añadir una etiqueta o un atributo:

import DatadogSDKTesting
import OpenTelemetryApi

let tracer = DDInstrumentationControl.openTelemetryTracer as? Tracer
let span = tracer?.spanBuilder(spanName: "ChildSpan").startSpan()
span?.setAttribute(key: "OTTag2", value: "OTValue2")
span?.end()

El objetivo de test debe vincularse explícitamente con opentelemetry-swift.

Informes sobre la cobertura del código

Cuando la cobertura del código está disponible, el SDK de Datadog (v2.2.7 y posteriores) lo informa mediante la etiqueta test.code_coverage.lines_pct para tus sesiones de tests.

En Xcode, puedes habilitar el informe de cobertura del código en tu esquema 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.

Uso de Info.plist para la configuración

Como alternativa a la configuración de variables de entorno, se pueden proporcionar todos los valores de configuración añadiéndolos al archivo Info.plist del paquete de tests (no del paquete de aplicaciones). Si se define la misma configuración, tanto en una variable de entorno como en el archivo Info.plist, la variable de entorno tiene prioridad.

Variables de entorno del proveedor de IC

API para tests manuales

Si utilizas XCTests en tus proyectos Swift, el marco DatadogSDKTesting los instrumenta automáticamente y envía los resultados al backend de Datadog. Si no utilizas XCTest, puedes utilizar la API para tests manuales Swift/Objective-C, que también informa de los resultados de los tests al backend.

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

Módulo de test

Un módulo de test representa la carga de una biblioteca o un paquete que incluye los tests.

Para iniciar un módulo de test, llama a DDTestModule.start() y pasa el nombre del módulo o el paquete al que se va a realizar el test.

Cuando todos tus tests hayan finalizado, llama a module.end(), que obliga a la biblioteca a enviar todos los resultados de los tests restantes al backend.

Conjuntos de tests

Un conjunto de tests incluye aquellos tests que comparten una funcionalidad común. Pueden compartir una inicialización y un desmontaje comunes, y también pueden compartir algunas variables.

Crea el conjunto de tests en el módulo de test llamando a module.suiteStart() y pasando el nombre del conjunto de tests.

Llama a suite.end() cuando todos los tests relacionados del conjunto hayan finalizado su ejecución.

Tests

Cada test se ejecuta dentro de conjunto y debe terminar en uno de estos tres estados: pass, fail o skip. Un test también puede contener información adicional, como atributos o información de errores.

Crea tests dentro de un conjunto llamando a suite.testStart() y pasando el nombre del test. Cuando finaliza un test, debe configurarse uno de los estados predefinidos.

API de interfaz

class DDTestModule {
    // Inicia el módulo.
    // - Parámetros:
    //   - bundleName: Nombre del módulo o el paquete al que se va a realizar un test.
    //   - startTime (opcional): Hora de inicio del módulo.
    static func start(bundleName: String, startTime: Date? = nil) -> DDTestModule
    //
    // Finaliza el módulo.
    // - Parámetros:
    //   - endTime (opcional): Hora de finalización del módulo.
    func end(endTime: Date? = nil)
    // Añade una etiqueta o un atributo al módulo de test. Se puede agregar cualquier número de etiquetas.
    // - Parámetros:
    //   - key: Nombre de la etiqueta. Si ya existe una etiqueta con el mismo nombre,
    //     se sustituirá su valor por uno nuevo.
    //   - value: Valor de la etiqueta. Puede ser un número o una cadena.
    func setTag(key: String, value: Any)
    //
    // Inicia un conjunto en este módulo.
    // - Parámetros:
    //   - name: Nombre del conjunto.
    //   - startTime (opcional): Hora de inicio del conjunto.
    func suiteStart(name: String, startTime: Date? = nil) -> DDTestSuite
}
    //
public class DDTestSuite : NSObject {
    // Finaliza el conjunto de tests.
    // - Parámetros:
    //   - endTime (opcional): Hora de finalización del conjunto.
    func end(endTime: Date? = nil)
    // Añade una etiqueta o un atributo al conjunto de tests. Se puede agregar cualquier número de etiquetas.
    // - Parámetros:
    //   - key: Nombre de la etiqueta. Si ya existe una etiqueta con el mismo nombre,
    //     se sustituirá su valor por uno nuevo.
    //   - value: Valor de la etiqueta. Puede ser un número o una cadena.
    func setTag(key: String, value: Any)
    //
    // Inicia un test en este conjunto.
    // - Parámetros:
    //   - name: Nombre del test.
    //   - startTime (opcional): Hora de inicio del test.
    func testStart(name: String, startTime: Date? = nil) -> DDTest
}
    //
public class DDTest : NSObject {
    // Añade una etiqueta o un atributo al test. Se puede agregar cualquier número de etiquetas.
    // - Parámetros:
    //   - key: Nombre de la etiqueta. Si ya existe una etiqueta con el mismo nombre,
    //     se sustituirá su valor por uno nuevo.
    //   - value: Valor de la etiqueta. Puede ser un número o una cadena.
    func setTag(key: String, value: Any)
    //
    // Añade información de errores al test. Un test sólo puede notificar una información de error..
    // - Parámetros:
    //   - type: Tipo de error que se va a informar.
    //   - message: Mensaje asociado al error.
    //   - callstack (opcional): El stack tecnológico de las llamadas asociado al error.
    func setErrorInfo(type: String, message: String, callstack: String? = nil)
    //
    // Finaliza el test.
    // - Parámetros:
    //   - status: Estado informado de este test.
    //   - endTime (opcional): Hora de finalización del test.
    func end(status: DDTestStatus, endTime: Date? = nil)
}
    //
// Posibles estados informados por un test:
enum DDTestStatus {
  // El test ha sido aprobado.
  case pass
  //
  //El test ha fallado.
  case fail
  //
  //El test se ha omitido.
  case skip
}

Ejemplo de código

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

import DatadogSDKTesting
let module = DDTestModule.start(bundleName: "ManualModule")
let suite1 = module.suiteStart(name: "ManualSuite 1")
let test1 = suite1.testStart(name: "Test 1")
test1.setTag(key: "key", value: "value")
test1.end(status: .pass)
let test2 = suite1.testStart(name: "Test 2")
test2.SetErrorInfo(type: "Error Type", message: "Error message", callstack: "Optional callstack")
test2.end(test: test2, status: .fail)
suite1.end()
let suite2 = module.suiteStart(name: "ManualSuite 2")
..
..
module.end()

Llama siempre a module.end() al finalizar, para que toda la información de los tests se envíe a Datadog.

Prácticas recomendadas

Sigue estas prácticas para aprovechar al máximo el marco para tests y CI Visibility.

Generación de archivos de símbolos durante la creación

Crea tu código en Xcode utilizando DWARF with dSYM File (o -Xswiftc -debug-info-format=dwarf si lo creas utilizando swift)

El marco para tests utiliza archivos de símbolos para algunas de sus funciones, entre ellas: simbolizar fallos, informar de la localización original de los tests e informar de los propietarios de códigos. Genera automáticamente el archivo de símbolos cuando se incrustan símbolos de depuración en los binarios, pero puede tardar un poco más en cargarse.

Deshabilitar el entorno aislado para tests de interfaz de usuario en macOS

En algunas versiones de Xcode, los paquetes de tests de interfaz de usuario se crean utilizando un entorno aislado por defecto. Los parámetros que vienen con un entorno aislado impiden que el marco para tests sea ejecutado por algunos comandos del sistema con xcrun, por lo que es necesario deshabilitarlo.

Deshabilita el entorno aislado añadiendo Privilegios al paquete del ejecutador de tests de interfaz de usuario y luego añadiendo App Sandbox = NO. También puedes crear un archivo de .entitlement y añadirlo a los parámetros de creación de firmas. Este archivo debe incluir el siguiente contenido:

<key>com.apple.security.app-sandbox</key>
 <false/>

Leer más

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

Explore los resultados de los tests y el rendimientoDOCUMENTACIÓN Para acelerar tus tests con Intelligent Test RunnerDOCUMENTACIÓN Solucionar problemas de CI VisibilityDOCUMENTACIÓN