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

package/src/dsl/monitor.ts

@@ -0,0 +1,83 @@
+/**
+ * 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.
+ *
+ */
+
+import merge from 'deepmerge';
+import {
+  ThrottlingOptions,
+  Location,
+  ScreenshotOptions,
+  Params,
+  PlaywrightOptions,
+} from '../common_types';
+
+export const SyntheticsLocations = ['US East', 'EU West'] as const;
+export type SyntheticsLocationsType = typeof SyntheticsLocations[number];
+export type MonitorConfig = {
+  id?: string;
+  name?: string;
+  tags?: string[];
+  schedule?: number;
+  enabled?: boolean;
+  locations?: SyntheticsLocationsType[];
+  throttling?: ThrottlingOptions;
+  screenshot?: ScreenshotOptions;
+  params?: Params;
+  playwrightOptions?: PlaywrightOptions;
+};
+
+type MonitorFilter = {
+  match: string;
+  tags?: string[];
+};
+
+export class Monitor {
+  source?: Location;
+  filter: MonitorFilter;
+  constructor(public config: MonitorConfig = {}) {}
+  /**
+   * Treat the creation time config with `monitor.use` as source of truth by
+   * merging the values coming from CLI and Synthetics config file
+   */
+  update(globalOpts: MonitorConfig = {}) {
+    this.config = merge(globalOpts, this.config, {
+      arrayMerge(target, source) {
+        return [...new Set(source)];
+      },
+    });
+  }
+
+  setSource(source: Location) {
+    this.source = source;
+  }
+  /**
+   * If journey files are colocated within the same file during
+   * push command, when we invoke synthetics from HB we rely on
+   * this filter for running that specific journey alone instead of
+   * all journeys on the file
+   */
+  setFilter(filter: MonitorFilter) {
+    this.filter = filter;
+  }
+}

package/src/generator/index.ts

@@ -0,0 +1,159 @@
+/**
+ * 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.
+ *
+ */
+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';
+import { progress, write as stdWrite } from '../helpers';
+import { getPackageManager, runCommand } from './utils';
+
+// Templates that are required for setting up new
+// synthetics project
+const templateDir = join(__dirname, '..', '..', 'templates');
+
+export class Generator {
+  pkgManager = 'npm';
+  constructor(public projectDir: string) {}
+
+  async directory() {
+    if (!existsSync(this.projectDir)) {
+      await mkdir(this.projectDir);
+    }
+  }
+
+  async files() {
+    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')
+    );
+
+    // 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')
+    );
+
+    // Create files
+    for (const [relativePath, content] of fileMap) {
+      await this.createFile(relativePath, content);
+    }
+  }
+
+  async createFile(relativePath: string, content: string, override = false) {
+    const absolutePath = join(this.projectDir, relativePath);
+    if (override || !existsSync(absolutePath)) {
+      progress(`Writing ${relative(process.cwd(), absolutePath)}.`);
+      await mkdir(dirname(absolutePath), { recursive: true });
+      await writeFile(absolutePath, content, 'utf-8');
+    }
+  }
+
+  async package() {
+    this.pkgManager = await getPackageManager(this.projectDir);
+    const commands = new Map<string, string>();
+    commands.set(
+      `Initializing Synthetics project using ${
+        this.pkgManager == 'yarn' ? 'Yarn' : 'NPM'
+      }`,
+      this.pkgManager == 'yarn' ? 'yarn init -y' : 'npm init -y'
+    );
+
+    const pkgName = '@elastic/synthetics';
+    commands.set(
+      `Installing @elastic/synthetics library`,
+      this.pkgManager == 'yarn'
+        ? `yarn add -dev ${pkgName}`
+        : `npm i -d ${pkgName}`
+    );
+
+    // Execute commands
+    for (const [name, command] of commands) {
+      progress(`${name}...`);
+      execSync(command, {
+        stdio: 'inherit',
+        cwd: this.projectDir,
+      });
+    }
+  }
+
+  async patchPkgJSON() {
+    const filename = 'package.json';
+    const pkgJSON = JSON.parse(
+      await readFile(join(this.projectDir, filename), 'utf-8')
+    );
+
+    if (!pkgJSON.scripts) {
+      pkgJSON.scripts = {};
+    }
+    // Add test command
+    pkgJSON.scripts.test = 'npx @elastic/synthetics journeys';
+
+    // 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`;
+
+    await this.createFile(
+      filename,
+      JSON.stringify(pkgJSON, null, 2) + '\n',
+      true
+    );
+  }
+
+  banner() {
+    stdWrite(
+      bold(`
+All set, you can run below commands inside: ${this.projectDir}:
+
+  Run synthetic tests: ${cyan(runCommand(this.pkgManager, 'test'))}
+
+  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.'
+  )}
+
+Visit https://www.elastic.co/guide/en/observability/master/synthetics-journeys.html to learn more.
+    `)
+    );
+  }
+
+  async setup() {
+    await this.directory();
+    await this.package();
+    await this.files();
+    await this.patchPkgJSON();
+    this.banner();
+  }
+}

package/src/generator/utils.ts

@@ -0,0 +1,41 @@
+/**
+ * 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.
+ *
+ */
+
+import { existsSync } from 'fs';
+import { join } from 'path';
+
+export async function getPackageManager(dir: string) {
+  if (existsSync(join(dir, 'yarn.lock'))) {
+    return 'yarn';
+  }
+  return 'npm';
+}
+
+export function runCommand(pkgManager: string, command: string) {
+  if (pkgManager === 'yarn') {
+    return `yarn ${command}`;
+  }
+  return `npm run ${command}`;
+}

package/src/helpers.ts

@@ -23,7 +23,7 @@
  *
  */
 
-import { red, green, yellow, cyan } from 'kleur/colors';
+import { red, green, yellow, cyan, bold } from 'kleur/colors';
 import os from 'os';
 import { resolve, join, dirname } from 'path';
 import fs from 'fs';
@@ -35,6 +35,7 @@ import {
   HooksCallback,
   NetworkConditions,
   Location,
+  ThrottlingOptions,
 } from './common_types';
 
 const lstatAsync = promisify(fs.lstat);
@@ -60,6 +61,7 @@ const NO_UTF8_SUPPORT = process.platform === 'win32';
 export const symbols = {
   warning: yellow(NO_UTF8_SUPPORT ? '!' : '⚠'),
   skipped: cyan('-'),
+  progress: cyan('>'),
   succeeded: green(NO_UTF8_SUPPORT ? 'ok' : '✓'),
   failed: red(NO_UTF8_SUPPORT ? 'x' : '✖'),
 };
@@ -267,62 +269,27 @@ export function megabitsToBytes(megabytes: number) {
   return (megabytes * 1024 * 1024) / 8;
 }
 
-export function bytesToMegabits(bytes: number) {
-  return (bytes / 1024 / 1024) * 8;
-}
-
-export const DEFAULT_NETWORK_CONDITIONS: NetworkConditions = {
-  downloadThroughput: megabitsToBytes(5), // Devtools CDP expects format to be in bytes/second
-  uploadThroughput: megabitsToBytes(3), // Devtools CDP expects format to be in bytes/second
-  latency: 20, // milliseconds,
-  offline: false,
+export const DEFAULT_THROTTLING_OPTIONS: ThrottlingOptions = {
+  download: 5,
+  upload: 3,
+  latency: 20,
 };
 
-// Tranforms CDP dev tools format back to cli args format
-export function formatNetworkConditionsArgs(
-  networkConditions: NetworkConditions
-) {
-  const d = bytesToMegabits(networkConditions.downloadThroughput);
-  const u = bytesToMegabits(networkConditions.uploadThroughput);
-  const l = networkConditions.latency;
-  return `${d}d/${u}u/${l}l`;
-}
-
-export const DEFAULT_NETWORK_CONDITIONS_ARG = formatNetworkConditionsArgs(
-  DEFAULT_NETWORK_CONDITIONS
-);
-
-export function parseNetworkConditions(args: string): NetworkConditions {
-  const uploadToken = 'u';
-  const downloadToken = 'd';
-  const latencyToken = 'l';
-  const networkConditions = {
-    ...DEFAULT_NETWORK_CONDITIONS,
+/**
+ * Transforms the CLI throttling arguments in to format
+ * expected by Chrome devtools protocol NetworkConditions
+ */
+export function getNetworkConditions(
+  throttlingOpts: ThrottlingOptions
+): NetworkConditions {
+  return {
+    downloadThroughput: megabitsToBytes(throttlingOpts.download),
+    uploadThroughput: megabitsToBytes(throttlingOpts.upload), // Devtools CDP expects format to be in bytes/second
+    latency: throttlingOpts.latency, // milliseconds,
+    offline: false,
   };
-
-  const conditions = args.split('/');
-
-  conditions.forEach(condition => {
-    const value = condition.slice(0, condition.length - 1);
-    const token = condition.slice(-1);
-
-    switch (token) {
-      case uploadToken:
-        networkConditions.uploadThroughput = megabitsToBytes(Number(value));
-        break;
-      case downloadToken:
-        networkConditions.downloadThroughput = megabitsToBytes(Number(value));
-        break;
-      case latencyToken:
-        networkConditions.latency = Number(value);
-        break;
-    }
-  });
-
-  return networkConditions;
 }
 
-// default stack trace limit
 const dstackTraceLimit = 10;
 
 // Uses the V8 Stacktrace API to get the function location
@@ -354,3 +321,20 @@ export function wrapFnWithLocation<A extends unknown[], R>(
     return func(location, ...args);
   };
 }
+
+// Console helpers
+export function write(message: string) {
+  process.stderr.write(message + '\n');
+}
+
+export function progress(message: string) {
+  write(cyan(bold(`${symbols.progress} ${message}`)));
+}
+
+export function error(message: string) {
+  write(red(message));
+}
+
+export function done(message: string) {
+  write(bold(green(`${symbols['succeeded']} ${message}`)));
+}

package/src/index.ts

@@ -33,7 +33,15 @@ export async function run(options: RunOptions) {
 /**
  * Export all core module functions
  */
-export { beforeAll, afterAll, journey, step, before, after } from './core';
+export {
+  journey,
+  step,
+  monitor,
+  beforeAll,
+  afterAll,
+  before,
+  after,
+} from './core';
 export { expect } from './core/expect';
 /**
  * Export all the driver related types to be consumed

package/src/loader.ts

@@ -81,7 +81,7 @@ export async function loadTestFiles(options: CliArgs, args: string[]) {
    */
   const files =
     args.length > 0 ? args : (await readStdin()).split('\n').filter(Boolean);
-  const suites = await prepareSuites(files, options);
+  const suites = await prepareSuites(files, options.pattern);
   requireSuites(suites);
 }
 
@@ -123,7 +123,7 @@ function requireSuites(suites: Iterable<string>) {
  * Handle both directory and files that are passed through TTY
  * and add them to suites
  */
-async function prepareSuites(inputs: string[], cliArgs: CliArgs) {
+async function prepareSuites(inputs: string[], filePattern?: string) {
   const suites = new Set<string>();
   const addSuite = absPath => {
     log(`Processing file: ${absPath}`);
@@ -133,8 +133,8 @@ async function prepareSuites(inputs: string[], cliArgs: CliArgs) {
    * Match all files inside the directory with the
    * .journey.{mjs|cjs|js|ts) extensions
    */
-  const pattern = cliArgs.pattern
-    ? new RegExp(cliArgs.pattern, 'i')
+  const pattern = filePattern
+    ? new RegExp(filePattern, 'i')
     : /.+\.journey\.([mc]js|[jt]s?)$/;
   /**
    * Ignore node_modules by default when running suites

package/src/options.ts

@@ -25,8 +25,9 @@
 
 import merge from 'deepmerge';
 import { readConfig } from './config';
-import { parseNetworkConditions } from './helpers';
-import type { CliArgs, RunOptions } from './common_types';
+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
@@ -91,11 +92,14 @@ export function normalizeOptions(cliArgs: CliArgs): RunOptions {
       ? readConfig(options.environment, cliArgs.config)
       : {};
 
-  options.params = Object.freeze(merge(config.params, cliArgs.params || {}));
-
   /**
-   * Favor playwright options passed via cli to inline playwright options
+   * 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 || {}));
+
   options.playwrightOptions = merge.all([
     config.playwrightOptions || {},
     cliArgs.playwrightOptions || {},
@@ -106,11 +110,70 @@ export function normalizeOptions(cliArgs: CliArgs): RunOptions {
     },
   ]);
 
+  const defaults = getDefaultMonitorConfig();
   if (cliArgs.throttling) {
-    options.networkConditions = parseNetworkConditions(
-      cliArgs.throttling as string
-    );
+    const throttleConfig = merge.all([
+      defaults.throttling,
+      config.monitor?.throttling || {},
+      cliArgs.throttling as ThrottlingOptions,
+    ]);
+    options.throttling = throttleConfig;
+    options.networkConditions = getNetworkConditions(throttleConfig);
+  } else {
+    /**
+     * Do not apply throttling when `--no-throttling` flag is passed
+     */
+    options.throttling = {};
   }
 
+  options.locations =
+    cliArgs.locations ?? config.monitor?.locations ?? defaults.locations;
+
+  options.schedule =
+    cliArgs.schedule ?? config.monitor?.schedule ?? defaults.schedule;
+
   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
+ * - Accepts old format `<5d/3u/20l>`
+ * - Processess new format otherwise `{download: 5, upload: 3, latency: 20}`
+ */
+export function parseThrottling(value: string, prev?: string) {
+  const THROTTLING_REGEX = /([0-9]{1,}u)|([0-9]{1,}d)|([0-9]{1,}l)/gm;
+  if (THROTTLING_REGEX.test(value)) {
+    const throttling: ThrottlingOptions = {};
+    const conditions = value.split('/');
+
+    conditions.forEach(condition => {
+      const setting = condition.slice(0, condition.length - 1);
+      const token = condition.slice(-1);
+      switch (token) {
+        case 'd':
+          throttling.download = Number(setting);
+          break;
+        case 'u':
+          throttling.upload = Number(setting);
+          break;
+        case 'l':
+          throttling.latency = Number(setting);
+          break;
+      }
+    });
+    return throttling;
+  }
+  return JSON.parse(value || prev);
+}

package/src/plugins/performance.ts

@@ -23,7 +23,7 @@
  *
  */
 
-import { Driver } from '../common_types';
+import { Driver, PageMetrics } from '../common_types';
 
 const supportedMetrics = new Set<string>([
   'Timestamp',
@@ -41,22 +41,6 @@ const supportedMetrics = new Set<string>([
   'JSHeapTotalSize',
 ]);
 
-export interface PageMetrics {
-  Timestamp?: number;
-  Documents?: number;
-  Frames?: number;
-  JSEventListeners?: number;
-  Nodes?: number;
-  LayoutCount?: number;
-  RecalcStyleCount?: number;
-  LayoutDuration?: number;
-  RecalcStyleDuration?: number;
-  ScriptDuration?: number;
-  TaskDuration?: number;
-  JSHeapUsedSize?: number;
-  JSHeapTotalSize?: number;
-}
-
 export class PerformanceManager {
   constructor(private driver: Driver) {}
 

package/src/push/bundler.ts

@@ -0,0 +1,99 @@
+/**
+ * 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.
+ *
+ */
+
+import path from 'path';
+import { unlink, readFile } from 'fs/promises';
+import { createWriteStream } from 'fs';
+import * as esbuild from 'esbuild';
+import archiver from 'archiver';
+import { commonOptions, MultiAssetPlugin, PluginData } from './plugin';
+
+function relativeToCwd(entry: string) {
+  return path.relative(process.cwd(), entry);
+}
+
+export class Bundler {
+  moduleMap = new Map<string, string>();
+  constructor() {}
+
+  async prepare(absPath: string) {
+    const addToMap = (data: PluginData) => {
+      this.moduleMap.set(data.path, data.contents);
+    };
+
+    const options: esbuild.BuildOptions = {
+      ...commonOptions(),
+      ...{
+        entryPoints: {
+          [absPath]: absPath,
+        },
+        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);
+    }
+  }
+
+  async zip(outputPath: string) {
+    return new Promise((fulfill, reject) => {
+      const output = createWriteStream(outputPath);
+      const archive = archiver('zip', {
+        zlib: { level: 9 },
+      });
+      archive.on('error', err => reject(err));
+      output.on('close', fulfill);
+      archive.pipe(output);
+      for (const [path, content] of this.moduleMap.entries()) {
+        const relativePath = relativeToCwd(path);
+        archive.append(content, { name: relativePath });
+      }
+      archive.finalize();
+    });
+  }
+
+  async build(entry: string, output: string) {
+    await this.prepare(entry);
+    await this.zip(output);
+    const data = await this.encode(output);
+    await this.cleanup(output);
+    return data;
+  }
+
+  async encode(outputPath: string) {
+    return await readFile(outputPath, 'base64');
+  }
+
+  async cleanup(outputPath: string) {
+    this.moduleMap = new Map<string, string>();
+    await unlink(outputPath);
+  }
+}