[[monitor-browser-options]]
=== Browser options

TIP: Want to get started with synthetic monitoring?
See the {observability-guide}/synthetics-quickstart.html[quick start guide].

beta[] The options described here configure {beatname_uc} to run the synthetic
monitoring test suites via Synthetic Agent on the Chromium browser.
Additional shared options are defined in <<monitor-options>>. 

Browser based monitors can only be run in our {beatname_uc} docker image,
or via the `elastic-agent-complete` docker image. 
For more information, see {observability-guide}/synthetics-quickstart.html[Synthetic monitoring using Docker].

Example configuration:

[source,yaml]
----
- type: browser
  id: synthetic-inline-suites
  name: Elastic website
  schedule: '@every 1m'
  source:
    inline:
      script: |-
        step("load homepage", async () => {
          await page.goto('https://www.elastic.co');
        });
        step("hover over products menu", async () => {
          await page.hover('css=[data-nav-item=products]');
        });
----

[float]
[[monitor-browser-source]]
==== `source`

Contains information on how to run the synthetic test suites.

[float]
[[monitor-source-inline]]
===== `inline`

Runs the Synthetic test scripts that are defined inline in the configuration.
See {observability-guide}/synthetics-create-test.html[Synthetics syntax] for
more information.

This is the most convenient way to get Synthetic tests up and running, however, it becomes
harder to maintain and share code as the number of test files increases.
The recommended way to run Synthetic suites is to create an https://docs.npmjs.com/cli/v7/commands/npm-init[NPM project] and
start writing individual tests for all the user journeys and save them as JavaScript or
TypeScript files. Once the project is created, the tests can be invoked either by
<<monitor-source-zipurl,Zip Url>> or <<monitor-source-local,Local directory>> method.

NOTE: {beatname_uc} will use the latest compatible version(^1.0.0) of the
https://www.npmjs.com/package/@elastic/synthetics[Synthetics NPM library] to run
the inline journeys.

[float]
[[monitor-source-zipurl]]
===== `Zip URL`

Remote zip endpoint configuration allows users to specify the location
of a synthetics test project ZIP file.

Under `zip_url`, specify these options:

*`url`*:: Location of the synthetics project repository.
*`folder`*:: Relative directory path where the synthetic journey files are
located in the repository.
*`username`*:: The username for authenticating with the zip endpoint. This setting is optional.
*`password`*:: The password for authenticating with the zip endpoint. This setting is optional.
*`ssl`*:: SSL options applied to downloading the zip, not the browser. See <<configuration-ssl>> for more details.

If `username` and `password` are provided, they will be sent as HTTP Basic Authentication
headers to the remote zip endpoint.

Example configuration:

[source,yaml]
-------------------------------------------------------------------------------
- type: browser
  id: todos-suites
  name: Todos Journeys
  schedule: '@every 1m'
  source:
    zip_url:
      url: "https://github.com/elastic/synthetics/archive/refs/heads/master.zip"
      folder: "examples/todos"
      username: ""
      password: ""
      # ssl options apply to downloading the zip, not the browser
      #ssl:
      #  certificate_authorities: ['/etc/ca.crt']
-------------------------------------------------------------------------------

[float]
[[monitor-source-local]]
===== `Local directory`

Local directory where the synthetic test files are located.

Example configuration:

[source,yaml]
-------------------------------------------------------------------------------
- type: browser
  id: local-journeys
  name: Local journeys
  schedule: '@every 1m'
  source:
    local:
      path: "/path/to/synthetics/journeys"
-------------------------------------------------------------------------------

[float]
[[monitor-browser-params]]
==== `params`

Set this option to add user defined parameters for your scripts. This value takes
arbitrary YAML that is then converted to JSON which is then passed into synthetics
via the `--params` option. See {observability-guide}/synthetics-params-secrets.html[Working with Params]
for more information.

Example:

[source,yaml]
-------------------------------------------------------------------------------
- type: browser
  id: local-journeys
  name: Local journeys
  schedule: '@every 1m'
  source: # Omitted in this example for brevity
  params:
    root_url: http://example.net
    my_custom_object:
      a_key: ["a value"]
-------------------------------------------------------------------------------

[float]
[[monitor-browser-screenshots]]
==== `screenshots`

Set this option to manage the screenshots captured by the synthetics agent.

Under `screenshots`, specify one of these options:

*`on`*:: capture screenshots for all steps in a journey (default)
*`off`*:: do not capture any screenshots
*`only-on-failure`*:: capture screenshots for all steps when a journey fails
(any failing step marks the whole journey as failed)

Example configuration:

[source,yaml]
-------------------------------------------------------------------------------
- type: browser
  id: local-journeys
  name: Local journeys
  schedule: '@every 1m'
  screenshots: "on"
  source:
    local:
      path: "/path/to/synthetics/journeys"
-------------------------------------------------------------------------------

[float]
[[monitor-browser-ignore-https-errors]]
==== `ignore_https_errors`

Set this option to `true` to disable TLS/SSL validation in the synthetics browser. This is useful for testing
sites that use self-signed certs. This option can also be used to test certs from non-standard CAs,
though you will no longer get errors if there is anything wrong with the certificate.


[float]
[[monitor-browser-sandbox]]
==== `sandbox`

Set this option to `true` to enable the normally disabled chromium sandbox.
Defaults to false.

[float]
[[monitor-browser-throttling]]
==== `throttling`

Set this option to control the network throttling. By default, all journeys are
run with 5Mbps download, 3Mbps upload and 20ms latency which emulates a standard
Cabel connection.

Users can control the throttling parameters, Below is an example of emulating a
3G connection with 1.6Mbps download, 750Kbps upload and 150ms round trip time.

[source,yaml]
-------------------------------------------------------------------------------
- type: browser
  schedule: '@every 1m'
  throttling: "1.6d/0.75u/150l"
-------------------------------------------------------------------------------

Network throttling can be completely disabled by passing `false`

[source,yaml]
-------------------------------------------------------------------------------
- type: browser
  schedule: '@every 1m'
  throttling: false
-------------------------------------------------------------------------------


[float]
[[monitor-browser-filter-journeys]]
==== `filter_journeys`

Set this option to filter journeys based on journey tags and names.


Example configuration:

[source,yaml]
-------------------------------------------------------------------------------
- type: browser
  id: local-journeys
  name: Local journeys
  schedule: '@every 1m'
  filter_journeys:
    tags: ["browse", "checkout"]
    match: "login*"
  source:
    local:
      path: "/path/to/synthetics/journeys"
-------------------------------------------------------------------------------

*`tags`*:: run only journeys with the given tag(s), or globs
*`match`*:: run only journeys with a name or tags that matches the configured glob

[float]
[[monitor-browser-synthetics-args]]
==== `synthetics_args`

Extra arguments to pass to the synthetics agent package. Takes a list of
strings.
