Configure Synthetics projects

edit

This functionality is in beta and is subject to change. The design and code is less mature than official GA features and is being provided as-is with no warranties. Beta features are not subject to the support SLA of official GA features.

Synthetic tests support the configuration of dynamic parameters that can be used in projects. In addition, the Synthetics agent, which is built on top of Playwright, supports configuring browser and context options that are available in Playwright-specific methods, for example, ignoreHTTPSErrors, extraHTTPHeaders, and viewport.

Create a synthetics.config.js or synthetics.config.ts file in the root of the synthetics project and specify the options:

import { SyntheticsConfig } from '@elastic/synthetics'

const config: SyntheticsConfig = {
  params: {
    url: 'https://www.elastic.co'
  },
  playwrightOptions: {
    ignoreHTTPSErrors: true, // ignores all HTTPS errors during navigation
    extraHTTPHeaders: {
      'foo': 'bar' // additional HTTP headers to be sent with every request
    }
  },
  monitor: {
    schedule: 10,
    locations: [ 'us-east4-a' ],
  }
}

export default config;

The configuration file can either export an object, or a function that when called should return the generated configuration. To know more about configuring the tests based on environments, look at the dynamic configuration documentation.

params

edit

An object that defines any variables your tests require.

playwrightOptions

edit

For available options, see the Playwright documentation.

Device emulation

edit

Users can emulate a mobile device using the configuration file. The example configuration below runs tests in "Pixel 5" emulation mode.

import { SyntheticsConfig } from "@elastic/synthetics"
import { devices } from "playwright-chromium"

const config: SyntheticsConfig = {
  playwrightOptions: {
    ...devices['Pixel 5']
  }
}

export default config;

monitor

edit

Default values to be applied to all monitors when using the @elastic/synthetics push command.

id (string)
A unique identifier for this monitor.
name (string)
A human readable name for the monitor.
tags (Array<string>)
A list of tags that will be sent with the monitor event. Tags are displayed in the Synthetics app and allow you to search monitors by tag.
schedule (number)
The interval (in minutes) at which the monitor should run.
enabled (boolean)
Enable or disable the monitor from running without deleting and recreating it.
locations (Array<SyntheticsLocationsType>)

Where to deploy the monitor. Monitors can be deployed in multiple locations so that you can detect differences in availability and response times across those locations.

To list available locations you can:

privateLocations (Array<string>)

The Private Locations to which the monitors will be deployed. These Private Locations refer to locations hosted and managed by you, whereas locations are hosted by Elastic. You can specify a Private Location using the location’s name.

To list available Private Locations you can:

  • Run the elastic-synthetics locations command with the Kibana URL for the deployment from which to fetch available locations.
  • Go to SyntheticsManagement and click Create monitor. Private Locations will be listed in Locations.
throttling (boolean | ThrottlingOptions)
Control the monitor’s download speeds, upload speeds, and latency to simulate your application’s behavior on slower or laggier networks. Set to false to disable throttling altogether.
screenshot (ScreenshotOptions)
Control whether or not to capture screenshots. Options include 'on', 'off', or 'only-on-failure'.

For information on configuring monitors individually, refer to Configure individual monitors.