@elastic/synthetics 1.0.0-beta.26 → 1.0.0-beta.29

package/src/cli.ts

@@ -26,6 +26,7 @@
  */
 
 import { program, Option } from 'commander';
+import { cwd } from 'process';
 import { CliArgs, PushOptions } from './common_types';
 import { reporters } from './reporters';
 import { normalizeOptions, parseThrottling } from './options';
@@ -65,7 +66,7 @@ program
   .option('--inline', 'Run inline journeys from heartbeat')
   .option('-r, --require <modules...>', 'module(s) to preload')
   .option('--no-headless', 'run browser in headful mode')
-  .option('--sandbox', 'enable chromium sandboxing', false)
+  .option('--sandbox', 'enable chromium sandboxing')
   .option('--rich-events', 'Mimics a heartbeat run')
   .option(
     '--capability <features...>',
@@ -81,12 +82,12 @@ program
     "don't actually execute anything, report only registered journeys"
   )
   .option(
-    '--match <name>',
-    'run only journeys with a name or tags that matches the glob'
+    '--tags <name...>',
+    'run only journeys with a tag that matches the glob'
   )
   .option(
-    '--tags <name...>',
-    'run only journeys with the given tag(s), or globs'
+    '--match <name>',
+    'run only journeys with a name or tag that matches the glob'
   )
   .option(
     '--outfd <fd>',
@@ -146,9 +147,21 @@ program
 
 // Push command
 program
-  .command('push [files...]')
+  .command('push')
   .description(
-    'Push monitors to create new montors with Kibana monitor management UI'
+    'Push journeys in the current directory to create monitors within the Kibana monitor management UI'
+  )
+  .option(
+    '--pattern <pattern>',
+    'RegExp file patterns to push inside current directory'
+  )
+  .option(
+    '--tags <name...>',
+    'push only journeys with a tag that matches the glob'
+  )
+  .option(
+    '--match <name>',
+    'push only journeys with a name or tag that matches the glob'
   )
   .option(
     '--schedule <time-in-minutes>',
@@ -158,33 +171,40 @@ program
   .addOption(
     new Option(
       '--locations <locations...>',
-      'The default list of locations from which your monitors will run.'
+      'default list of locations from which your monitors will run.'
     ).choices(SyntheticsLocations)
   )
   .requiredOption(
-    '--project <id/name>',
-    'project/repository that will be used for grouping the monitors.'
+    '--project <project-id>',
+    'id that will be used for logically grouping monitors'
   )
   .requiredOption('--url <url>', 'kibana URL to upload the monitors')
   .requiredOption(
     '--auth <auth>',
-    'user authentication (in user:password format) or API key that will be used to communicate with Kibana.'
+    'API key used for Kibana authentication(https://www.elastic.co/guide/en/kibana/master/api-keys.html).'
   )
   .option(
     '--space <space>',
     'the target Kibana spaces for the pushed monitors — spaces help you organise pushed monitors.',
     'default'
   )
-  .option('--delete', 'automatically delete the stale monitors.')
-  .action(async (files, cmdOpts: PushOptions) => {
+  .action(async (cmdOpts: PushOptions) => {
     try {
-      const cliArgs = { inline: false };
-      await loadTestFiles(cliArgs, files);
+      await loadTestFiles({ inline: false }, [cwd()]);
       const options = normalizeOptions({ ...program.opts(), ...cmdOpts });
+      if (!options.schedule) {
+        throw error(`Set default schedule in minutes for all monitors via '--schedule <time-in-minutes>' OR
+  configure via Synthetics config file under 'monitors.schedule' field.`);
+      }
+
+      if (!options.locations) {
+        throw error(`Set default location for all monitors via CLI as '--locations <locations...>' OR
+  configure via Synthetics config file under 'monitors.locations' field.`);
+      }
       const monitors = runner.buildMonitors(options);
       await push(monitors, cmdOpts);
     } catch (e) {
-      console.error(e);
+      e && console.error(e);
       process.exit(1);
     }
   });
@@ -198,7 +218,7 @@ program
       const generator = await new Generator(resolve(process.cwd(), dir));
       await generator.setup();
     } catch (e) {
-      error(e);
+      e && error(e);
       process.exit(1);
     }
   });

package/src/common_types.ts

@@ -243,7 +243,6 @@ export type PushOptions = {
   url: string;
   project: string;
   space: string;
-  delete: boolean;
   schedule?: MonitorConfig['schedule'];
   locations?: MonitorConfig['locations'];
 };

package/src/core/gatherer.ts

@@ -65,12 +65,12 @@ export class Gatherer {
   }
 
   static async getUserAgent(userAgent?: string) {
-    const syntheticsIdentifier = ' Elastic/Synthetics';
     if (!userAgent) {
       const session = await Gatherer.browser.newBrowserCDPSession();
       ({ userAgent } = await session.send('Browser.getVersion'));
+      return userAgent + ' Elastic/Synthetics';
     }
-    return userAgent + syntheticsIdentifier;
+    return userAgent;
   }
 
   static setNetworkConditions(

package/src/core/runner.ts

@@ -97,11 +97,11 @@ export default class Runner {
   }
 
   async captureScreenshot(page: Driver['page'], step: Step) {
-    await page.waitForLoadState('load');
     const buffer = await page
       .screenshot({
         type: 'jpeg',
         quality: 80,
+        timeout: 5000,
       })
       .catch(() => {});
     /**
@@ -397,9 +397,16 @@ export default class Runner {
       playwrightOptions: options.playwrightOptions,
     });
 
+    const { match, tags } = options;
+
     const monitors: Monitor[] = [];
     for (const journey of this.journeys) {
+      if (!journey.isMatch(match, tags)) {
+        continue;
+      }
+
       this.#currentJourney = journey;
+
       /**
        * Execute dummy callback to get all monitor specific
        * configurations for the current journey

package/src/dsl/locations.ts

@@ -0,0 +1,38 @@
+/**
+ * MIT License
+ *
+ * Copyright (c) 2020-present, Elastic NV
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ */
+
+// DO NOT EDIT - UPDATE WITH `npm run build:locations`
+export const LocationsMap = {
+  japan: 'asia-northeast1-a',
+  india: 'asia-south1-a',
+  singapore: 'asia-southeast1-a',
+  australia_east: 'australia-southeast1-a',
+  united_kingdom: 'europe-west2-a',
+  germany: 'europe-west3-a',
+  canada_east: 'northamerica-northeast1-a',
+  brazil: 'southamerica-east1-a',
+  us_east: 'us-east4-a',
+  us_west: 'us-west1-a',
+};

package/src/dsl/monitor.ts

@@ -31,9 +31,13 @@ import {
   Params,
   PlaywrightOptions,
 } from '../common_types';
+import { LocationsMap } from './locations';
+
+export type SyntheticsLocationsType = keyof typeof LocationsMap;
+export const SyntheticsLocations = Object.keys(
+  LocationsMap
+) as SyntheticsLocationsType[];
 
-export const SyntheticsLocations = ['US East', 'EU West'] as const;
-export type SyntheticsLocationsType = typeof SyntheticsLocations[number];
 export type MonitorConfig = {
   id?: string;
   name?: string;

package/src/generator/index.ts

@@ -27,13 +27,29 @@ 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';
+import { prompt } from 'enquirer';
+import { SyntheticsLocations } from '../dsl/monitor';
 import { progress, write as stdWrite } from '../helpers';
-import { getPackageManager, runCommand } from './utils';
+import { getPackageManager, replaceTemplates, runCommand } from './utils';
 
 // Templates that are required for setting up new
 // synthetics project
 const templateDir = join(__dirname, '..', '..', 'templates');
 
+type PromptOptions = {
+  locations: string;
+  schedule: number;
+};
+
+// exported for testing
+export const regularFiles = [
+  '.github/workflows/run-synthetics.yml',
+  'README.md',
+  'journeys/example.journey.ts',
+  'journeys/advanced-example.journey.ts',
+  'journeys/advanced-example-helpers.ts',
+];
+
 export class Generator {
   pkgManager = 'npm';
   constructor(public projectDir: string) {}
@@ -44,26 +60,47 @@ export class Generator {
     }
   }
 
-  async files() {
+  async questions() {
+    if (process.env.TEST_QUESTIONS) {
+      return JSON.parse(process.env.TEST_QUESTIONS);
+    }
+    const question = [
+      {
+        type: 'select',
+        name: 'locations',
+        message: 'Select the default location where you want to run monitors.',
+        choices: SyntheticsLocations,
+      },
+      {
+        type: 'numeral',
+        name: 'schedule',
+        message: 'Set default schedule in minutes for all monitors',
+        initial: 10,
+      },
+    ];
+    return await prompt<PromptOptions>(question);
+  }
+
+  async files(answers: PromptOptions) {
     const fileMap = new Map<string, string>();
     // Setup Synthetics config file
     const configFile = 'synthetics.config.ts';
     fileMap.set(
       configFile,
-      await readFile(join(templateDir, configFile), 'utf-8')
+      replaceTemplates(
+        await readFile(join(templateDir, configFile), 'utf-8'),
+        answers
+      )
     );
 
-    // Setup example journey file
-    const journeyFile = 'journeys/example.journey.ts';
-    fileMap.set(
-      journeyFile,
-      await readFile(join(templateDir, journeyFile), 'utf-8')
-    );
-    // Setup gitignore
-    fileMap.set(
-      '.gitignore',
-      await readFile(join(templateDir, '.gitignore'), 'utf-8')
-    );
+    // Setup non-templated files
+    Promise.all(
+      regularFiles.map(async fn => {
+        fileMap.set(fn, await readFile(join(templateDir, fn), 'utf-8'));
+      })
+    ).catch(e => {
+      throw e;
+    });
 
     // Create files
     for (const [relativePath, content] of fileMap) {
@@ -122,7 +159,7 @@ export class Generator {
 
     // Add push command
     const project = basename(this.projectDir);
-    pkgJSON.scripts.push = `npx @elastic/synthetics push journeys --project ${project} --url http://localhost:5601 --auth basic-auth`;
+    pkgJSON.scripts.push = `npx @elastic/synthetics push journeys --project ${project} --url http://localhost:5601 --auth apiKey`;
 
     await this.createFile(
       filename,
@@ -131,6 +168,20 @@ export class Generator {
     );
   }
 
+  async patchGitIgnore() {
+    const gitIgnorePath = join(this.projectDir, '.gitignore');
+    let gitIgnore = '';
+    if (existsSync(gitIgnorePath)) {
+      const contents = await readFile(gitIgnorePath, 'utf-8');
+      gitIgnore += contents.trimEnd() + '\n';
+    }
+    if (!gitIgnore.includes('node_modules')) {
+      gitIgnore += 'node_modules/\n';
+    }
+    gitIgnore += '.synthetics/\n';
+    await writeFile(gitIgnorePath, gitIgnore, 'utf-8');
+  }
+
   banner() {
     stdWrite(
       bold(`
@@ -141,7 +192,7 @@ All set, you can run below commands inside: ${this.projectDir}:
   Push monitors to Kibana: ${cyan(runCommand(this.pkgManager, 'push'))}
 
   ${yellow(
-    'Make sure to update the Kibana url and authentication info before pushing monitors to Kibana.'
+    'Make sure to update the Kibana url and api keys before pushing monitors to Kibana.'
   )}
 
 Visit https://www.elastic.co/guide/en/observability/master/synthetics-journeys.html to learn more.
@@ -151,9 +202,11 @@ Visit https://www.elastic.co/guide/en/observability/master/synthetics-journeys.h
 
   async setup() {
     await this.directory();
+    const answers = await this.questions();
     await this.package();
-    await this.files();
+    await this.files(answers);
     await this.patchPkgJSON();
+    await this.patchGitIgnore();
     this.banner();
   }
 }

package/src/generator/utils.ts

@@ -39,3 +39,16 @@ export function runCommand(pkgManager: string, command: string) {
   }
   return `npm run ${command}`;
 }
+
+export function replaceTemplates(input: string, literals: Record<string, any>) {
+  for (const key in literals) {
+    const finalValue = literals[key];
+    input = input.replace(new RegExp(`'{{` + key + `}}'`, 'g'), () => {
+      if (typeof finalValue == 'number') {
+        return Number(finalValue);
+      }
+      return finalValue;
+    });
+  }
+  return input;
+}

package/src/options.ts

@@ -27,7 +27,6 @@ import merge from 'deepmerge';
 import { readConfig } from './config';
 import { getNetworkConditions, DEFAULT_THROTTLING_OPTIONS } from './helpers';
 import type { CliArgs, RunOptions, ThrottlingOptions } from './common_types';
-import { MonitorConfig } from './dsl/monitor';
 
 /**
  * Set debug based on DEBUG ENV and -d flags
@@ -100,21 +99,30 @@ export function normalizeOptions(cliArgs: CliArgs): RunOptions {
    */
   options.params = Object.freeze(merge(config.params, cliArgs.params || {}));
 
-  options.playwrightOptions = merge.all([
-    config.playwrightOptions || {},
-    cliArgs.playwrightOptions || {},
-    {
-      headless: cliArgs.headless,
-      chromiumSandbox: cliArgs.sandbox,
-      ignoreHTTPSErrors: cliArgs.ignoreHttpsErrors,
-    },
-  ]);
+  /**
+   * Merge playwright options from CLI and Synthetics config
+   * and prefer individual options over other option
+   */
+  const playwrightOpts = merge(
+    config.playwrightOptions,
+    cliArgs.playwrightOptions || {}
+  );
+  options.playwrightOptions = {
+    ...playwrightOpts,
+    headless: cliArgs.headless,
+    chromiumSandbox: cliArgs.sandbox ?? playwrightOpts?.chromiumSandbox,
+    ignoreHTTPSErrors:
+      cliArgs.ignoreHttpsErrors ?? playwrightOpts?.ignoreHTTPSErrors,
+  };
 
-  const defaults = getDefaultMonitorConfig();
+  /**
+   * Get the default monitor config from synthetics.config.ts file
+   */
+  const monitor = config.monitor;
   if (cliArgs.throttling) {
     const throttleConfig = merge.all([
-      defaults.throttling,
-      config.monitor?.throttling || {},
+      DEFAULT_THROTTLING_OPTIONS,
+      monitor?.throttling || {},
       cliArgs.throttling as ThrottlingOptions,
     ]);
     options.throttling = throttleConfig;
@@ -126,26 +134,12 @@ export function normalizeOptions(cliArgs: CliArgs): RunOptions {
     options.throttling = {};
   }
 
-  options.locations =
-    cliArgs.locations ?? config.monitor?.locations ?? defaults.locations;
-
-  options.schedule =
-    cliArgs.schedule ?? config.monitor?.schedule ?? defaults.schedule;
+  options.schedule = cliArgs.schedule ?? monitor?.schedule;
+  options.locations = cliArgs.locations ?? monitor?.locations;
 
   return options;
 }
 
-/**
- * Get the default monitor configuration for all journeys
- */
-export function getDefaultMonitorConfig(): MonitorConfig {
-  return {
-    throttling: DEFAULT_THROTTLING_OPTIONS,
-    locations: ['US East'],
-    schedule: 10,
-  };
-}
-
 /**
  * Parses the throttling CLI settings and also
  * adapts to the format to keep the backwards compatability

package/src/push/bundler.ts

@@ -52,15 +52,11 @@ export class Bundler {
         plugins: [MultiAssetPlugin(addToMap)],
       },
     };
-    try {
-      const result = await esbuild.build(options);
-      if (result.errors.length > 0) {
-        throw result.errors;
-      }
-      this.moduleMap.set(absPath, result.outputFiles[0].text);
-    } catch (e) {
-      console.error(e);
+    const result = await esbuild.build(options);
+    if (result.errors.length > 0) {
+      throw result.errors;
     }
+    this.moduleMap.set(absPath, result.outputFiles[0].text);
   }
 
   async zip(outputPath: string) {

package/src/push/index.ts

@@ -28,13 +28,12 @@ import {
   ok,
   formatAPIError,
   formatFailedMonitors,
-  formatStaleMonitors,
   formatNotFoundError,
 } from './request';
 import { Monitor } from '../dsl/monitor';
 import { PushOptions } from '../common_types';
 import { buildMonitorSchema } from './monitor';
-import { progress, error, done, write } from '../helpers';
+import { progress, error, done } from '../helpers';
 
 export async function push(monitors: Monitor[], options: PushOptions) {
   progress(`preparing all monitors`);
@@ -49,13 +48,10 @@ export async function push(monitors: Monitor[], options: PushOptions) {
       const { error, message } = await body.json();
       throw formatAPIError(statusCode, error, message);
     }
-    const { staleMonitors, failedMonitors } = await body.json();
+    const { failedMonitors } = await body.json();
     if (failedMonitors.length > 0) {
       throw formatFailedMonitors(failedMonitors);
     }
-    if (staleMonitors.length > 0) {
-      write(formatStaleMonitors());
-    }
     done('Pushed');
   } catch (e) {
     error(e);

package/src/push/monitor.ts

@@ -27,11 +27,8 @@ import { mkdir } from 'fs/promises';
 import { join } from 'path';
 import { Bundler } from './bundler';
 import { CACHE_PATH } from '../helpers';
-import {
-  Monitor,
-  MonitorConfig,
-  SyntheticsLocationsType,
-} from '../dsl/monitor';
+import { LocationsMap } from '../dsl/locations';
+import { Monitor, MonitorConfig } from '../dsl/monitor';
 
 export type MonitorSchema = Omit<MonitorConfig, 'locations'> & {
   content: string;
@@ -39,12 +36,6 @@ export type MonitorSchema = Omit<MonitorConfig, 'locations'> & {
   filter: Monitor['filter'];
 };
 
-// Internal representation of Locations that would be used when
-// talking to the Kibana API
-const LocationsMap: Record<SyntheticsLocationsType, string> = {
-  'US East': 'us-east4-a',
-  'EU West': 'europe-west2-a',
-};
 function translateLocation(locations: MonitorConfig['locations']) {
   return locations.map(loc => LocationsMap[loc]).filter(Boolean);
 }

package/src/push/plugin.ts

@@ -33,6 +33,7 @@ export function commonOptions(): esbuild.BuildOptions {
     external: ['node_modules', '@elastic/synthetics'],
     minify: false,
     platform: 'node',
+    logLevel: 'silent',
     format: 'esm',
     write: false,
     outExtension: {

package/src/push/request.ts

@@ -23,7 +23,7 @@
  *
  */
 
-import { bold, gray, yellow } from 'kleur/colors';
+import { bold } from 'kleur/colors';
 import { request } from 'undici';
 import { PushOptions } from '../common_types';
 import { indent, symbols } from '../helpers';
@@ -38,16 +38,11 @@ export type APISchema = {
   monitors: MonitorSchema[];
 };
 
-function encodeAuth(auth: string) {
-  if (auth.includes(':')) {
-    return Buffer.from(auth).toString('base64');
-  }
-  return auth;
-}
-
 function getAPIUrl(options: PushOptions) {
+  // remove trialing / as well
   return (
-    options.url + `/s/${options.space}/api/synthetics/service/project/monitors`
+    options.url.replace(/\/+$/, '') +
+    `/s/${options.space}/api/synthetics/service/project/monitors`
   );
 }
 
@@ -61,7 +56,7 @@ export async function createMonitors(
 ) {
   const schema: APISchema = {
     project: options.project,
-    keep_stale: !options.delete,
+    keep_stale: false,
     monitors,
   };
 
@@ -69,7 +64,7 @@ export async function createMonitors(
     method: 'PUT',
     body: JSON.stringify(schema),
     headers: {
-      authorization: `Basic ${encodeAuth(options.auth)}`,
+      authorization: `ApiKey ${options.auth}`,
       'content-type': 'application/json',
       'user-agent': `Elastic/Synthetics ${version}`,
       'kbn-xsrf': 'true',
@@ -114,10 +109,3 @@ export function formatFailedMonitors(errors: APIMonitorError[]) {
   }
   return outer;
 }
-
-export function formatStaleMonitors() {
-  let outer = bold(yellow(`${symbols['warning']} Found stale monitors\n`));
-  const inner = gray(`Pass --delete to remove all the stale monitors.`);
-  outer += indent(inner, '   ');
-  return outer;
-}

package/templates/.github/workflows/run-synthetics.yml

@@ -0,0 +1,26 @@
+name: Elastic Synthetics Tests
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+  schedule:
+    - cron: '* 0 * * *'
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2
+        with:
+          node-version: 16
+      - run: npm install
+      - run: "SYNTHETICS_JUNIT_FILE='junit-synthetics.xml' npx @elastic/synthetics . --reporter=junit"
+        continue-on-error: true
+      - name: Publish Unit Test Results
+        uses: EnricoMi/publish-unit-test-result-action@v1.19
+        if: always()
+        with:
+          files: '**/junit-*.xml'
+          fail_on: 'test failures'
+          check_name: Elastic Synthetics Tests

package/templates/README.md

@@ -0,0 +1,21 @@
+## Get started with Elastic Synthetics!
+
+Browse the directory structure here to see an example skeleton of an [Elastic Synthetics](https://www.elastic.co/observability/synthetic-monitoring) project.
+Make sure to [read the docs](https://www.elastic.co/guide/en/observability/current/monitor-uptime-synthetics.html) as well if you're unfamiliar with Elastic Synthetics.
+
+This directory was created with the command `npx @elastic/synthetics <target-directory>`, with `<target-directory>` being the name of the directory you'd like it to make.
+You can always use this command to scafold new Synthetics projects.
+
+Key places to look:
+
+- The `synthetics.config.ts` file contains configuration for your project.
+- The `journeys` directory contains both basic and more advanced examples of using synthetics. It tests a publicly hosted [Todos List](https://elastic.github.io/synthetics-demo/).
+- The `.github` directory contains an example github action, demonstrating the use of a CI service for automatically running tests on merges and PR creation.
+
+To run the tests locally, use the following command:
+
+```bash
+npm run test
+```
+
+Curious to learn more? [Read the docs](https://www.elastic.co/guide/en/observability/current/monitor-uptime-synthetics.html) to learn about pushing configurations to an Elastic cloud stack and more.