Swift Tests

Docs > Test Optimization in Datadog > Configure Test Optimization > Swift Tests

Compatibility

Supported languages:

Language	Version
Swift	>= 5.7
Objective-C	>= 2.0
Xcode	>= 14.3

Supported platforms:

Platform	Version
iOS	>= 11.0
macOS	>= 10.13
tvOS	>= 11.0

Installing the Swift testing SDK

There are three ways you can install the testing framework:

Using Xcode Project

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

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

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

Using Swift Package Project

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

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

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

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

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

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

target 'MyApp' do
  # ...

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

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

Download and decompress DatadogSDKTesting.zip from the release page.
Copy and link your test targets with the resulting XCFramework.

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

Note: This framework is useful only for testing and should only be linked with the application when running tests. Do not distribute the framework to your users.

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:

You should have your main target in the variables expansion of the environment variables; if not selected, variables are not valid.

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

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)

Important: If you disable crash reporting, tests that crash are not reported at all, and don't appear as test failures. If you need to disable crash handling for any of your tests, run them as a separate target, so you don't disable it for the others.

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.