Use the Synthetics CLIedit
@elastic/synthetics
edit
The Synthetics app uses the npx @elastic/synthetics
command to run and report synthetic tests.
It can also be used locally to help develop your tests.
npx @elastic/synthetics [options] [files] [dir]
You will not need to use most command line flags — they have been implemented purely to interact with the Synthetics app. However, there are some you may find useful:
-
--debug
- Prints debug info.
-
--match <name>
- Filters journey with the name or a matching tag.
-
--tags <name...>
- Filters journey with the given tag(s).
-
--reporter
-
One of
junit
,default
, orjson
. Use the JUnit reporter to provide easily parsed output to CI servers like Jenkins. -
--inline
-
Instead of reading from a file,
cat
inline scripted journeys and pipe them throughstdin
. For example,cat path/to/file.js | npx @elastic/synthetics --inline
. -
--playwright-options <jsonstring>
-
JSON object to pass in custom Playwright options for the agent.
Options passed will be merged with Playwright options defined in your synthetics.config.js file. Options defined via
--playwright-options
take precedence. -
--screenshots <on|off|only-on-failure>
- Captures screenshots for every step in the journey.
-
--no-throttling
- Does not apply throttling.
-
-h, --help
-
Shows help for the
npx @elastic/synthetics
command.
@elastic/synthetics init
edit
Scaffold a new project using Elastic Synthetics.
This will create a template Node.js project that includes the synthetics agent, required dependencies, a synthetics configuration file, and example journey files. These journeys can be edited and then pushed to Kibana to create monitors.
npx @elastic/synthetics init <name-of-project>
Read more about what’s included in a template project in Create a project.
@elastic/synthetics push
edit
Create monitors in Kibana by using your local journeys.
npx @elastic/synthetics push --auth <api-key> --url <kibana-url> --project <id|name>
The push
command includes interactive prompts to prevent you from accidentally deleting or duplicating monitors.
You will see a prompt when:
-
You
push
a project that used to contain one or more monitors but no longer contains any monitors. Selectyes
to delete all monitors associated with the project ID being pushed. -
You
push
a project that’s already been pushed using one project ID and then try topush
it using a different ID. Selectyes
to create duplicates of all monitors in the project.
If the journey contains external NPM packages other than the @elastic/synthetics
,
those packages will be bundled along with the journey code when the push
command is invoked.
However there are some limitations when using external packages:
- Bundled journeys after compression should not be more than 800 Kilobytes.
- Native node modules will not work as expected due to platform inconsistency.
-
--auth
-
API key used for Kibana authentication.
If you are pushing to a Private Location, you must use an API key generated in 8.4 or higher.
To create an API key, you must be logged into Kibana as a user with the privileges described in Writer role.
-
--url
- The Kibana URL for the deployment to which you want to upload the monitors.
-
--project
-
A unique id associated with your project.
It will be used for logically grouping monitors.
If you used
init
to create a project, this is the<name-of-project>
you specified. -
--yes
-
The
push
command includes interactive prompts to prevent you from accidentally deleting or duplicating monitors. If running the CLI non-interactively, you can override these prompts using the--yes
option. When the--yes
option is passed topush
:-
If you
push
a project that used to contain one or more monitors but no longer contains any monitors, all monitors associated with the project ID being pushed will be deleted. -
If you
push
a project that’s already been pushed using one project ID and then try topush
it using a different ID, it will create duplicates of all monitors in the project.
-
If you
@elastic/synthetics locations
edit
List all available locations for running synthetics monitors.
npx @elastic/synthetics locations --url <kibana-host> --auth <api-key>
Run npx @elastic/synthetics locations
with no flags to list all the available global locations managed by Elastic for running synthetics monitors.
To list both locations on Elastic’s global managed infrastructure and {private-locations}, include:
-
--url
- The Kibana URL for the deployment from which to fetch all available public and Private Locations.
-
--auth
- API key used for Kibana authentication.