Working with params and secrets

[beta] This functionality is in beta and is subject to change. The design and code is less mature than official GA features and is being provided as-is with no warranties. Beta features are not subject to the support SLA of official GA features. You may need to use dynamically defined values in your synthetic scripts, which may sometimes be sensitive. For instance, you may want to test a production website with a particular demo account whose password is only known to the team administering Heartbeat. Another scenario might be using a different URL when running the tests under Heartbeat and then running them locally using the Synthetics agent. Solving these problems is where params come in. params are variables that you can use within a synthetic suite. They can be defined either in the suites config file, the synthetics agent command line, or in a Heartbeat YAML config file.

You should also note that since synthetics is a full JavaScript environment, it is also possible to use regular environment variables via the standard node process.env global object.

When writing a test suite, parameters can be referenced via the params property available within the argument to a journey, before, beforeAll, after, or afterAll callback function.

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

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

If you try to run the example above you’ll notice an error because we haven’t specified a value for the url parameter. Parameter values can be declared by any of the following methods:

The values in the configuration file are read first, then merged with either the CLI argument, or the Heartbeat option, with the CLI and Heartbeat options taking precedence over the configuration file.

These options are discussed in detail in the sections below.

Use a synthetics.config.js or synthetics.config.ts file to define variables your tests always need to be defined. This file should be placed in the root of your synthetics project.

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

Note that we use the env variable in the above example, which corresponds to the value of the NODE_ENV environment variable , or the environment parameter in the browser monitor definition when using Heartbeat.

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

To override the url parameter, you would run: elastic-synthetics . --params '{"url": "http://localhost:8080"}'

When running via Heartbeat use the params option to set additional parameters, passed through the --params flag mentioned above and have their values merged over any default values. In the example below we run the todos app, overriding the url parameter.

- name: Todos
  id: todos
  type: browser
  schedule: "@every 3m"
  tags: todos-app
  params:
    url: "https://elastic.github.io/synthetics-demo/"
  source:
    zip_url:
      url: "https://github.com/elastic/synthetics-demo/archive/refs/heads/main.zip"
      folder: "synthetics-tests"

Your synthetics scripts may require the use of passwords or other sensitive secrets that are not known till runtime. Before we continue, it is important to remember that since synthetics scripts have no limitations, a malicious script author could write a synthetics journey that exfiltrates params and other data at runtime. Therefore, it is generally best not to use truly sensitive passwords (e.g. an admin password to test an admin panel, or a real credit card) in any synthetics tools. Instead, set up limited dummy accounts, or fake credit cards with limited functionality.

Use either environment variables or the Heartbeat keystore to handle any values needing encryption at rest. As an example, the syntax ${URL} for instance, to reference a variable named URL in either the secret store or the environment. For example:

- name: Todos
  id: todos
  type: browser
  schedule: "@every 3m"
  tags: todos-app
  params:
    url: ${URL}
  source:
    zip_url:
      url: "https://github.com/elastic/synthetics-demo/archive/refs/heads/main.zip"
      folder: "synthetics-tests"

To setup the Heartbeat keystore see the Heartbeat keystore documentation.