Technical preview

Params allow you to use dynamically defined values in your synthetic monitors. For example, you may want to test a production website with a particular demo account whose password is only known to the team managing the synthetic monitors.

For more information about security-sensitive use cases, refer to Work with params and secrets.

Define params

Param values can be declared by any of the following methods:

• In the Global parameters tab of the Synthetics Settings page in an Observability project.
• Declaring a default value for the parameter in a configuration file.
• Passing the --params CLI argument.

The values in the configuration file are read in the following order:

1. Global parameters in an Observability project: The Global parameters set using the Observability project's UI are read first.
2. Configuration file: Then the Global parameters are merged with any parameters defined in a configuration file. If a parameter is defined in both the Observability project and a Synthetics project configuration file, the value in the configuration file will be used.
3. CLI: Then the parameters defined in the configuration are merged with any parameters passed to the CLI --params argument. If a parameter is defined in a Synthetics project configuration file and using the CLI argument, the value defined using the CLI will be used. When running a script using the CLI, Global parameters defined in the Observability project have no impact on the test because it won't have access to the Observability project.

Global parameters in your Observability project

From any page in the Observability project's Synthetics section:

1. Go to Settings.
2. Go to the Global parameters tab.
3. Define parameters.

— Click to open this image in fullscreen mode

Synthetics project config file

Use a synthetics.config.js or synthetics.config.ts file to define variables required by your tests. This file should be placed in the root of your Synthetics project.

export default (env) => {
  let my_url = "http://localhost:8080";
  if (env === "production") {
    my_url = "https://elastic.github.io/synthetics-demo/"
  }
  return {
    params: {
      my_url,
    },
  };
};

The example above uses the env variable, which corresponds to the value of the NODE_ENV environment variable.

CLI argument

To set parameters when running npx @elastic/synthetics on the command line, use the --params or -p flag. The provided map is merged over any existing variables defined in the synthetics.config.{js,ts} file.

For example, to override the my_url parameter, you would run:

npx @elastic/synthetics . --params '{"my_url": "http://localhost:8080"}'

Use params

You can use params in both lightweight and browser monitors created in either a Synthetics project or the Synthetics UI in your Observability project.

In a Synthetics project

For lightweight monitors in a Synthetics project, wrap the name of the param in ${} (for example, ${my_url}).

- type: http
  name: Todos Lightweight
  id: todos-lightweight
  urls: ["${my_url}"]
  schedule: '@every 1m'

In browser monitors, parameters can be referenced via the params property available within the argument to a journey, before, beforeAll, after, or afterAll callback function.

Add params. before the name of the param (for example, params.my_url):

beforeAll(({params}) => {
  console.log(`Visiting ${params.my_url}`)
})

journey("My Journey", ({ page, params }) => {
  step('launch app', async () => {
    await page.goto(params.my_url) 
  })
})

In the UI

To use a param in a lightweight monitor that is created in the Synthetics UI, wrap the name of the param in ${} (for example, ${my_url}).

— Click to open this image in fullscreen mode

To use a param in a browser monitor that is created in the Synthetics UI, add params. before the name of the param (for example, params.my_url).

— Click to open this image in fullscreen mode

Working with secrets and sensitive values

Your synthetics scripts may require the use of passwords or other sensitive secrets that are not known until runtime.

If you are managing monitors with a Synthetics project, you can use environment variables in your synthetics.config.ts or synthetics.config.js file.

The example below uses process.env.MY_URL to reference a variable named MY_URL defined in the environment and assigns its value to a param. That param can then be used in both lightweight and browser monitors that are managed in the Synthetics project:

export default {
  params: {
    my_url: process.env.MY_URL
  }
};