@elastic/synthetics 1.7.2 → 1.9.0

package/src/cli.ts

@@ -56,33 +56,38 @@ import { installTransform } from './core/transform';
 /* eslint-disable-next-line @typescript-eslint/no-var-requires */
 const { name, version } = require('../package.json');
 
-const { params, pattern, playwrightOpts, auth, authMandatory } =
-  getCommonCommandOpts();
+const {
+  params,
+  pattern,
+  playwrightOpts,
+  auth,
+  authMandatory,
+  configOpt,
+  tags,
+  match,
+} = getCommonCommandOpts();
 
 program
   .name(`npx ${name}`)
   .usage('[options] [dir] [files] file')
-  .option(
-    '-c, --config <path>',
-    'configuration path (default: synthetics.config.js)'
-  )
+  .addOption(configOpt)
   .addOption(pattern)
+  .addOption(tags)
+  .addOption(match)
   .addOption(params)
-  .option('--tags <name...>', 'run tests with a tag that matches the glob')
-  .option(
-    '--match <name>',
-    'run tests with a name or tags that matches the glob'
-  )
   .addOption(
     new Option('--reporter <value>', `output reporter format`).choices(
       Object.keys(reporters)
     )
   )
-  .option('--inline', 'Run inline journeys from heartbeat')
+  .option('--inline', 'read journeys from stdin instead of reading from files')
   .option('-r, --require <modules...>', 'module(s) to preload')
   .option('--sandbox', 'enable chromium sand-boxing')
-  .option('--rich-events', 'Mimics a heartbeat run')
-  .option('--no-headless', 'run browser in head-full mode')
+  .option(
+    '--rich-events',
+    'preset flag used when running monitors directly via Heartbeat'
+  )
+  .option('--no-headless', 'run with the browser in headful mode')
   .option(
     '--capability <features...>',
     'Enable capabilities through feature flags'
@@ -90,7 +95,7 @@ program
   .addOption(
     new Option(
       '--screenshots [flag]',
-      'take screenshots at end of each step'
+      'Control whether to capture screenshots at the end of each step'
     ).choices(['on', 'off', 'only-on-failure'])
   )
   .option(
@@ -160,6 +165,7 @@ program
   .description(
     'Push all journeys in the current directory to create monitors within the Kibana monitor management UI'
   )
+  .addOption(authMandatory)
   .option(
     '--schedule <time-in-minutes>',
     "schedule in minutes for the pushed monitors. Setting `10`, for example, configures monitors which don't have an interval defined to run every 10 minutes.",
@@ -175,7 +181,7 @@ program
     '--private-locations <locations...>',
     'default list of private locations from which your monitors will run.'
   )
-  .option('--url <url>', 'Kibana URL to upload the monitors')
+  .option('--url <url>', 'Kibana URL to upload the project monitors')
   .option(
     '--id <id>',
     'project id that will be used for logically grouping monitors'
@@ -185,20 +191,23 @@ program
     'the target Kibana spaces for the pushed monitors — spaces help you organise pushed monitors.'
   )
   .option('-y, --yes', 'skip all questions and run non-interactively')
-  .addOption(authMandatory)
+
   .addOption(pattern)
+  .addOption(tags)
+  .addOption(match)
   .addOption(params)
   .addOption(playwrightOpts)
-  .action(async (cmdOpts: PushOptions) => {
+  .addOption(configOpt)
+  .action(async cmdOpts => {
+    cmdOpts = { ...cmdOpts, ...program.opts() };
     const workDir = cwd();
-    const tearDown = await globalSetup({ inline: false, ...program.opts() }, [
+    const tearDown = await globalSetup({ inline: false, ...cmdOpts }, [
       workDir,
     ]);
     try {
-      const settings = await loadSettings();
+      const settings = await loadSettings(cmdOpts.config);
       const options = (await normalizeOptions(
         {
-          ...program.opts(),
           ...settings,
           ...cmdOpts,
         },
@@ -244,8 +253,7 @@ program
   .addOption(auth)
   .action(async (cmdOpts: LocationCmdOptions) => {
     const revert = installTransform();
-    const url = cmdOpts.url ?? (await loadSettings(true))?.url;
-
+    const url = cmdOpts.url ?? (await loadSettings(null, true))?.url;
     try {
       if (url && cmdOpts.auth) {
         const allLocations = await getLocations({

package/src/common_types.ts

@@ -200,13 +200,18 @@ export type ThrottlingOptions = {
   latency?: number;
 };
 
+type GrepOptions = {
+  pattern?: string;
+  tags?: Array<string>;
+  match?: string;
+};
+
 type BaseArgs = {
   params?: Params;
   screenshots?: ScreenshotOptions;
   dryRun?: boolean;
-  pattern?: string;
-  match?: string;
-  tags?: Array<string>;
+  config?: string;
+  auth?: string;
   outfd?: number;
   wsEndpoint?: string;
   pauseOnError?: boolean;
@@ -219,7 +224,9 @@ type BaseArgs = {
 };
 
 export type CliArgs = BaseArgs & {
-  config?: string;
+  pattern?: string;
+  match?: string;
+  tags?: Array<string>;
   reporter?: BuiltInReporterName;
   inline?: boolean;
   require?: Array<string>;
@@ -239,6 +246,7 @@ export type RunOptions = BaseArgs & {
   environment?: string;
   networkConditions?: NetworkConditions;
   reporter?: BuiltInReporterName | ReporterInstance;
+  grepOpts?: GrepOptions;
 };
 
 export type PushOptions = Partial<ProjectSettings> &
@@ -246,9 +254,11 @@ export type PushOptions = Partial<ProjectSettings> &
     auth: string;
     kibanaVersion?: string;
     yes?: boolean;
+    tags?: Array<string>;
     alert?: AlertConfig;
     retestOnFailure?: MonitorConfig['retestOnFailure'];
     enabled?: boolean;
+    grepOpts?: GrepOptions;
   };
 
 export type ProjectSettings = {

package/src/core/runner.ts

@@ -404,8 +404,7 @@ export default class Runner {
 
   buildMonitors(options: PushOptions) {
     /**
-     * Update the global monitor configuration required for
-     * setting defaults
+     * Update the global monitor configuration required for setting defaults
      */
     this.updateMonitor({
       throttling: options.throttling,
@@ -430,11 +429,23 @@ export default class Runner {
         );
       }
       /**
-       * Execute dummy callback to get all monitor specific
-       * configurations for the current journey
+       * Before pushing a browser monitor, three things need to be done:
+       *
+       * - execute callback `monitor.use` in particular to get monitor configurations
+       * - update the monitor config with global configuration
+       * - filter out monitors based on matched tags and name after applying both
+       *  global and local monitor configurations
        */
       journey.callback({ params: options.params } as any);
       journey.monitor.update(this.monitor?.config);
+      if (
+        !journey.monitor.isMatch(
+          options.grepOpts?.match,
+          options.grepOpts?.tags
+        )
+      ) {
+        continue;
+      }
       journey.monitor.validate();
       monitors.push(journey.monitor);
     }
@@ -454,7 +465,7 @@ export default class Runner {
       params: options.params,
     }).catch(e => (this.hookError = e));
 
-    const { dryRun, match, tags } = options;
+    const { dryRun, grepOpts } = options;
     /**
      * Skip other journeys when using `.only`
      */
@@ -471,7 +482,7 @@ export default class Runner {
         this.#reporter.onJourneyRegister?.(journey);
         continue;
       }
-      if (!journey.isMatch(match, tags) || journey.skip) {
+      if (!journey.isMatch(grepOpts?.match, grepOpts?.tags) || journey.skip) {
         continue;
       }
       const journeyResult: JourneyResult = this.hookError

package/src/dsl/monitor.ts

@@ -33,7 +33,7 @@ import {
   Params,
   PlaywrightOptions,
 } from '../common_types';
-import { indent } from '../helpers';
+import { indent, isMatch } from '../helpers';
 import { LocationsMap } from '../locations/public-locations';
 
 export type SyntheticsLocationsType = keyof typeof LocationsMap;
@@ -129,6 +129,18 @@ export class Monitor {
     this.filter = filter;
   }
 
+  /**
+   * Matches monitors based on the provided args. Proitize tags over match
+   */
+  isMatch(matchPattern: string, tagsPattern: Array<string>) {
+    return isMatch(
+      this.config.tags,
+      this.config.name,
+      tagsPattern,
+      matchPattern
+    );
+  }
+
   /**
    * Hash is used to identify if the monitor has changed since the last time
    * it was pushed to Kibana. Change is based on three factors:

package/src/generator/index.ts

@@ -22,13 +22,14 @@
  * THE SOFTWARE.
  *
  */
+import { URL } from 'url';
 import { execSync } from 'child_process';
 import { existsSync } from 'fs';
 import { mkdir, readFile, writeFile } from 'fs/promises';
 import { bold, cyan, yellow } from 'kleur/colors';
 import { join, relative, dirname, basename } from 'path';
 // @ts-ignore-next-line: has no exported member 'Input'
-import { prompt, Input } from 'enquirer';
+import { prompt, Input, Password } from 'enquirer';
 import { getProjectApiKeyURL, progress, write as stdWrite } from '../helpers';
 import {
   getPackageManager,
@@ -60,6 +61,8 @@ export const REGULAR_FILES_PATH = [
 ];
 export const CONFIG_PATH = 'synthetics.config.ts';
 
+const IS_URL = new RegExp('^(https?:\\/\\/)');
+
 export class Generator {
   pkgManager = 'npm';
   constructor(public projectDir: string) {}
@@ -80,29 +83,30 @@ export class Generator {
       return JSON.parse(process.env.TEST_QUESTIONS);
     }
 
-    const { onCloud } = await prompt<{ onCloud: string }>({
-      type: 'confirm',
-      name: 'onCloud',
-      initial: 'y',
-      message: 'Do you use Elastic Cloud',
-    });
     const url = await new Input({
-      header: onCloud
-        ? yellow(
-            'Get cloud.id from your deployment https://www.elastic.co/guide/en/cloud/current/ec-cloud-id.html'
-          )
-        : '',
-      message: onCloud
-        ? 'What is your cloud.id'
-        : 'What is the url of your Kibana instance',
       name: 'url',
+      message: 'Enter Elastic Kibana URL or Cloud ID',
       required: true,
-      result(value) {
-        return onCloud ? cloudIDToKibanaURL(value) : value;
+      validate(value) {
+        try {
+          if (!IS_URL.test(value)) {
+            value = cloudIDToKibanaURL(value);
+          }
+          new URL(value);
+          return true;
+        } catch (e) {
+          return 'Invalid URL or Cloud ID';
+        }
+      },
+      result(value: string) {
+        if (!IS_URL.test(value)) {
+          value = cloudIDToKibanaURL(value);
+        }
+        return value;
       },
     }).run();
 
-    const auth = await new Input({
+    const auth = await new Password({
       name: 'auth',
       header: yellow(
         `Generate API key from Kibana ${getProjectApiKeyURL(url)}`
@@ -249,7 +253,7 @@ export class Generator {
     }
     // Add push command
     if (!pkgJSON.scripts.push) {
-      pkgJSON.scripts.push = 'npx @elastic/synthetics push';
+      pkgJSON.scripts.push = `npx @elastic/synthetics push`;
     }
 
     await this.createFile(
@@ -287,7 +291,7 @@ All set, you can run below commands inside: ${this.projectDir}:
   )}
 
   ${yellow(
-    'Make sure to configure the SYNTHETICS_API_KEY before pushing monitors to Kibana.'
+    'Configure API Key via `SYNTHETICS_API_KEY` env variable or --auth CLI flag.'
   )}
 
 Visit https://www.elastic.co/guide/en/observability/current/synthetic-run-tests.html to learn more.

package/src/options.ts

@@ -26,74 +26,49 @@
 import merge from 'deepmerge';
 import { createOption } from 'commander';
 import { readConfig } from './config';
-import type { CliArgs, PushOptions, RunOptions } from './common_types';
-import { THROTTLING_WARNING_MSG, error, warn } from './helpers';
+import type { CliArgs, RunOptions } from './common_types';
+import { THROTTLING_WARNING_MSG, warn } from './helpers';
 
 type Mode = 'run' | 'push';
 
+/**
+ * Normalize the options passed via CLI and Synthetics config file
+ *
+ * Order of preference for options:
+ * 1. Local options configured via Runner API
+ * 2. CLI flags
+ * 3. Configuration file
+ */
 export async function normalizeOptions(
   cliArgs: CliArgs,
   mode: Mode = 'run'
 ): Promise<RunOptions> {
+  /**
+   * Move filtering flags from the top level to filter object
+   * and delete the old keys
+   */
+  const grepOpts = {
+    pattern: cliArgs.pattern,
+    tags: cliArgs.tags,
+    match: cliArgs.match,
+  };
+  delete cliArgs.pattern;
+  delete cliArgs.tags;
+  delete cliArgs.match;
+
   const options: RunOptions = {
     ...cliArgs,
+    grepOpts,
     environment: process.env['NODE_ENV'] || 'development',
   };
   /**
-   * Group all events that can be consumed by heartbeat and
-   * eventually by the Synthetics UI.
-   */
-  if (cliArgs.richEvents) {
-    options.reporter = cliArgs.reporter ?? 'json';
-    options.ssblocks = true;
-    options.network = true;
-    options.trace = true;
-    options.quietExitCode = true;
-  }
-
-  if (cliArgs.capability) {
-    const supportedCapabilities = [
-      'trace',
-      'network',
-      'filmstrips',
-      'metrics',
-      'ssblocks',
-    ];
-    /**
-     * trace - record chrome trace events(LCP, FCP, CLS, etc.) for all journeys
-     * network - capture network information for all journeys
-     * filmstrips - record detailed filmstrips for all journeys
-     * metrics - capture performance metrics (DOM Nodes, Heap size, etc.) for each step
-     * ssblocks - Dedupes the screenshots in to blocks to save storage space
-     */
-    for (const flag of cliArgs.capability) {
-      if (supportedCapabilities.includes(flag)) {
-        options[flag] = true;
-      } else {
-        console.warn(
-          `Missing capability "${flag}", current supported capabilities are ${supportedCapabilities.join(
-            ', '
-          )}`
-        );
-      }
-    }
-  }
-
-  /**
-   * Validate and read synthetics config file
-   * based on the environment
+   * Validate and read synthetics config file based on the environment
    */
   const config =
     cliArgs.config || !cliArgs.inline
       ? await readConfig(options.environment, cliArgs.config)
       : {};
 
-  /**
-   * Order of preference for options that are used while running are
-   * 1. Local options configured via Runner API
-   * 2. CLI flags
-   * 3. Configuration file
-   */
   options.params = Object.freeze(merge(config.params, cliArgs.params || {}));
 
   /**
@@ -118,10 +93,49 @@ export async function normalizeOptions(
    */
   switch (mode) {
     case 'run':
+      if (cliArgs.capability) {
+        const supportedCapabilities = [
+          'trace',
+          'network',
+          'filmstrips',
+          'metrics',
+          'ssblocks',
+        ];
+        /**
+         * trace - record chrome trace events(LCP, FCP, CLS, etc.) for all journeys
+         * network - capture network information for all journeys
+         * filmstrips - record detailed filmstrips for all journeys
+         * metrics - capture performance metrics (DOM Nodes, Heap size, etc.) for each step
+         * ssblocks - Dedupes the screenshots in to blocks to save storage space
+         */
+        for (const flag of cliArgs.capability) {
+          if (supportedCapabilities.includes(flag)) {
+            options[flag] = true;
+          } else {
+            console.warn(
+              `Missing capability "${flag}", current supported capabilities are ${supportedCapabilities.join(
+                ', '
+              )}`
+            );
+          }
+        }
+      }
+
+      /**
+       * Group all events that can be consumed by heartbeat and
+       * eventually by the Synthetics UI.
+       */
+      if (cliArgs.richEvents) {
+        options.reporter = cliArgs.reporter ?? 'json';
+        options.ssblocks = true;
+        options.network = true;
+        options.trace = true;
+        options.quietExitCode = true;
+      }
+
       options.screenshots = cliArgs.screenshots ?? 'on';
       break;
     case 'push':
-      validatePushOptions(options as PushOptions);
       /**
        * Merge the default monitor config from synthetics.config.ts file
        * with the CLI options passed via push command
@@ -152,14 +166,6 @@ export function getHeadlessFlag(
   return configHeadless ?? true;
 }
 
-export function validatePushOptions(opts: PushOptions) {
-  if (opts.tags || opts.match) {
-    throw error(`Aborted. Invalid CLI flags.
-
-Tags and Match are not supported in push command.`);
-  }
-}
-
 /* eslint-disable-next-line @typescript-eslint/no-unused-vars */
 function toObject(value: boolean | Record<string, any>): Record<string, any> {
   const defaulVal = {};
@@ -183,19 +189,17 @@ export function parseThrottling() {
 export function getCommonCommandOpts() {
   const params = createOption(
     '-p, --params <jsonstring>',
-    'JSON object that gets injected to all journeys'
-  );
-  params.argParser(JSON.parse);
+    'JSON object that defines any variables your tests require.'
+  ).argParser(JSON.parse);
 
   const playwrightOpts = createOption(
     '--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.'
-  );
-  playwrightOpts.argParser(JSON.parse);
+  ).argParser(JSON.parse);
 
   const pattern = createOption(
     '--pattern <pattern>',
-    'RegExp pattern to match journey/monitor files that are different from the default (ex: /*.journey.(ts|js)$/)'
+    'RegExp pattern to match journey files in the current working directory (default: /*.journey.(ts|js)$/)'
   );
 
   const apiDocsLink =
@@ -208,11 +212,28 @@ export function getCommonCommandOpts() {
     .env('SYNTHETICS_API_KEY')
     .makeOptionMandatory(true);
 
+  const configOpt = createOption(
+    '-c, --config <path>',
+    'path to the configuration file (default: synthetics.config.(js|ts))'
+  );
+
+  const tags = createOption(
+    '--tags <name...>',
+    'run/push tests with the tag(s) matching a pattern'
+  );
+  const match = createOption(
+    '--match <name>',
+    'run/push tests with a name or tags that matches a pattern'
+  );
+
   return {
     auth,
     authMandatory,
     params,
     playwrightOpts,
     pattern,
+    configOpt,
+    tags,
+    match,
   };
 }

package/src/push/index.ts

@@ -58,13 +58,16 @@ import {
   isLightweightMonitorSupported,
   logDiff,
 } from './utils';
+import { log } from '../core/logger';
 
 export async function push(monitors: Monitor[], options: PushOptions) {
   const duplicates = trackDuplicates(monitors);
   if (duplicates.size > 0) {
     throw error(formatDuplicateError(duplicates));
   }
-  progress(`Pushing monitors for project: ${options.id}`);
+  progress(
+    `Pushing monitors for '${options.id}' project in kibana '${options.space}' space`
+  );
 
   /**
    * Legacy API for kibana which does not support bulk operations
@@ -97,8 +100,17 @@ export async function push(monitors: Monitor[], options: PushOptions) {
   }
 
   if (removedIDs.size > 0) {
+    log(`deleting monitor ids: ${Array.from(removedIDs.keys()).join(', ')}`);
     if (updatedMonitors.size === 0 && unchangedIDs.size === 0) {
-      await promptConfirmDeleteAll(options);
+      await confirmDelete(
+        `Pushing without any monitors will delete all monitors associated with the project.\n Do you want to continue?`,
+        options.yes
+      );
+    } else {
+      await confirmDelete(
+        `Deleting ${removedIDs.size} monitors. Do you want to continue?`,
+        options.yes
+      );
     }
     const chunks = getChunks(Array.from(removedIDs), CHUNK_SIZE);
     for (const chunk of chunks) {
@@ -112,22 +124,22 @@ export async function push(monitors: Monitor[], options: PushOptions) {
   done(`Pushed: ${grey(getMonitorManagementURL(options.url))}`);
 }
 
-async function promptConfirmDeleteAll(options: PushOptions) {
-  write('');
-  const { deleteAll } = await prompt<{ deleteAll: boolean }>({
+async function confirmDelete(message: string, skip: boolean) {
+  const { deleteMonitors } = await prompt<{ deleteMonitors: boolean }>({
     type: 'confirm',
     skip() {
-      if (options.yes) {
+      write('');
+      if (skip || !process.stdout.isTTY) {
         this.initial = process.env.TEST_OVERRIDE ?? true;
         return true;
       }
       return false;
     },
-    name: 'deleteAll',
-    message: `Pushing without any monitors will delete all monitors associated with the project.\n Do you want to continue?`,
+    name: 'deleteMonitors',
+    message,
     initial: false,
   });
-  if (!deleteAll) {
+  if (!deleteMonitors) {
     throw warn('Push command Aborted');
   }
 }
@@ -160,9 +172,12 @@ export function formatDuplicateError(monitors: Set<Monitor>) {
 
 const INSTALLATION_HELP = `Run 'npx @elastic/synthetics init' to create project with default settings.`;
 
-export async function loadSettings(ignoreMissing = false) {
+export async function loadSettings(configPath, ignoreMissing = false) {
   try {
-    const config = await readConfig(process.env['NODE_ENV'] || 'development');
+    const config = await readConfig(
+      process.env['NODE_ENV'] || 'development',
+      configPath
+    );
     // Missing config file, fake throw to capture as missing file
     if (Object.keys(config).length === 0) {
       throw '';
@@ -216,9 +231,13 @@ ${reason}
 ${INSTALLATION_HELP}`);
 }
 
-async function overrideSettings(oldValue: string, newValue: string) {
+async function overrideSettings(
+  configPath,
+  oldValue: string,
+  newValue: string
+) {
   const cwd = process.cwd();
-  const configPath = await findSyntheticsConfig(cwd, cwd);
+  configPath = configPath ?? (await findSyntheticsConfig(cwd, cwd));
   if (!configPath) {
     throw warn(`Unable to find synthetics config file: ${configPath}`);
   }
@@ -256,7 +275,7 @@ export async function catchIncorrectSettings(
     }
   }
   if (override) {
-    await overrideSettings(settings.id, options.id);
+    await overrideSettings(options.config, settings.id, options.id);
   }
 }
 
@@ -279,7 +298,10 @@ export async function pushLegacy(monitors: Monitor[], options: PushOptions) {
       );
     }
   } else {
-    await promptConfirmDeleteAll(options);
+    await confirmDelete(
+      `Pushing without any monitors will delete all monitors associated with the project.\n Do you want to continue?`,
+      options.yes
+    );
   }
   await liveProgress(
     createMonitorsLegacy({ schemas, keepStale: false, options }),