Technical preview

Synthetic tests support the configuration of dynamic parameters that can be used in Synthetics 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. For example:

import type { SyntheticsConfig } from '@elastic/synthetics';

export default env => {
  const config: SyntheticsConfig = {
    params: {
      url: 'https://www.elastic.co',
    },
    playwrightOptions: {
      ignoreHTTPSErrors: false,
    },
    /**
     * Configure global monitor settings
     */
    monitor: {
      schedule: 10,
      locations: [ 'us_east' ],
    },
    /**
     * Synthetic project monitors settings
     */
    project: {
      id: 'my-synthetics-project',
      url: 'https://abc123',
    },
  };
  if (env !== 'development') {
  /**
   * Override configuration specific to environment
   * For example, config.params.url = ""
   */
  }
  return 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

A JSON object that defines any variables your tests require. Read more in Work with params and secrets.

playwrightOptions

For all available options, refer to the Playwright documentation.

Below are details on a few Playwright options that are particularly relevant to Elastic Synthetics including timeouts, timezones, and device emulation.

Timeouts

Playwright has two types of timeouts that are used in Elastic Synthetics: action and navigation timeouts.

Elastic Synthetics uses a default action and navigation timeout of 50 seconds. You can override this default using actionTimeout and navigationTimeout in playwrightOptions.

Timezones and locales

The Elastic global managed testing infrastructure does not currently set the timezone. For Private Locations, the monitors will use the timezone of the host machine running the Elastic Agent. This is not always desirable if you want to test how a web application behaves across different timezones. To specify what timezone to use when the monitor runs, you can use playwrightOptions on a per monitor or global basis.

To use a timezone and/or locale for all monitors in the Synthetics project, set locale and/or timezoneId in the configuration file:

playwrightOptions: {
  locale: 'en-AU',
  timezoneId: 'Australia/Brisbane',
}

To use a timezone and/or locale for a specific monitor, add these options to a journey using monitor.use.

Device emulation

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;

project

Information about the Synthetics project.

id (string)

A unique id associated with your Synthetics project. It will be used for logically grouping monitors.

If you used init to create a Synthetics project, this is the <name-of-synthetics-project> you specified.

url (string)

The URL for the Observability project to which you want to upload the monitors.

monitor

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 UI 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:

• Run the elastic-synthetics locations command.
• Go to Synthetics → Management and click Create monitor. Locations will be listed in Locations.

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 URL for the Observability project from which to fetch available locations.
• Go to Synthetics → Management 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'.

alert.status.enabled (boolean)

Enable or disable monitor status alerts. Read more about alerts in Alerting.

retestOnFailure (boolean)

Enable or disable retesting when a monitor fails. Default is true.

By default, monitors are automatically retested if the monitor goes from "up" to "down". If the result of the retest is also "down", an error will be created, and if configured, an alert sent. Then the monitor will resume running according to the defined schedule.

Using retestOnFailure can reduce noise related to transient problems.

For information on configuring monitors individually, refer to:

• Configure individual browser monitors for browser monitors
• Configure lightweight monitors for lightweight monitors