IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Configure individual browser monitors Use the Synthetics Recorder »
Elastic Docs ›Observability Guide [8.7] ›Synthetic monitoring ›Scripting browser monitors

Work with params and secrets

edit

Work with params and secrets

edit

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 managing the synthetic monitors. Solving these problems is where params come in. params are variables that you can use within a synthetic project. They can be defined either in the project config file or the synthetics agent command line.

Because synthetics is a full JavaScript environment, it is also possible to use regular environment variables via the standard node process.env global object.

Parameter Basics

edit

When creating a project, 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);
    });
});

Note that in a typescript program you would want to instead use params.url as string.

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 in the following order:

  1. Global parameters: The Global parameters set in Kibana 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 Kibana and a 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 configuration file and using the CLI argument, the value defined using the CLI will be used. When running a script using the CLI, Kibana-defined Global parameters have no impact on the test because it won’t have access to Kibana.

Use a config file to set params

edit

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,
    },
  };
};

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

Use CLI arguments to set params

edit

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.

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

elastic-synthetics . --params '{"url": "http://localhost:8080"}'

Working with secrets and sensitive values

edit

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

Because synthetics scripts have no limitations, a malicious script author could write a synthetics journey that exfiltrates params and other data at runtime. Do not to use truly sensitive passwords (for example, an admin password or a real credit card) in any synthetics tools. Instead, set up limited demo accounts, or fake credit cards with limited functionality.

Use environment variables to handle any values needing encryption at rest. The example below uses the syntax ${URL} to reference a variable named URL defined in the environment:

- name: Todos
  id: todos
  type: browser
  schedule: "@every 3m"
  tags: todos-app
  params:
    url: ${URL}
  source:
    inline:
      script: |-
      step("load homepage", async () => {
        await page.goto(params.url);
      });
      step("hover over products menu", async () => {
        await page.hover('css=[data-nav-item=products]');
      });
« Configure individual browser monitors Use the Synthetics Recorder »