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 TLS client authentication, timeouts, timezones, and device emulation.

TLS client authentication
edit

To enable TLS client authentication, set the clientCertificates option in the configuration file:

Path-based options {certPath, keyPath, pfxPath} are only supported on Private Locations, defer to in-memory alternatives {cert, key, pfx} when running on locations hosted by Elastic.

playwrightOptions: {
  clientCertificates: [
    {
      origin: 'https://example.com',
      certPath: './cert.pem',
      keyPath: './key.pem',
      passphrase: 'mysecretpassword',
    },
    {
      origin: 'https://example.com',
      cert: Buffer.from("-----BEGIN CERTIFICATE-----\n..."),
      key: Buffer.from("-----BEGIN RSA PRIVATE KEY-----\n..."),
      passphrase: 'mysecretpassword',
    }
  ],
}

When using Synthetics monitor UI, cert, key and pfx can simply be specified using a string literal:

clientCertificates: [
  {
    cert: "-----BEGIN CERTIFICATE-----\n...",
    // Not cert: Buffer.from("-----BEGIN CERTIFICATE-----\n..."),
  }
],
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.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.

fields (object)

A list of key-value pairs that will be sent with each monitor event. The fields are appended to Elasticsearch documents as labels, and those labels are displayed in Kibana in the Monitor details panel in the individual monitor’s Overview tab.

For example:

fields: {
  foo: 'bar',
  team: 'synthetics',
}

For information on configuring monitors individually, refer to: