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

package/src/generator/index.ts

@@ -0,0 +1,212 @@
+/**
+ * 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 { prompt } from 'enquirer';
+import { SyntheticsLocations } from '../dsl/monitor';
+import { progress, write as stdWrite } from '../helpers';
+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) {}
+
+  async directory() {
+    if (!existsSync(this.projectDir)) {
+      await mkdir(this.projectDir);
+    }
+  }
+
+  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,
+      replaceTemplates(
+        await readFile(join(templateDir, configFile), 'utf-8'),
+        answers
+      )
+    );
+
+    // 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) {
+      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 apiKey`;
+
+    await this.createFile(
+      filename,
+      JSON.stringify(pkgJSON, null, 2) + '\n',
+      true
+    );
+  }
+
+  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(`
+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 api keys 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();
+    const answers = await this.questions();
+    await this.package();
+    await this.files(answers);
+    await this.patchPkgJSON();
+    await this.patchGitIgnore();
+    this.banner();
+  }
+}

package/src/generator/utils.ts

@@ -0,0 +1,54 @@
+/**
+ * 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}`;
+}
+
+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/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,8 @@
 
 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';
 
 /**
  * Set debug based on DEBUG ENV and -d flags
@@ -91,26 +91,83 @@ export function normalizeOptions(cliArgs: CliArgs): RunOptions {
       ? 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 || {}));
 
   /**
-   * Favor playwright options passed via cli to inline playwright options
+   * Merge playwright options from CLI and Synthetics config
+   * and prefer individual options over other option
    */
-  options.playwrightOptions = merge.all([
-    config.playwrightOptions || {},
-    cliArgs.playwrightOptions || {},
-    {
-      headless: cliArgs.headless,
-      chromiumSandbox: cliArgs.sandbox,
-      ignoreHTTPSErrors: cliArgs.ignoreHttpsErrors,
-    },
-  ]);
+  const playwrightOpts = merge(
+    config.playwrightOptions,
+    cliArgs.playwrightOptions || {}
+  );
+  options.playwrightOptions = {
+    ...playwrightOpts,
+    headless: cliArgs.headless,
+    chromiumSandbox: cliArgs.sandbox ?? playwrightOpts?.chromiumSandbox,
+    ignoreHTTPSErrors:
+      cliArgs.ignoreHttpsErrors ?? playwrightOpts?.ignoreHTTPSErrors,
+  };
 
+  /**
+   * Get the default monitor config from synthetics.config.ts file
+   */
+  const monitor = config.monitor;
   if (cliArgs.throttling) {
-    options.networkConditions = parseNetworkConditions(
-      cliArgs.throttling as string
-    );
+    const throttleConfig = merge.all([
+      DEFAULT_THROTTLING_OPTIONS,
+      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.schedule = cliArgs.schedule ?? monitor?.schedule;
+  options.locations = cliArgs.locations ?? monitor?.locations;
+
   return options;
 }
+
+/**
+ * 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);
+  }
+}