Working with params and secrets
editWorking with params and secrets
editIn version 7.x
, browser checks are in beta and will never be made generally available in 7.x
.
If you want to use browser checks, we highly recommend using the latest version of browser checks available in 8.x
. This functionality has changed significantly in version 8.x
. We do not recommend using browser checks in 7.x
anymore.
[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.
Parameter Basics
editWhen 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:
- Declaring a default value for the parameter in a configuration file.
-
Passing the
--params
CLI argument. -
Specifying the parameter in the heartbeat yaml config using the
params
option.
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.
Using a config file to set params
editUse 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.
Using CLI arguments to set params
editTo 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"}'
Using Heartbeat options to set params
editWhen 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"
Working with secrets and sensitive values
editYour 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.