Compatibility

Supported languages:

Supported platforms:

Installing the Swift testing SDK

There are three ways you can install the testing framework:

Using Xcode Project

1. Add dd-sdk-swift-testing package to your project. It is located at https://github.com/DataDog/dd-sdk-swift-testing.

2. Link your test targets with the library DatadogSDKTesting from the package.

3. If you run UI Tests and don’t use RUM, also add the dependency to your applications running the tests.

Using Swift Package Project

1. Add dd-sdk-swift-testing to your package dependencies array, for example:

Copy

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

2. To add the testing framework to your testing targets’ dependencies, add the following line to your test targets dependencies array:

Copy

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

3. If you run UI Tests and don’t use RUM, also add the dependency to your applications running the tests.

1. Add the DatadogSDKTesting dependency to the test targets of your Podfile:

Copy

target 'MyApp' do
  # ...

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

2. If you run UI Tests and don’t use RUM, also add the dependency to the app running the tests.

1. Download and decompress DatadogSDKTesting.zip from the release page.

2. Copy and link your test targets with the resulting XCFramework.

3. If you run UI Tests and don’t use RUM, also link the app running the tests with this library.

Instrumenting your tests

Configuring SDK

Using Xcode Project

To enable testing instrumentation, add the following environment variables to your test target or in the Info.plist file as described below. You must select your main target in Expand variables based on or Target for Variable Expansion if you are using test plans:

For UI Tests, environment variables need to be set only in the test target, because the framework automatically injects these values to the application.

Using Swift Package Project

To enable testing instrumentation, you must set the following environment variables to your commandline execution for the tests. You can alternatively set them in the environment before running the tests or you can prepend them to the command:

DD_TEST_RUNNER=1 DD_API_KEY= SRCROOT=$PWD swift test ...

or

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

Set all these variables in your test target:

DD_TEST_RUNNER

Enables or disables the instrumentation of tests. Set this value to $(DD_TEST_RUNNER) so you can enable and disable test instrumentation with a environment variable defined outside of the test process (for example, in the CI build).
Default: false
Recommended: $(DD_TEST_RUNNER)

DD_API_KEY

The Datadog API key used to upload the test results.
Default: (empty)

DD_SERVICE

Name of the service or library under test.
Default: The repository name
Example: my-ios-app

DD_ENV

Name of the environment where tests are being run. Set this value to $(DD_ENV) so you can use an environment variable at runtime for setting it.
Default: none
Recommended: $(DD_ENV)
Examples: ci, local

SRCROOT

The path to the project location. If using Xcode, use $(SRCROOT) for the value, because it is automatically set by it.
Default: (empty)
Recommended: $(SRCROOT)
Example: /Users/ci/source/MyApp

For more information about service and env reserved tags, see Unified Service Tagging.

Additionally, configure the Datadog site to use the selected one ():

DD_SITE (Required)

The Datadog site to upload results to.
Default: datadoghq.com
Selected site:

Collecting Git metadata

Datadog tire profit des données Git pour vous présenter les résultats de vos tests et les regrouper par référentiel, branche et commit. Les métadonnées Git sont automatiquement recueillies par l’instrumentation de test, à partir des variables d’environnement du fournisseur de CI et du dossier local .git dans le chemin du projet, le cas échéant.

Si vous exécutez des tests dans des fournisseurs de CI non pris en charge, ou sans dossier .git, vous pouvez configurer manuellement les données Git à l’aide de variables d’environnement. Ces dernières sont prioritaires et remplacent les informations détectées automatiquement. Configurez les variables d’environnement suivantes pour obtenir des données Git :

DD_GIT_REPOSITORY_URL

URL du référentiel dans lequel le code est stocké. Les URL HTTP et SSH sont prises en charge.
Exemple : git@github.com:MyCompany/MyApp.git, https://github.com/MyCompany/MyApp.git

DD_GIT_BRANCH

Branche Git testée. Ne renseignez pas cette variable si vous fournissez à la place des informations sur les tags.
Exemple : develop

DD_GIT_TAG

Tag Git testé (le cas échéant). Ne renseignez pas cette variable si vous fournissez à la place des informations sur la branche.
Exemple : 1.0.1

DD_GIT_COMMIT_SHA

Hash entier du commit.
Exemple : a18ebf361cc831f5535e58ec4fae04ffd98d8152

DD_GIT_COMMIT_MESSAGE

Message du commit.
Exemple : Set release number

DD_GIT_COMMIT_AUTHOR_NAME

Nom de l’auteur du commit.
Exemple : John Smith

DD_GIT_COMMIT_AUTHOR_EMAIL

E-mail de l’auteur du commit.
Exemple : john@example.com

DD_GIT_COMMIT_AUTHOR_DATE

Date de l’auteur du commit, au format ISO 8601.
Exemple : 2021-03-12T16:00:28Z

DD_GIT_COMMIT_COMMITTER_NAME

Nom du responsable du commit.
Exemple : Jane Smith

DD_GIT_COMMIT_COMMITTER_EMAIL

E-mail du responsable du commit.
Exemple : jane@example.com

DD_GIT_COMMIT_COMMITTER_DATE

Date du responsable du commit, au format ISO 8601.
Exemple : 2021-03-12T16:00:28Z

Running tests

After installation, run your tests as you normally do, for example using the xcodebuild test command. Tests, network requests, and application crashes are instrumented automatically. Pass your environment variables when running your tests in the CI, for example:

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

UI tests

RUM Integration

If the application being tested is instrumented using RUM, your UI tests results and their generated RUM sessions are automatically linked. Learn more about RUM in the RUM iOS Integration guide. An iOS RUM version >= 1.10 is needed.

Environment variables need to be set only in the test target, because the framework automatically injects these values to the application.

Test Optimisation SDK

If you don’t use RUM, you can link your application target with the Test SDK. The SDK adds auto-intrumentation to your application, gathers network requests and logs, and attaches them to the test traces.

Environment variables need to be set only in the test target, because the framework automatically injects these values to the application.

Additional optional configuration

For the following configuration settings:

• Boolean variables can use any of: 1, 0, true, false, YES, or NO
• String list variables accept a list of elements separated by , or ;

Enabling auto-instrumentation

DD_ENABLE_STDOUT_INSTRUMENTATION

Captures messages written to stdout (for example, print()) and reports them as logs. This may impact your bill. (Boolean)

DD_ENABLE_STDERR_INSTRUMENTATION

Captures messages written to stderr (for example, NSLog(), UITest steps) and reports them as logs. This may impact your bill. (Boolean)

Disabling auto-instrumentation

The framework enables auto-instrumentation of all supported libraries, but in some cases this might not be desired. You can disable auto-instrumentation of certain libraries by setting the following environment variables (or in the Info.plist file as described below):

DD_DISABLE_NETWORK_INSTRUMENTATION

Disables all network instrumentation (Boolean)

DD_DISABLE_RUM_INTEGRATION

Disables integration with RUM Sessions (Boolean)

DD_DISABLE_SOURCE_LOCATION

Disables test source code location and Codeowners (Boolean)

DD_DISABLE_CRASH_HANDLER

Disables crash handling and reporting. (Boolean)

Network auto-instrumentation

For Network auto-instrumentation, you can configure these additional settings:

DD_DISABLE_HEADERS_INJECTION

Disables all injection of tracing headers (Boolean)

DD_INSTRUMENTATION_EXTRA_HEADERS

Specific extra headers that you want to log (String List)

DD_EXCLUDED_URLS

URLs that you don’t want to log or inject headers into (String List)

DD_ENABLE_RECORD_PAYLOAD

Enables reporting a subset (1024 bytes) of the payloads in requests and responses (Boolean)

DD_MAX_PAYLOAD_SIZE

Sets the maximum size reported from the payload. Default 1024 (Integer)

DD_DISABLE_NETWORK_CALL_STACK

Disables the call stack information in the network spans (Boolean)

DD_ENABLE_NETWORK_CALL_STACK_SYMBOLICATED

Shows the call stack information with not only the method name, but also the precise file and line information. May impact your tests’ performance (Boolean)

Infrastructure test correlation

If you are running tests in your own infrastructure (macOS or simulator tests), you can correlate your tests with your infrastructure metrics by installing the Datadog Agent and setting the following:

DD_CIVISIBILITY_REPORT_HOSTNAME

Reports the hostname of the machine launching the tests (Boolean)

You can also disable or enable specific auto-instrumentation in some of the tests from Swift or Objective-C by importing the module DatadogSDKTesting and using the class: DDInstrumentationControl.

Custom tags

Environment variables

You can use DD_TAGS environment variable (or in the Info.plist file as described below). It must contain pairs of key:tag separated by spaces. For example:

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

If one of the values starts with the $ character, it is replaced with an environment variable of the same name (if it exists), for example:

DD_TAGS=home:$HOME

Using the $ character also supports replacing an environment variable at the beginning of a value if contains non-environment variable supported characters (a-z, A-Z or _), for example:

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

Inside a test method

You can add custom tags inside your test methods. The static property DDTest.current will return the current test instance if called inside the test method scope.

// Somewhere inside the test method
DDTest.current?.setTag(key: "key1", value: "value1")
// test continues normally
// ...

OpenTelemetry

Note: Using OpenTelemetry is only supported for Swift.

Datadog Swift testing framework uses OpenTelemetry as the tracing technology under the hood. You can access the OpenTelemetry tracer using DDInstrumentationControl.openTelemetryTracer and use any OpenTelemetry API. For example, to add a tag or attribute:

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()

The test target needs to link explicitly with opentelemetry-swift.

Reporting code coverage

When code coverage is available, the Datadog SDK (v2.2.7+) reports it under the test.code_coverage.lines_pct tag for your test sessions.

In Xcode, you can enable gathering of code coverage in your Test Plan or Test Scheme, depending on your project configuration.

You can see the evolution of the test coverage in the Coverage tab of a test session.

Using Info.plist for configuration

Alternatively to setting environment variables, all configuration values can be provided by adding them to the Info.plist file of the Test bundle (not the App bundle). If the same setting is set both in an environment variable and in the Info.plist file, the environment variable takes precedence.

CI provider environment variables

Best practices

Follow these practices to take full advantage of the testing framework and Test Optimization.

Generate symbols file when building

Build your code in Xcode using DWARF with dSYM File (or -Xswiftc -debug-info-format=dwarf if building with swift)

The testing framework uses symbol files for some of its functionality, including: symbolicating crashes, reporting test source location, and reporting code owners. It automatically generates the symbol file when debug symbols are embedded in the binaries, but it can take some extra time to load.

Disable sandbox for UI Tests on macOS

In some Xcode versions, UI Test bundles are built with a sandbox by default. The settings that come with a sandbox prevent the testing framework from being run by some system commands with xcrun, so you need to disable it.

Disable the sandbox by adding Entitlements to the UI Test runner bundle, then adding App Sandbox = NO to them. You can also create an .entitlement file and add it to the Signing Build Settings. This file should should include the following content:

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

Further reading

Documentation, liens et articles supplémentaires utiles:

Explore Test Results and PerformanceDOCUMENTATION Speed up your test jobs with Test Impact AnalysisDOCUMENTATION Troubleshooting Test OptimizationDOCUMENTATION