Skip to content

Synthetic testing

Amazon CloudWatch Synthetics allows you to monitor applications from the perspective of your customer, even in the absence of actual users. By continuously testing your APIs and website experiences, you can gain visibility into intermittent issues that occur even when there is no user traffic.

Canaries are configurable scripts, that you can run on a schedule to continually test your APIs and website experiences 24x7. They follow the same code paths and network routes as real-users, and can notify you of unexpected behavior including latency, page load errors, broken or dead links, and broken user workflows.

CloudWatch Synthetics architecture


Ensure that you use Synthetics canaries to monitor only endpoints and APIs where you have ownership or permissions. Depending on the canary frequency settings, these endpoints might experience increased traffic.

Getting Started

Full Coverage


When developing your testing strategy, consider both public and private internal endpoints within your Amazon VPC.

Recording New Canaries

The CloudWatch Synthetics Recorder Chrome browser plugin allows you to quickly build new canary test scripts with complex workflows from scratch. The type and click actions taken during recording are converted into a Node.js script that you can use to create a canary. The known limitations of the CloudWatch Synthetics Recorder are noted on this page.

Viewing Aggregate Metrics

Take advantage of the out-of-the-box reporting on aggregate metrics collected from your fleet of canary scripts. CloudWatch Automatic Dashboard

The CloudWatch Dashboard for Synthetics

Building Canaries


Use canary blueprints to simplify the setup process for multiple canary types.

Multiple ways to create a synthetics canary


Blueprints are a convenient way to start writing canaries and simple use cases can be covered with no code.


When you write your own canaries, they are tied to a runtime version. This will be a specific version of either Python with Selenium, or JavaScript with Puppeteer. See [this page] for a list of our currently-supported runtime versions and those that are deprecated.


Improve the maintainability of your scripts by using environment variables to share data that can be accessed during the canary's execution.


Upgrade your canaries to the latest runtime version when available.

String Secrets

You can code your canaries to pull secrets (such as login credentials) from a secure system outside of your canary or its environment variables. Any system that can be reached by AWS Lambda can potentially provide secrets to your canaries at runtime.


Execute your tests and secure sensitive data by storing secrets like database connection details, API keys, and application credentials using AWS Secrets Manager.

Managing Canaries at Scale


If your website contains a high-volume of dynamic content and links, you can use CloudWatch Synthetics to crawl your website, detect broken links, and find the reason for failure. Then use a failure threshold to optionally create a CloudWatch Alarm when a failure threshold has been violated.

Multiple Heartbeat URLs


Simplify your testing and optimize costs by batching multiple URLs in a single heartbeat monitoring canary test. You can then see the status, duration, associated screenshots, and failure reason for each URL in the step summary of the canary run report.

Organize in Groups


Organize and track your canaries in groups to view aggregated metrics and more easily isolate and drill in to failures.

Organize and track canaries in groups


Note that groups will require the exact name of the canary if you are creating a cross-region group.

Runtime Options

Versions and Support

CloudWatch Synthetics currently supports runtimes that use Node.js for scripts and the Puppeteer framework, and runtimes that use Python for scripting and Selenium WebDriver for the framework.


Always use the most recent runtime version for your canaries, to be able to use the latest features and updates made to the Synthetics library.

CloudWatch Synthetics notifies you by email if you have canaries that use runtimes that are scheduled to be deprecated in the next 60 days.

Code Samples

Get started with code samples for both Node.js and Puppeteer and Python and Selenium.

Import for Selenium

Create canaries in Python and Selenium from scratch or by importing existing scripts with minimal changes.