For AI agents: A markdown version of this page is available at https://docs.datadoghq.com/synthetics/test_suites.md. A documentation index is available at /llms.txt.

Test Suites

Overview

Synthetic Monitoring Test Suites let you organize multiple tests into a single collection for simplified management and troubleshooting. Group tests by user journey, environment, location, service, team, or any other dimension that fits your workflow. View aggregated results, identify failing components, and understand application performance across related tests, all from a unified view. Configure suite-level alerting to receive a consolidated notification when a critical portion of your tests fail, helping you respond more efficiently to issues impacting important workflows.

Key features

  • Impact-driven alerting: Receive a consolidated alert when a critical portion of the test suite fails.
  • Centralized visibility: View all tests in a suite and their results in one place.
  • Simplified management: Create and run test groups instead of managing individual tests separately.
  • Easier maintenance: Identify which tests need updates when application changes are made.

Create a test suite

To create a Synthetic Monitoring Test Suite:

  1. In Datadog, navigate to Digital Experience.
  2. Click New Test Suite.
  3. Optionally, navigate to the Synthetic Monitoring tests page, and click + New Suite.

Test suite configuration

  1. Enter a name for your suite (for example, Checkout flow or API health checks).

  2. Click Add Tests to include existing Synthetic Monitoring tests.
    You can:

    • Search by name or tag.
    • Filter by test type (such as Browser, API, Private Location, or Mobile).
    • Select one or more tests to include.

  3. Click Add Tests to confirm.

  4. Optionally, remove tests using the Remove Test from Suite icon next to each entry.

  5. Configure alerting for the suite:

Alerting for Test Suites is not supported for this Datadog site ()

  • By default, all tests are marked as Critical, and the alert triggers when any critical test fails.

    Note: Suite alerts are separate from individual test alerts. To avoid duplicate notifications, mute alerts on individual tests included in the suite.

  • To exclude specific tests from triggering the suite-level alert, select them and mark them as Ignored.

  • Adjust the alert threshold to trigger only when a specified percentage of critical tests fail.

Suite alerting creation page, with the suite alerting drop-down expanded.

Note: For existing test suites, alerting is enabled with default settings. You can modify the configuration as needed.

  1. Configure monitor settings (notification message, recipients, renotification) the same way you would for a single test.
  2. Click Save Suite when finished.
Synthetic Monitoring Test Suite creation page

Service level objectives

When you create a test suite, Datadog automatically generates a service level objective (SLO) for it, with no configuration required. By default, the SLO uses a 7-day rolling window with a 99.9% target.

The SLO panel on the Test Suite details page shows the current SLO status and error budget. From this view, you can:

  • Create alert to set up alerting when SLO performance degrades significantly. When an alert already exists, hover over the alert indicator to view additional details.
  • View details by clicking the eye icon to open the full SLO details page.
  • View contributors to see which tests are consuming error budget.
  • Edit the SLO by clicking the Image pencil icon.
Test suite SLO panel showing the 7-day rolling window, error budget, Create Alert button, and primary contributors.

Create an alert

Click Create alert on the SLO details panel to open the SLO Monitor configuration form, where you can set alert conditions and notification settings.

SLO Monitor creation form with alert condition and notification settings.

View details

Click the eye icon to open the full SLO details page. From this page, you can view SLO status, error budget burndown, burn rate, and metric timeseries.

Full SLO details page for a test suite, showing SLO status, error budget burndown, burn rate, and metric timeseries.

Contributors

The contributors section highlights the tests with the largest impact on error budget consumption:

  • Total number of critical tests: The total number of critical tests in the suite.
  • Error budget consumed by: The number of tests that consumed error budget.
  • Top 3 contributors consumed: The top three tests by percentage impact, based on how long each test was in an alert state while the suite was in alert.
Primary Contributors section showing total critical tests, error budget consumed, and top three contributors by percentage impact.

Edit the service level objective

To update the SLO time window (for example, to 30 days) or target, click the Image pencil icon on the SLO panel. Because this SLO is automatically created from a test suite, you can only edit the time window, target, and warning thresholds.

Edit SLO page for a test suite, showing the target and time window fields.

View and manage test suites

After creating your suite, it appears in the Suites tab on the Synthetic Monitoring tests page, or you can access test suites from Digital Experience > Test Suites.

To apply a Scheduled downtime to one or more test suites, select them using the checkboxes and click Add to Downtime in the bulk actions bar.

When viewing a test suite, three tabs are available:

  • Tests in the Suite: Lists all tests included in the suite.
  • Test Runs: Displays global uptime metrics and related test runs.
  • Attributes: Shows suite attributes such as team, monitors, and who created the test suite.

Note: Test runs appear in the suite only from the date the test was added. To view earlier results, check the individual test page. If you rename a test, previous runs remain listed under the original name. A maximum of 300 tests can be added per suite.

Synthetic Monitoring Test Suite summary page

Run a test suite

To manually trigger the tests in a suite:

  1. Navigate to the suite and click the Tests in the Suite tab.
  2. Select the tests you want to run using the checkboxes.
  3. Click Run Tests Now.
The Tests in the Suite tab with tests bulk selected and the Run Tests Now button visible

Note: You can run a maximum of 50 tests at a time.

Troubleshooting

If some tests fail to appear in a suite:

  • Ensure the tests are active and not deleted.
  • Confirm you have the necessary permissions to view those tests.
  • Refresh filters or clear search terms when adding tests.

If execution results look incomplete:

  • Verify test run frequency and recent activity.
  • Check for tag or location mismatches that could filter out runs.
  • Re-save the Test Suite to refresh the association with its tests.

Further Reading

Additional helpful documentation, links, and articles:

Learn about Synthetic MonitoringDOCUMENTATION more more Configure Synthetic test monitorsDOCUMENTATION more more Synthetic Monitoring TroubleshootingDOCUMENTATION more more Get organized, actionable insights from complex test environmentsBLOG more more Understanding Synthetic Monitor AlertingGUIDE more more