Cette page n'est pas encore disponible en français, sa traduction est en cours. Si vous avez des questions ou des retours sur notre projet de traduction actuel, n'hésitez pas à nous contacter.
This page is about configuring Synthetic tests for your continuous integration (CI) pipelines. If you want to bring your CI metrics and data into Datadog dashboards, see the Continuous Integration Visibility section.
Overview
Use the @datadog-ci NPM package to run Synthetic tests directly within your CI/CD pipeline. You can automatically halt a build, block a deployment, and roll back a deployment when a Synthetics test detects a regression.
To configure which URL your test starts on, provide a startUrl to your test object. Build your own starting URL with any part of your test’s original starting URL and the following environment variables:
The global JSON configuration file can specify additional advanced options. Specify the path to this file using the flag --configwhen launching your tests. If you set the name of your global configuration file to datadog-ci.json, that name is the default.
In the global configuration file, you can configure the following options:
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. The default is datadoghq.com. Your Datadog site is .
files
Glob pattern to detect Synthetic tests config files.
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 the 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.
By default, the client automatically discovers and runs all tests specified in **/*.synthetics.json files. This 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 test configuration overrides.
However, in the context of your CI deployment, you may decide to override some or all of your test parameters with the overrides below. To define overrides for all of your tests, set the same parameters at the global configuration file level.
allowInsecureCertificates
Type: boolean Disable certificate checks in HTTP tests.
basicAuth
Type: object Credentials to provide in case a basic authentication is encountered in HTTP or browser tests.
username: string. Username to use in basic authentication.
password: string. Password to use in basic authentication.
body
Type: string Data to send in HTTP tests.
bodyType
Type: string Type of the data sent in HTTP tests.
cookies
Type: string Use provided string as cookie header in HTTP or browser tests.
deviceIds
Type: array List of devices on which to run the browser test.
followRedirects
Type: boolean Indicates whether to follow redirections in HTTP tests.
headers
Type: object Headers to replace in the HTTP or browser test. This object should contain the name of the header to replace as keys and the new value of the header as values.
locations
Type: array List of locations from which the test runs.
retry
Type: 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
Type: string Execution rule of the test that defines the CLI behavior 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
Type: string New start URL to provide to the HTTP or browser test.
variables
Type: object Variables to replace in the test. This object should contain the name of the variable to replace as keys and the new value of the variable as values.
pollingTimeout
Type: integer The duration in milliseconds after which datadog-ci stops polling for test results. The default is 120,000 ms. At the CI level, test results completed after this duration are considered failed.
Note: The test’s overrides take precedence over global overrides.
Use the drop-down menu next to CI Execution to define the execution rule for each test at the test level.
The execution rule associated with the test is the most restrictive one in the configuration file. The options range from most to least restrictive: skipped, non_blocking, and blocking. For example, if your test is configured as skipped in the UI but blocking in the configuration file, it is skipped when your test runs.
Starting URL
URL
Test’s original starting URL Example: https://www.example.org:81/path/to/something?abc=123#target
DOMAIN
Test’s domain name Example: example.org
HASH
Test’s hash Example: #target
HOST
Test’s host Example: www.example.org:81
HOSTNAME
Test’s hostname Example: www.example.org
ORIGIN
Test’s origin Example: https://www.example.org:81
PARAMS
Test’s query parameters Example: ?abc=123
PATHNAME
Test’s URl path Example: /path/to/something
PORT
Test’s host port Example: 81
PROTOCOL
Test’s protocol Example: https:
SUBDOMAIN
Test’s sub domain Example: www
Whether you use Synthetic tests to control your CI/CD deployments in production or staging, you can run Synthetic tests against a generated staging URL instead of in production by setting local environment variables in your test’s starting URL.
To trigger an existing Synthetics test on a staging endpoint instead of in production, set the $SUBDOMAIN environment variable to staging-example and the $PORT environment variable to a port used for staging. Your Synthetic tests run against the generated staging URL instead of running in production.
For example, you can write https://app.datadoghq.com/synthetics/details/abc-123-zyx?live=1h#test-results as:
Note: If you have environment variables with names corresponding to one of the reserved variables above, your environment variables are ignored and replaced with the corresponding component parsed from your test’s startUrl.
Run tests
You can decide to have the CLI auto-discover 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:
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.
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.
Use the testing tunnel
The @datadog/datadog-ci NPM package also comes with secure tunnelling, allowing you to trigger Synthetic tests on your internal applications.
The testing tunnel creates an end-to-end encrypted HTTP proxy between your infrastructure and Datadog that allows all test requests sent through the CLI to be automatically routed through the datadog-ci client.