Configure Synthetics projects

edit

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. 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' ],
    },
    /**
     * Project monitors settings
     */
    project: {
      id: 'my-project',
      url: 'https://abc123',
      space: 'custom-space',
    },
  };
  if (env !== 'development') {
    /**
     * Override configuration specific to environment
     * For example, config.params.url = ""
     */
  }
  return config;
};

env in the example above is the environment you are pushing from not the environment where monitors will run. In other words, env corresponds to the configured NODE_ENV.

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

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

playwrightOptions

edit

For all available options, refer to the Playwright documentation.

Do not attempt to run in headful mode (using headless:false) when running through Elastic’s global managed testing infrastructure or Private Locations as this is not supported.

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

Timeouts

edit

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

edit

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

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;

project

edit

Information about the project.

id (string)

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

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

url (string)
The Kibana URL for the deployment to which you want to upload the monitors.
space (string)
The identifier of the target Kibana space for the pushed monitors. Spaces help you organize pushed monitors. Pushes to the "default" space if not specified.

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'.
alert (AlertConfig)

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

status.enabled (boolean)
Enable monitor status alerts.
tls.enabled (boolean)
Enable TLS certificate alerts.

For information on configuring monitors individually, refer to: