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 UITests, also link the app running the tests with this library.

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.2.0")

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 UITests, 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 UITests, 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 UITests, also link the app running the tests with this library.

If you use GitHub, you can use the Swift test action from GitHub Marketplace to automatically configure and run your tests. By default, the rest of the configuration described on this page can be skipped (except the configuration of the action itself), but you can use the configuration environment variables for disabling or configuring additional functionality.

Compared to other methods, such as Cocoapods and Framework linking, the Swift test action option may be less flexible to configure and run, but requires no code changes.

Instrumenting your tests

Configuring Datadog

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 UITests, 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= 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 ...

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_APPLICATION_KEY

The Datadog Application 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_ENV=ci DD_SITE= xcodebuild \
  -project "MyProject.xcodeproj" \
  -scheme "MyScheme" \
  -destination "platform=macOS,arch=x86_64" \
  test

UI tests

For UITests, both the test target and the application running from the UITests must link with the framework. Environment variables need to be set only in the test target, because the framework automatically injects these values to the application.

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.

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

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 the reporting of code coverage in your Test Scheme.

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

Manual testing API

If you use XCTests with your Swift projects, the DatadogSDKTesting framework automatically instruments them and sends the results to the Datadog backend. If you don’t use XCTest, you can instead use the Swift/Objective-C manual testing API, which also reports test results to the backend.

The API is based around three concepts: test module, test suites, and tests.

Test module

A test module represents the load of a library or bundle that includes the tests.

To start a test module, call DDTestModule.start() and pass the name of the module or bundle to test.

When all your tests have finished, call module.end(), which forces the library to send all remaining test results to the backend.

Test Suites

A test suite comprises a set of tests that share common functionality. They can share a common initialization and teardown, and can also share some variables.

Create test suites in the test module by calling module.suiteStart() and passing the name of the test suite.

Call suite.end() when all the related tests in the suite have finished their execution.

Tests

Each test runs inside a suite and must end in one of these three statuses: pass, fail, or skip. A test can optionally have additional information like attributes or error information.

Create tests in a suite by calling suite.testStart() and passing the name of the test. When a test ends, one of the predefined statuses must be set.

API interface

class DDTestModule {
    // Starts the module.
    // - Parameters:
    //   - bundleName: Name of the module or bundle to test.
    //   - startTime: Optional. The time the module started.
    static func start(bundleName: String, startTime: Date? = nil) -> DDTestModule
    //
    // Ends the module.
    // - Parameters:
    //   - endTime: Optional. The time the module ended.
    func end(endTime: Date? = nil)
    // Adds a tag/attribute to the test module. Any number of tags can be added.
    // - Parameters:
    //   - key: The name of the tag. If a tag with the same name already exists,
    //     its value will be replaced by the new value.
    //   - value: The value of the tag. Can be a number or a string.
    func setTag(key: String, value: Any)
    //
    // Starts a suite in this module.
    // - Parameters:
    //   - name: Name of the suite.
    //   - startTime: Optional. The time the suite started.
    func suiteStart(name: String, startTime: Date? = nil) -> DDTestSuite
}
    //
public class DDTestSuite : NSObject {
    // Ends the test suite.
    // - Parameters:
    //   - endTime: Optional. The time the suite ended.
    func end(endTime: Date? = nil)
    // Adds a tag/attribute to the test suite. Any number of tags can be added.
    // - Parameters:
    //   - key: The name of the tag. If a tag with the same name already exists,
    //     its value will be replaced by the new value.
    //   - value: The value of the tag. Can be a number or a string.
    func setTag(key: String, value: Any)
    //
    // Starts a test in this suite.
    // - Parameters:
    //   - name: Name of the test.
    //   - startTime: Optional. The time the test started.
    func testStart(name: String, startTime: Date? = nil) -> DDTest
}
    //
public class DDTest : NSObject {
    // Adds a tag/attribute to the test. Any number of tags can be added.
    // - Parameters:
    //   - key: The name of the tag. If a tag with the same name already exists,
    //     its value will be replaced by the new value.
    //   - value: The value of the tag. Can be a number or a string.
    func setTag(key: String, value: Any)
    //
    // Adds error information to the test. Only one errorInfo can be reported by a test.
    // - Parameters:
    //   - type: The type of error to be reported.
    //   - message: The message associated with the error.
    //   - callstack: Optional. The callstack associated with the error.
    func setErrorInfo(type: String, message: String, callstack: String? = nil)
    //
    // Ends the test.
    // - Parameters:
    //   - status: The status reported for this test.
    //   - endTime: Optional. The time the test ended.
    func end(status: DDTestStatus, endTime: Date? = nil)
}
    //
// Possible statuses reported by a test:
enum DDTestStatus {
  // The test passed.
  case pass
  //
  //The test failed.
  case fail
  //
  //The test was skipped.
  case skip
}

Code example

The following code represents a simple usage of the 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()

Always call module.end() at the end so that all the test info is flushed to Datadog.

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

Additional helpful documentation, links, and articles:

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