From ed4af75860e1fcf2e8de66c21b86e3725494e283 Mon Sep 17 00:00:00 2001 From: vigneshshanmugam Date: Tue, 6 Jul 2021 14:19:51 -0700 Subject: [PATCH 1/3] add synthetics configuration docs --- docs/en/observability/index.asciidoc | 2 + .../synthetics-configuration.asciidoc | 64 +++++++++++++++++++ .../synthetics-params-secrets.asciidoc | 10 +-- 3 files changed, 71 insertions(+), 5 deletions(-) create mode 100644 docs/en/observability/synthetics-configuration.asciidoc diff --git a/docs/en/observability/index.asciidoc b/docs/en/observability/index.asciidoc index 08212729e1..9097aa742e 100644 --- a/docs/en/observability/index.asciidoc +++ b/docs/en/observability/index.asciidoc @@ -102,6 +102,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] diff --git a/docs/en/observability/synthetics-configuration.asciidoc b/docs/en/observability/synthetics-configuration.asciidoc new file mode 100644 index 0000000000..57f5c76802 --- /dev/null +++ b/docs/en/observability/synthetics-configuration.asciidoc @@ -0,0 +1,64 @@ +[[synthetics-configuration]] += Synthetic tests configuration + +++++ +Synthetic tests configuration +++++ + +beta[] Synthetic tests support the configuration of dynamic parameters that can be +used in the suites. In addition to that, 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`, `viewport`. + +[discrete] +[[synthetics-config-file]] +== Global Synthetics Configuration + +Create `synthetics.config.js` or `synthetics.config.ts` in the root of +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 return either a function or an object which will be + +To know more about configuring the tests based on environments, look at the +<> documentation. + +[discrete] +[[synthetics-config-device-emulation]] +=== Device emulation + +Users can emulate a mobile device using the configuration file. Check +the example configuration below that 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. \ No newline at end of file diff --git a/docs/en/observability/synthetics-params-secrets.asciidoc b/docs/en/observability/synthetics-params-secrets.asciidoc index 22d0d69e13..19c5f0e75f 100644 --- a/docs/en/observability/synthetics-params-secrets.asciidoc +++ b/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. From a8e8682866ff06afb843b67e4d72946f1d1876ae Mon Sep 17 00:00:00 2001 From: Vignesh Shanmugam Date: Wed, 7 Jul 2021 15:51:27 -0700 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Brandon Morelli --- .../synthetics-configuration.asciidoc | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/en/observability/synthetics-configuration.asciidoc b/docs/en/observability/synthetics-configuration.asciidoc index 57f5c76802..8f45f93424 100644 --- a/docs/en/observability/synthetics-configuration.asciidoc +++ b/docs/en/observability/synthetics-configuration.asciidoc @@ -6,16 +6,16 @@ ++++ beta[] Synthetic tests support the configuration of dynamic parameters that can be -used in the suites. In addition to that, 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`, `viewport`. +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 `synthetics.config.js` or `synthetics.config.ts` in the root of -synthetics project and specify the options +Create a `synthetics.config.js` or `synthetics.config.ts` file in the root of the +synthetics project and specify the options: [source,js] ---- @@ -35,15 +35,15 @@ export default config; The configuration file can return either a function or an object which will be -To know more about configuring the tests based on environments, look at the -<> documentation. +To learn more about configuring synthetic tests based on environments, see +<>. [discrete] [[synthetics-config-device-emulation]] === Device emulation -Users can emulate a mobile device using the configuration file. Check -the example configuration below that runs tests in "Pixel 5" emulation mode. +Users can emulate a mobile device using the configuration file. +The example configuration below runs tests in "Pixel 5" emulation mode. [source,js] ---- @@ -61,4 +61,4 @@ export default config; NOTE: Synthetics tests configuration can only be used along with synthetics -projects and is not available for inline suites. \ No newline at end of file +projects and is not available for inline suites. From 2c0e703a5205cf62435794cc7c26738b73b47a7c Mon Sep 17 00:00:00 2001 From: vigneshshanmugam Date: Wed, 7 Jul 2021 15:57:06 -0700 Subject: [PATCH 3/3] complete the export sentence --- docs/en/observability/synthetics-configuration.asciidoc | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/en/observability/synthetics-configuration.asciidoc b/docs/en/observability/synthetics-configuration.asciidoc index 8f45f93424..7dd42dd63b 100644 --- a/docs/en/observability/synthetics-configuration.asciidoc +++ b/docs/en/observability/synthetics-configuration.asciidoc @@ -33,10 +33,9 @@ const config: SyntheticsConfig = { export default config; ---- -The configuration file can return either a function or an object which will be - -To learn more about configuring synthetic tests based on environments, see -<>. +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 <> documentation. [discrete] [[synthetics-config-device-emulation]]