@elastic/synthetics 1.0.0-beta.3 → 1.0.0-beta.30

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,16 +23,28 @@
  *
  */
 
-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';
 import { promisify } from 'util';
 import { performance } from 'perf_hooks';
-import { HooksArgs, HooksCallback } from './common_types';
+import sourceMapSupport from '@cspotcode/source-map-support';
+import {
+  HooksArgs,
+  HooksCallback,
+  NetworkConditions,
+  Location,
+  ThrottlingOptions,
+} from './common_types';
+
+const lstatAsync = promisify(fs.lstat);
+const readdirAsync = promisify(fs.readdir);
+
+export const readFileAsync = promisify(fs.readFile);
+export const writeFileAsync = promisify(fs.writeFile);
+export const mkdirAsync = promisify(fs.mkdir);
 
-const statAsync = promisify(fs.lstat);
-const readAsync = promisify(fs.readdir);
 const SEPARATOR = '\n';
 
 export function noop() {}
@@ -41,15 +53,25 @@ export function indent(lines: string, tab = '   ') {
   return lines.replace(/^/gm, tab);
 }
 
+/**
+ *  Disable unicode symbols for windows, the underlying
+ *  FS stream has a known issue in windows
+ */
+const NO_UTF8_SUPPORT = process.platform === 'win32';
 export const symbols = {
-  warning: yellow('⚠'),
+  warning: yellow(NO_UTF8_SUPPORT ? '!' : '⚠'),
   skipped: cyan('-'),
-  succeeded: green('✓'),
-  failed: red('✖'),
+  progress: cyan('>'),
+  succeeded: green(NO_UTF8_SUPPORT ? 'ok' : '✓'),
+  failed: red(NO_UTF8_SUPPORT ? 'x' : '✖'),
 };
 
+export function generateUniqueId() {
+  return `${Date.now() + Math.floor(Math.random() * 1e13)}`;
+}
+
 export function generateTempPath() {
-  return join(os.tmpdir(), `synthetics-${process.hrtime().toString()}`);
+  return join(os.tmpdir(), `synthetics-${generateUniqueId()}`);
 }
 
 /**
@@ -155,11 +177,11 @@ export async function totalist(
   pre = ''
 ) {
   dir = resolve('.', dir);
-  await readAsync(dir).then(arr => {
+  await readdirAsync(dir).then(arr => {
     return Promise.all(
       arr.map(str => {
         const abs = join(dir, str);
-        return statAsync(abs).then(stats =>
+        return lstatAsync(abs).then(stats =>
           stats.isDirectory()
             ? totalist(abs, callback, join(pre, str))
             : callback(join(pre, str), abs)
@@ -242,3 +264,77 @@ export const CACHE_PATH = join(cwd, '.synthetics', process.pid.toString());
 export function getDurationInUs(duration: number) {
   return Math.trunc(duration * 1e6);
 }
+
+export function megabitsToBytes(megabytes: number) {
+  return (megabytes * 1024 * 1024) / 8;
+}
+
+export const DEFAULT_THROTTLING_OPTIONS: ThrottlingOptions = {
+  download: 5,
+  upload: 3,
+  latency: 20,
+};
+
+/**
+ * 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 dstackTraceLimit = 10;
+
+// Uses the V8 Stacktrace API to get the function location
+// information - https://v8.dev/docs/stack-trace-api#customizing-stack-traces
+export function wrapFnWithLocation<A extends unknown[], R>(
+  func: (location: Location, ...args: A) => R
+): (...args: A) => R {
+  return (...args) => {
+    const _prepareStackTrace = Error.prepareStackTrace;
+    Error.prepareStackTrace = (_, stackFrames) => {
+      // Deafult CallSite would not map to the original transpiled source
+      // from ts-node properly, So we wrap it with the library that knows
+      // how to retrive those source-map for the transpiled code
+      const frame: NodeJS.CallSite = sourceMapSupport.wrapCallSite(
+        stackFrames[1]
+      );
+      return {
+        file: frame.getFileName(),
+        line: frame.getLineNumber(),
+        column: frame.getColumnNumber(),
+      };
+    };
+    Error.stackTraceLimit = 2;
+    const obj: { stack: Location } = {} as any;
+    Error.captureStackTrace(obj);
+    const location = obj.stack;
+    Error.stackTraceLimit = dstackTraceLimit;
+    Error.prepareStackTrace = _prepareStackTrace;
+    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

@@ -24,35 +24,24 @@
  */
 
 import { runner } from './core';
-import { RunOptions } from './core/runner';
-import { setLogger } from './core/logger';
-import sourceMapSupport from 'source-map-support';
+import { RunOptions } from './common_types';
 
 export async function run(options: RunOptions) {
-  /**
-   * Install source map support
-   */
-  sourceMapSupport.install({
-    environment: 'node',
-  });
-  /**
-   * set up logger with appropriate file descriptor
-   * to capture all the DEBUG logs when run through heartbeat
-   */
-  setLogger(options.outfd);
-
-  try {
-    return await runner.run(options);
-  } catch (e) {
-    console.error('Failed to run the test', e);
-    process.exit(1);
-  }
+  return runner.run(options);
 }
 
 /**
  * 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
@@ -70,3 +59,13 @@ export type {
  */
 export type { default as Runner } from './core/runner';
 export type { Reporter, ReporterOptions } from './reporters';
+
+export type { SyntheticsConfig } from './common_types';
+export type {
+  Action,
+  ActionInContext,
+  Signal,
+  Step,
+  Steps,
+  actionTitle,
+} from './formatter/javascript';

package/src/loader.ts

@@ -0,0 +1,162 @@
+/**
+ * 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 { stdin, cwd } from 'process';
+import { resolve } from 'path';
+import { CliArgs } from './common_types';
+import { step, journey } from './core';
+import { log } from './core/logger';
+import { expect } from './core/expect';
+import {
+  isDepInstalled,
+  isDirectory,
+  totalist,
+  findPkgJsonByTraversing,
+} from './helpers';
+
+const resolvedCwd = cwd();
+
+export async function loadTestFiles(options: CliArgs, args: string[]) {
+  /**
+   * Transform `.ts` files out of the box by invoking
+   * the `ts-node` via `transpile-only` mode that compiles
+   * TS files without doing any extensive type checks.
+   *
+   * We must register `ts-node` _before_ loading inline
+   * scripts too because otherwise we will not be able to
+   * require `.ts` configuration files.
+   */
+  /* eslint-disable-next-line @typescript-eslint/no-var-requires */
+  require('ts-node').register({
+    transpileOnly: true,
+    compilerOptions: {
+      esModuleInterop: true,
+      allowJs: true,
+      target: 'es2020',
+    },
+  });
+
+  /**
+   * Preload modules before running the tests
+   */
+  const modules = [].concat(options.require || []).filter(Boolean);
+  for (const name of modules) {
+    if (isDepInstalled(name)) {
+      require(name);
+    } else {
+      throw new Error(`cannot find module '${name}'`);
+    }
+  }
+
+  if (options.inline) {
+    const source = await readStdin();
+    loadInlineScript(source);
+    return;
+  }
+  /**
+   * Handle piped files by reading the STDIN
+   * ex: ls example/suites/*.js | npx @elastic/synthetics
+   */
+  const files =
+    args.length > 0 ? args : (await readStdin()).split('\n').filter(Boolean);
+  const suites = await prepareSuites(files, options.pattern);
+  requireSuites(suites);
+}
+
+const loadInlineScript = source => {
+  const scriptFn = new Function(
+    'step',
+    'page',
+    'context',
+    'browser',
+    'params',
+    'expect',
+    source
+  );
+  journey('inline', ({ page, context, browser, params }) => {
+    scriptFn.apply(null, [step, page, context, browser, params, expect]);
+  });
+};
+
+/**
+ * Read the input from STDIN and run it as inline journey
+ */
+async function readStdin() {
+  const chunks = [];
+  stdin.resume();
+  stdin.setEncoding('utf-8');
+  for await (const chunk of stdin) {
+    chunks.push(chunk);
+  }
+  return chunks.join();
+}
+
+function requireSuites(suites: Iterable<string>) {
+  for (const suite of suites) {
+    require(suite);
+  }
+}
+
+/**
+ * Handle both directory and files that are passed through TTY
+ * and add them to suites
+ */
+async function prepareSuites(inputs: string[], filePattern?: string) {
+  const suites = new Set<string>();
+  const addSuite = absPath => {
+    log(`Processing file: ${absPath}`);
+    suites.add(require.resolve(absPath));
+  };
+  /**
+   * Match all files inside the directory with the
+   * .journey.{mjs|cjs|js|ts) extensions
+   */
+  const pattern = filePattern
+    ? new RegExp(filePattern, 'i')
+    : /.+\.journey\.([mc]js|[jt]s?)$/;
+  /**
+   * Ignore node_modules by default when running suites
+   */
+  const ignored = /node_modules/i;
+
+  for (const input of inputs) {
+    const absPath = resolve(resolvedCwd, input);
+    /**
+     * Validate for package.json file before running
+     * the suites
+     */
+    findPkgJsonByTraversing(absPath, resolvedCwd);
+    if (isDirectory(absPath)) {
+      await totalist(absPath, (rel, abs) => {
+        if (pattern.test(rel) && !ignored.test(rel)) {
+          addSuite(abs);
+        }
+      });
+    } else {
+      addSuite(absPath);
+    }
+  }
+  return suites.values();
+}

package/src/options.ts

@@ -0,0 +1,173 @@
+/**
+ * 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 { readConfig } from './config';
+import { getNetworkConditions, DEFAULT_THROTTLING_OPTIONS } from './helpers';
+import type { CliArgs, RunOptions, ThrottlingOptions } from './common_types';
+
+/**
+ * Set debug based on DEBUG ENV and -d flags
+ * namespace - synthetics
+ */
+const namespace = 'synthetics';
+if (process.env.DEBUG && process.env.DEBUG.includes(namespace)) {
+  process.env.DEBUG = '1';
+}
+
+export function normalizeOptions(cliArgs: CliArgs): RunOptions {
+  const options: RunOptions = {
+    ...cliArgs,
+    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
+   */
+  const config =
+    cliArgs.config || !cliArgs.inline
+      ? 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 || {}));
+
+  /**
+   * 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,
+  };
+
+  /**
+   * Get the default monitor config from synthetics.config.ts file
+   */
+  const monitor = config.monitor;
+  if (cliArgs.throttling) {
+    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/browser-console.ts

@@ -23,8 +23,7 @@
  *
  */
 
-import { Page } from 'playwright-chromium';
-import { BrowserMessage } from '../common_types';
+import { BrowserMessage, Driver } from '../common_types';
 import { Step } from '../dsl';
 import { getTimestamp } from '../helpers';
 
@@ -34,6 +33,8 @@ export class BrowserConsole {
   private messages: BrowserMessage[] = [];
   _currentStep: Partial<Step> = null;
 
+  constructor(private driver: Driver) {}
+
   private consoleEventListener = msg => {
     if (!this._currentStep) {
       return;
@@ -47,20 +48,41 @@ export class BrowserConsole {
         type,
         step: { name, index },
       });
-      if (this.messages.length > defaultMessageLimit) {
-        this.messages.splice(0, 1);
-      }
+
+      this.enforceMessagesLimit();
+    }
+  };
+
+  private pageErrorEventListener = (error: Error) => {
+    if (!this._currentStep) {
+      return;
     }
+    const { name, index } = this._currentStep;
+    this.messages.push({
+      timestamp: getTimestamp(),
+      text: error.message,
+      type: 'error',
+      step: { name, index },
+      error,
+    });
+
+    this.enforceMessagesLimit();
   };
 
-  constructor(private page: Page) {}
+  private enforceMessagesLimit() {
+    if (this.messages.length > defaultMessageLimit) {
+      this.messages.splice(0, 1);
+    }
+  }
 
   start() {
-    this.page.on('console', this.consoleEventListener);
+    this.driver.page.on('console', this.consoleEventListener);
+    this.driver.page.on('pageerror', this.pageErrorEventListener);
   }
 
   stop() {
-    this.page.off('console', this.consoleEventListener);
+    this.driver.page.off('console', this.consoleEventListener);
+    this.driver.page.off('pageerror', this.pageErrorEventListener);
     return this.messages;
   }
 }