Configure a Synthetics project

[preview] This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.

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.

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

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

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

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',
    }
  ],
}

clientCertificates: [
  {
    cert: "-----BEGIN CERTIFICATE-----\n...",
    // Not cert: Buffer.from("-----BEGIN CERTIFICATE-----\n..."),
  }
],

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.

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.

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;

Information about the Synthetics project.

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

For information on configuring monitors individually, refer to: