Synthetic CI/CD Testing

In addition to running tests at predefined intervals, you can also run Datadog Synthetic tests on-demand using API endpoints. You can run Datadog Synthetic tests in your continuous integration (CI) pipelines, letting you block the deployment of branches that would break your product. Synthetic CI/CD testing can also be used to run tests as part of your CD process, evaluating the state of your production application immediately after a deployment finishes. This lets you detect potential regressions that could impact your users—and automatically trigger a rollback whenever a critical test fails.

This function allows you to avoid spending time fixing issues on production, and to catch bugs and regressions earlier in the process.

On top of these API endpoints, Datadog provides and maintains a command line interface (CLI), allowing you to easily integrate Datadog Synthetic tests with your CI tooling. Synthetic CI/CD testing is open-source, and its source code is available on GitHub at DataDog/datadog-ci.

API usage

The trigger endpoint provides the list of triggered checks alongside their result identifiers. A polling endpoint is available to obtain the full results of the tests if they are available.

Trigger tests endpoint

The test triggering endpoint supports starting up to 50 tests in one request.

Request data structure

{
    "tests": [TEST_TO_TRIGGER, TEST_TO_TRIGGER, ...]
}

The TEST_TO_TRIGGER objects are composed of the public_id (required) of the test to trigger and optional configuration overrides (see below for a description of each field).

The public identifier of a test can be either the identifier of the test found in the URL of a test details page (for https://app.datadoghq.com/synthetics/details/abc-def-ghi, it would be abc-def-ghi) or the full URL to the details page (that is, https://app.datadoghq.com/synthetics/details/abc-def-ghi).

Example request

#!/bin/sh

api_key="<DATADOG_API_KEY>"
app_key="<DATADOG_APPLICATION_KEY>"

curl -X POST \
-H 'Content-Type: application/json' \
-H "DD-API-KEY: ${api_key}" \
-H "DD-APPLICATION-KEY: ${app_key}" \
-d '{
    "tests": [
        {
            "public_id": "abc-def-ghi",
            "allowInsecureCertificates": true,
            "basicAuth": { "username": "test", "password": "test" },
            "body": "{\"fakeContent\":true}",
            "bodyType": "application/json",
            "cookies": "name1=value1;name2=value2;",
            "deviceIds": ["laptop_large"],
            "followRedirects": true,
            "headers": { "NEW_HEADER": "NEW VALUE" },
            "locations": ["aws:us-west-1"],
            "retry": { "count": 2, "interval": 300 },
            "startUrl": "http://new.url/",
            "variables": { "titleVariable": "new value" }
        }
    ]
}' "https://api.datadoghq.com/api/v1/synthetics/tests/trigger/ci"

#!/bin/sh

api_key="<DATADOG_API_KEY>"
app_key="<DATADOG_APPLICATION_KEY>"

curl -X POST \
-H 'Content-Type: application/json' \
-H "DD-API-KEY: ${api_key}" \
-H "DD-APPLICATION-KEY: ${app_key}" \
-d '{
    "tests": [
        {
            "public_id": "abc-def-ghi",
            "allowInsecureCertificates": true,
            "basicAuth": { "username": "test", "password": "test" },
            "body": "{\"fakeContent\":true}",
            "bodyType": "application/json",
            "cookies": "name1=value1;name2=value2;",
            "deviceIds": ["laptop_large"],
            "followRedirects": true,
            "headers": { "NEW_HEADER": "NEW VALUE" },
            "locations": ["aws:us-west-1"],
            "retry": { "count": 2, "interval": 300 },
            "startUrl": "http://new.url/",
            "variables": { "titleVariable": "new value" }
        }
    ]
}' "https://api.datadoghq.eu/api/v1/synthetics/tests/trigger/ci"

Example response

{
  "results": [
    {
      "result_id": "0123456789012345678",
      "public_id": "abc-def-ghi",
      "location": 1
    },
  ],
  "triggered_check_ids": [
    "abc-def-ghi"
  ]
}

Poll results endpoint

Example request

#!/bin/sh

api_key="<DATADOG_API_KEY>"
app_key="<DATADOG_APPLICATION_KEY>"

curl -G \
    "https://api.datadoghq.com/api/v1/synthetics/tests/poll_results" \
    -H "DD-API-KEY: ${api_key}" \
    -H "DD-APPLICATION-KEY: ${app_key}" \
    -d "result_ids=[220123456789012345678]"

#!/bin/sh

api_key="<DATADOG_API_KEY>"
app_key="<DATADOG_APPLICATION_KEY>"

curl -G \
    "https://api.datadoghq.eu/api/v1/synthetics/tests/poll_results" \
    -H "DD-API-KEY: ${api_key}" \
    -H "DD-APPLICATION-KEY: ${app_key}" \
    -d "result_ids=[%220123456789012345678%22]"

Example response

Dropdown

{
  "results": [
    {
      "check_id": "123456",
      "timestamp": 1585841351642,
      "orgID": 2,
      "result": {
        "unhealthy": false,
        "eventType": "finished",
        "timings": {
          "firstByte": 14.7,
          "tcp": 11.6,
          "ssl": 45.7,
          "dns": 12.484235048294067,
          "download": 0.2,
          "total": 84.7
        },
        "mainDC": "us1.prod",
        "runType": 2,
        "httpStatusCode": 200,
        "responseSize": 9201,
        "healthCheckRatio": 1
      },
      "dc_id": 1,
      "resultID": "0123456789012345678"
    }
  ]
}

{
  "results": [
    {
      "check_id": "123456",
      "timestamp": 1601639904704,
      "orgID": 2,
      "result": {
        "runType": 2,
        "artifactsBucketKey": "2/e2e-tests/abc-def-ghi/results/17221670732431167/chrome.laptop_large/artifacts__1601639913277.json",
        "browserType": "chrome",
        "eventType": "finished",
        "stepDetails": [
          {
            "browserErrors": [],
            "skipped": false,
            "description": "Navigate to start URL",
            "warnings": [],
            "url": "about:blank",
            "value": "https://example.com",
            "duration": 1002,
            "allowFailure": false,
            "screenshotBucketKey": "2/e2e-tests/abc-def-ghi/results/17221670732431167/chrome.laptop_large/step-0__1601639913294.jpeg",
            "type": "goToUrlAndMeasureTti",
            "stepId": -1
          },
          {
            "browserErrors": [],
            "stepElementUpdates": {
              "version": 1,
              "multiLocator": {
                "ab": "/*[local-name()=\"html\"][1]/*[local-name()=\"body\"][1]/*[local-name()=\"div\"][1]/*[local-name()=\"h1\"][1]",
                "co": "[{\"text\":\"example domain\",\"textType\":\"directText\"}]",
                "cl": "/*[local-name()=\"html\"]/*[local-name()=\"body\"]/*[local-name()=\"div\"][1]/*[local-name()=\"h1\"][1]",
                "at": "/*[local-name()=\"html\"]/*[local-name()=\"body\"]/*[local-name()=\"div\"][1]/*[local-name()=\"h1\"][1]",
                "clt": "/descendant::*[text()[normalize-space(translate(., 'ABCDEFGHIJKLMNOPQRSTUVWXYZÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞŸŽŠŒ', 'abcdefghijklmnopqrstuvwxyzàáâãäåæçèéêëìíîïðñòóôõöøùúûüýþÿžšœ')) = \"example domain\"]]",
                "ro": "//*[local-name()=\"h1\"]"
              }
            },
            "skipped": false,
            "description": "Test heading \"Example Domain\" content",
            "url": "https://www.example.com/",
            "checkType": "contains",
            "value": "Example Domain",
            "duration": 204,
            "allowFailure": false,
            "screenshotBucketKey": "2/e2e-tests/abc-def-ghi/results/17221670732431167/chrome.laptop_large/step-1__1601639913410.jpeg",
            "type": "assertElementContent",
            "stepId": 2275176
          }
        ],
        "browserVersion": "84.0.4147.135",
        "mainDC": "us1.prod",
        "timeToInteractive": 269,
        "device": {
          "name": "Laptop Large",
          "height": 1100,
          "width": 1440,
          "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/84.0.4147.135 Safari/537.36",
          "id": "chrome.laptop_large",
          "isMobile": false,
          "browser": "chrome"
        },
        "passed": true,
        "duration": 1206,
        "startUrl": "https://www.example.com",
        "metadata": {}
      },
      "dc_id": 30005,
      "resultID": "17221670732431167",
      "metadata": {}
    }
  ]
}

CLI usage

Package installation

The package is published under @datadog/datadog-ci in the NPM registry.

Dropdown

Install the package through NPM:

npm install --save-dev @datadog/datadog-ci

Install the package through Yarn:

yarn add --dev @datadog/datadog-ci

Setup the client

To setup your client, Datadog API and application keys need to be configured. These keys can be defined in three different ways:

As environment variables:

export DATADOG_API_KEY="<API_KEY>"
export DATADOG_APP_KEY="<APPLICATION_KEY>"

Passed to the CLI when running your tests:

datadog-ci synthetics run-tests --apiKey "<API_KEY>" --appKey "<APPLICATION_KEY>"

Or defined in a global configuration file:

You can also create a JSON configuration file to specify more advanced options. The path to this global configuration file can be set using the flag --config when launching your tests. If the name of your global configuration file is set to datadog-ci.json, it defaults to it.

apiKey: The API key used to query the Datadog API.
appKey: The application key used to query the Datadog API.
datadogSite: The Datadog instance to which request is sent (choices are datadoghq.com or datadoghq.eu). The default is datadoghq.com.
files: Glob pattern to detect synthetic tests config files.
global: Overrides of synthetic tests applied to all tests (see below for description of each field).
proxy: The proxy to be used for outgoing connections to Datadog. host and port keys are mandatory arguments, protocol key defaults to http. Supported values for protocol key are http, https, socks, socks4, socks4a, socks5, socks5h, pac+data, pac+file, pac+ftp, pac+http, pac+https. The library used to configure the proxy is proxy-agent library.
subdomain: The name of the custom subdomain set to access your Datadog application. If the URL used to access Datadog is myorg.datadoghq.com the subdomain value then needs to be set to myorg.

Example global configuration file:

{
    "apiKey": "<DATADOG_API_KEY>",
    "appKey": "<DATADOG_APPLICATION_KEY>",
    "datadogSite": "datadoghq.com",
    "files": "{,!(node_modules)/**/}*.synthetics.json",
    "global": {
        "allowInsecureCertificates": true,
        "basicAuth": { "username": "test", "password": "test" },
        "body": "{\"fakeContent\":true}",
        "bodyType": "application/json",
        "cookies": "name1=value1;name2=value2;",
        "deviceIds": ["laptop_large"],
        "followRedirects": true,
        "headers": { "<NEW_HEADER>": "<NEW_VALUE>" },
            "locations": ["aws:us-west-1"],
        "retry": { "count": 2, "interval": 300 },
        "executionRule": "skipped",
        "startUrl": "{{URL}}?static_hash={{STATIC_HASH}}",
        "variables": { "titleVariable": "new value" },
        "pollingTimeout": 180000
    },
    "proxy": {
      "auth": {
        "username": "login",
        "password": "pwd"
      },
      "host": "127.0.0.1",
      "port": 3128,
      "protocol": "http"
    },
    "subdomain": "subdomainname"
}

Configure tests

By default, the client automatically discovers and runs all tests specified in **/*.synthetics.json files (the path can be configured in the global configuration file. These files have a tests key, which contains an array of objects with the IDs of the tests to run and any potential configuration overrides for these tests.

Example basic test configuration file:

{
    "tests": [
        {
            "id": "<TEST_PUBLIC_ID>"
        },
        {
            "id": "<TEST_PUBLIC_ID>"
        }
    ]
}

Further configuration

The default configurations used for the tests are the original tests’ configurations (visible in the UI or when getting your tests’ configurations from the API).

However, in the context of your CI deployment, you can optionally decide to override some (or all) of your tests parameters by using the below overrides. If you want to define overrides for all of your tests, these same parameters can be set at the global configuration file level.

allowInsecureCertificates: (boolean) Disable certificate checks in API tests.
basicAuth: (object) Credentials to provide in case a basic authentication is encountered.
- username: (string) Username to use in basic authentication.
- password: (string) Password to use in basic authentication.
body: (string) Data to send in a synthetic API test.
bodyType: (string) Type of the data sent in a synthetic API test.
cookies: (string) Use provided string as cookie header in API or browser test.
deviceIds: (array) List of devices on which to run the browser test.
followRedirects: (boolean) Indicates whether to follow HTTP redirections in API tests.
headers: (object) Headers to replace in the test. This object should contain, as keys, the name of the header to replace and, as values, the new value of the header.
locations: (array) List of locations from which the test should be run.
retry: (object) Retry policy for the test:
- count: (integer) Number of attempts to perform in case of test failure.
- interval: (integer) Interval between the attempts (in milliseconds).
executionRule: (string) Execution rule of the test: defines the behavior of the CLI in case of a failing test:
- blocking: The CLI returns an error if the test fails.
- non_blocking: The CLI only prints a warning if the test fails.
- skipped: The test is not executed at all.
startUrl: (string) New start URL to provide to the test.
variables: (object) Variables to replace in the test. This object should contain, as keys, the name of the variable to replace and, as values, the new value of the variable.
pollingTimeout: (integer) Duration after which synthetic tests are considered failed (in milliseconds).

Note: Tests’ overrides take precedence over global overrides.

Example advanced test configuration file:

{
    "tests": [
        {
            "id": "<TEST_PUBLIC_ID>",
            "config": {
                "allowInsecureCertificates": true,
                "basicAuth": { "username": "test", "password": "test" },
                "body": "{\"fakeContent\":true}",
                "bodyType": "application/json",
                "cookies": "name1=value1;name2=value2;",
                "deviceIds": ["laptop_large"],
                "followRedirects": true,
                "headers": { "<NEW_HEADER>": "<NEW_VALUE>" },
            "locations": ["aws:us-west-1"],
                "retry": { "count": 2, "interval": 300 },
                "executionRule": "skipped",
                "startUrl": "{{URL}}?static_hash={{STATIC_HASH}}",
                "variables": { "titleVariable": "new value" },
                "pollingTimeout": 180000
            }
        }
    ]
}

Execution rule

The execution rule of each test can also be defined in-app, at the test level. Use the drop-down menu next to CI Execution.

The execution rule associated with the test is always the most restrictive one that was set in the configuration file. From the most restrictive to the least restrictive: skipped, non_blocking, blocking. For example, if your test is configured to be skipped in the UI but to blocking in the configuration file, it is skipped when running your tests.

Start URL

You can configure on which url your test starts by providing a startUrl to your test object and build your own starting URL using any part of your test’s original starting URL and the following environment variables:

Environment variable	Description	Example
`URL`	Test’s original starting URL	`https://www.example.org:81/path/to/something?abc=123`
`DOMAIN`	Test’s domain name	`example.org`
`HOST`	Test’s host	`www.example.org:81`
`HOSTNAME`	Test’s hostname	`www.example.org`
`ORIGIN`	Test’s origin	`https://www.example.org:81`
`PARAMS`	Test’s query parameters	`?abc=123`
`PATHNAME`	Test’s URl path	`/path/to/something`
`PORT`	Test’s host port	`81`
`PROTOCOL`	Test’s protocol	`https:`
`SUBDOMAIN`	Test’s sub domain	`www`

For instance, if your test’s starting URL is https://www.example.org:81/path/to/something?abc=123, it can be written as:

{{PROTOCOL}}//{{SUBDOMAIN}}.{{DOMAIN}}:{{PORT}}{{PATHNAME}}{{PARAMS}}
{{PROTOCOL}}//{{HOST}}{{PATHNAME}}{{PARAMS}}
{{URL}}

Running tests

You can decide to have the CLI autodiscover all your **/*.synthetics.json Synthetic tests (or all the tests associated to the path specified in your global configuration file) or to specify the tests you want to run using the -p,--public-id flag.

Run tests by executing the CLI:

Dropdown

yarn datadog-ci synthetics run-tests

Note: If you are launching your tests with a custom global configuration file, append your command with --config <PATH_TO_GLOBAL_CONFIG_FILE.

Add the following to your package.json:

{
  "scripts": {
    "datadog-ci-synthetics": "datadog-ci synthetics run-tests"
  }
}

Then, run:

npm run datadog-ci-synthetics

Note: If you are launching your tests with a custom global configuration file, append the command associated to your datadog-ci-synthetics script with --config <PATH_TO_GLOBAL_CONFIG_FILE.