extends: capitalization

message: "'%s' should use sentence-style capitalization."

link: "https://github.com/DataDog/documentation/blob/master/CONTRIBUTING.md#headers"

scope: heading

match: $sentence

exceptions:

- IoT

- IPs

- Java

- JBoss

- JMXFetch

- Journald

Synthetic tests allow you to observe how your systems and applications are performing using **simulated requests and actions from around the globe**. Datadog **tracks the performance of your webpages and APIs** from the backend to the frontend, and at various network levels (`HTTP`, `TCP`, `SSL`, `DNS`, and `ICMP`) in a controlled and stable way, alerting you in case of faulty behavior (regression, broken feature, high response time, unexpected status code, etc.). **End-to-end testing production and CI environments** increases development teams’ speed as it puts an end to the fear of defective code making it to production. **Computing SLOs** on your key endpoints and user journeys makes it easier to stick to your application performance targets and ultimately provide a consistent customer experience.

Create your first Synthetic test and start monitoring web applications to improve their performance in just a few minutes.

API tests allow you to launch [single][1] or [chained][2] requests to perform verifications on your key systems at various network levels: `HTTP`, `TCP`, `SSL`, `DNS`, and `ICMP`. Create your first [HTTP test][3], [TCP test][4], [SSL test][5], [DNS test][6], or [ICMP test][7] to get started with API and network monitoring.

{{< img src="synthetics/api_test.png" alt="API tests" style="width:100%;">}}

Record end-to-end tests to monitor how your customers experience your webpages from around the world using [Synthetic browser tests][8].

{{< img src="synthetics/browser_test.gif" alt="Browser tests" style="width:100%;">}}

Use [Synthetic private locations][9] to monitor internal APIs and websites or to create custom locations in areas that are mission-critical to your business.

{{< img src="synthetics/ci.png" alt="CI tests" style="width:100%;">}}

Use the [out of the box integration between Synthetic tests and APM traces][11] to find the root cause of failures across frontend, network and backend requests.

The following Datadog tracing libraries are supported:

**Note**: The default timeout for each step is approximately 60 seconds. You can override this default timeout through the dedicated [advanced option][2].

The following steps are automatically recorded with the [Datadog browser test recorder extension][3]:

This is limited to 10 files with a limit of 5MB each.

The following steps can be manually added to a browser test by configuring them on the the browser test recorder page:

**Note**: You must prepend your URLs with `http` or `https` in the **Enter link URL** box.

The [Datadog browser test recorder extension][3] is able to record most steps associated to user journeys you might want to monitor. However, some steps—such as **Hover**, **Press Key**, and **Scroll**—are not recorded automatically. Explicitly add a step for them using the **Special Actions** menu located at the top left-hand corner of the recorder.

{{< img src="synthetics/browser_tests/variables.png" alt="Browser Test Variables" style="width:60%;">}}

Create a variable by defining its value from one of the below available builtins:

`{{ timestamp(n, unit) }}`

: Generates a timestamp in one of our accepted units with a value of the timestamp the test is initiated at +/- `n` chosen unit.

Create a variable out of a `span`, `div`, etc. content by extracting the text of this element.

**Note**: The way Browser tests load external JavaScript is by adding it to the page, so it will only work if your website accepts it.

Pick any global variables that was defined through [Synthetic Monitoring Settings][7].

Generate a random Synthetic email address that can be used in your test steps to [assert if an email was correctly sent][8] or to [navigate to a link contained within the email][9] (e.g. click a confirmation link). A unique mailbox is generated at each test execution to avoid any conflicts between test runs.

Test results and performance data are accessed from the **Step Results** section on your browser test's status page.

Each step where a full URL is loaded will contain page performance information.

[Google's Core Web Vitals][1] are a set of three metrics designed to monitor a site's user experience. These metrics focus on giving you a view of load performance, interactivity, and visual stability. Each metric comes with guidance on the range of values that translate to a good user experience.

A resource corresponds to the combination of requests and assets. The Resources panel shows:

Resource

: The URL of the resource

The maximum number of resources that can be displayed is 50. Resources are ordered by the time when they start and then are displayed in Datadog by the first 50.

Resources can be filtered by resource type. Also, a search can be performed over the displayed URLs.

kind: guide

further_reading:

- link: 'https://www.datadoghq.com/blog/browser-tests/'

tag: 'Documentation'

text: 'Configure a Browser Test'

- `alert` modals are closed.

{{< img src="synthetics/guide/popup/http_auth_option.png" alt="Basic Auth Popup">}}

{{< img src="synthetics/guide/uptime_slo/synthetics_message.png" alt="Synthetic test message" >}}

* `synthetics.dns.*` come from your API [DNS tests][4]

* `synthetics.ssl.*` come from your API [SSL tests][5]

{{< get-metrics-from-git "synthetics" "synthetics.browser" >}}

{{< get-metrics-from-git "synthetics" "synthetics.api" >}}

{{< get-metrics-from-git "synthetics" "synthetics.http" >}}

{{< get-metrics-from-git "synthetics" "synthetics.tcp" >}}

{{< get-metrics-from-git "synthetics" "synthetics.dns" >}}

{{< get-metrics-from-git "synthetics" "synthetics.ssl" >}}

The private location worker is shipped as a Docker container. The official [Docker image][3] is available on Docker Hub. It can run on a Linux based OS or Windows OS if the [Docker engine][4] is available on your host and can run in Linux containers mode.

To pull test configurations and push test results, the private location worker needs access to the below Datadog API endpoints.

Configure your private location by customizing the generated configuration file. Initial configuration parameters like [proxy](#proxy-configuration) and [blocked reserved IPs](#blocking-reserved-ips) are added in **Step 2** and are automatically reflected in the **Step 3** configuration file. Depending on your internal network setup, you may want to configure your private location with [advanced options](#advanced-configuration).

If the traffic between your private location and Datadog has to go through a proxy, specify your proxy URL with the following format: `http://<YOUR_USER>:<YOUR_PWD>@<YOUR_IP>:<YOUR_PORT>` to add the associated `proxyDatadog` parameter to your generated configuration file.

{{< img src="synthetics/private_locations/pl_proxy.png" alt="Add a proxy to your private location configuration file" style="width:90%;">}}

[Advanced proxy configuration options][5] are available.

By default, Synthetic users can create Synthetic tests on endpoints using any IP. If you want to prevent users from creating tests on sensitive internal IPs in your network, toggle the **Block reserved IPs** button to block a default set of reserved IP ranges ([IPv4 address registry][6] and [IPv6 address registry][7]) and set the associated `enableDefaultBlockedIpRanges` parameter to `true` in your generated configuration file.

[Advanced reserved IPs configuration options][8] are available.

[Advanced configuration options][9] are available and can be found by running the below `help` command:

**Note:** Arguments set in the launch command have precedence over the configuration file. However, these options are not stored and are consequently only prevalent for a given launch.

: **Type**: String <br>

**Default**: `datadoghq.com`<br>

Datadog site from which the private location pulls the test configuration and pushes the test results. Your `site` is {{< region-param key="dd_site" code="true" >}}.

The two below parameters can be used to customize DNS resolution on your **API tests**:

: **Type**: Boolean <br>

**Default**: `true`<br>

On **browser tests**, the DNS resolution is done directly by the browser, which usually reads DNS servers from the host. Alternatively, you can configure it at the container level (e.g., using the `--dns` flag on [Docker][1], or `dnsConfig.nameservers` on [Kubernetes][2]).

: **Type**: Boolean <br>

**Note:** The `whitelistedRange` and `blacklistedRange` parameters are now deprecated and should be replaced by the above listed ones.

: **Type**: String <br>

**Note:** The `proxy` parameter is now deprecated and should be replaced by `proxyDatadog`.

: **Type**: Number <br>

**Default**: `60000`<br>

Maximum test execution duration for API tests (in milliseconds).

You can upload custom root certificates to your private locations to have your API and Browser tests perform SSL handshake using your own `.pem` files. When spinning up your private location containers, mount the relevant certificate `.pem` files to `/etc/datadog/certs`, the same way your private location configuration file is mounted. These certificates are then considered trusted CA and used as such at test runtime.

**Note**: This feature is supported for versions 1.5.3+ of the private location Docker image.

: **Type**: String <br>