add synthetics configuration docs (#847)

* add synthetics configuration docs

* Apply suggestions from code review

Co-authored-by: Brandon Morelli <[email protected]>

* complete the export sentence

Co-authored-by: Brandon Morelli <[email protected]>

docs/en/observability/index.asciidoc

@@ -103,6 +103,8 @@ include::synthetics-visualize.asciidoc[leveloffset=+2]
 
 include::synthetics-params-secrets.asciidoc[leveloffset=+2]
 
+include::synthetics-configuration.asciidoc[leveloffset=+2]
+
 // User experience
 include::user-experience.asciidoc[leveloffset=+1]
 

docs/en/observability/synthetics-configuration.asciidoc

@@ -0,0 +1,63 @@
+[[synthetics-configuration]]
+= Synthetic tests configuration
+
+++++
+<titleabbrev>Synthetic tests configuration</titleabbrev>
+++++
+
+beta[] Synthetic tests support the configuration of dynamic parameters that can be
+used in the suites. In addition, the Synthetics agent, which is built on top
+of Playwright, supports configuring browser and context options that are available
+in Playwright specific methods, for example, `ignoreHTTPSErrors` and `viewport`. 
+
+[discrete]
+[[synthetics-config-file]]
+== Global Synthetics Configuration
+
+Create a `synthetics.config.js` or `synthetics.config.ts` file in the root of the
+synthetics project and specify the options:
+
+[source,js]
+----
+import { SyntheticsConfig } from "@elastic/synthetics"
+
+const config: SyntheticsConfig = {
+  params: {
+    url: "https://www.elastic.co"
+  },
+  playwrightOptions: {
+    ignoreHTTPSErrors: true, // ignores all HTTPS errors during navigation
+  }
+}
+
+export default config;
+----
+
+The configuration file can either export an object, or a function that when
+called should return the generated configuration. To know more about configuring
+the tests based on environments, look at the <<synthetics-dynamic-configs, dynamic configuration>> documentation.
+
+[discrete]
+[[synthetics-config-device-emulation]]
+=== Device emulation
+
+Users can emulate a mobile device using the configuration file.
+The example configuration below runs tests in "Pixel 5" emulation mode.
+
+[source,js]
+----
+import { SyntheticsConfig } from "@elastic/synthetics"
+import { devices } from "playwright-chromium"
+
+const config: SyntheticsConfig = {
+  playwrightOptions: {
+    ...devices['Pixel 5']
+  }
+}
+
+export default config;
+----
+
+
+NOTE: Synthetics tests configuration can only be used along with synthetics
+projects and is not available for inline suites.

docs/en/observability/synthetics-params-secrets.asciidoc

@@ -39,7 +39,7 @@ If you try to run the example above you'll notice an error because we haven't sp
 Parameter values can be declared by any of the following methods:
 
 * Declaring a default value for the parameter in a configuration file.
-* Passing the `--suite-params` CLI argument. 
+* 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
@@ -48,7 +48,7 @@ option, with the CLI and Heartbeat options taking precedence over the configurat
 These options are discussed in detail in the sections below.
 
 [discrete]
-[[synthetics-configs]]
+[[synthetics-dynamic-configs]]
 == Using a config file to set params
 
 Use a `synthetics.config.js` or `synthetics.config.ts` file to define variables your tests always need to be defined. 
@@ -76,15 +76,15 @@ Note that we use the `env` variable in the above example, which corresponds to t
 [[synthetics-cli-params]]
 == Using CLI arguments to set params
 
-To set parameters when running `elastic-synthetics` on the command line, use the `--suite-params` or `-s` arguments to the `elastic-synthetics` program. The provided map is merged over any existing variables defined in the `synthetics.config.{js,ts}` file.
+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 . --suite-params '{"url": "http://localhost:8080"}'`
+To override the `url` parameter, you would run: `elastic-synthetics . --params '{"url": "http://localhost:8080"}'`
 
 [discrete]
 [[synthetics-hb-params]]
 == Using Heartbeat options to set params
 
-When running via Heartbeat use the `params` option to set additional parameters, passed through the `--suite-params` flag
+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.