@elastic/synthetics 1.0.0-beta.8 → 1.0.0

package/src/generator/index.ts

@@ -0,0 +1,308 @@
+/**
+ * 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';
+// @ts-ignore-next-line: has no exported member 'Input'
+import { prompt, Input } from 'enquirer';
+import {
+  getMonitorManagementURL,
+  progress,
+  write as stdWrite,
+} from '../helpers';
+import {
+  getPackageManager,
+  replaceTemplates,
+  runCommand,
+  cloudIDToKibanaURL,
+} from './utils';
+import { formatLocations, getLocations, groupLocations } from '../locations';
+import { ALLOWED_SCHEDULES } from '../dsl/monitor';
+import type { ProjectSettings } from '../common_types';
+
+// Templates that are required for setting up new synthetics project
+const templateDir = join(__dirname, '..', '..', 'templates');
+
+type PromptOptions = ProjectSettings & {
+  locations: Array<string>;
+  privateLocations: Array<string>;
+  schedule: number;
+};
+
+// exported for testing
+export const REGULAR_FILES_PATH = [
+  'journeys/example.journey.ts',
+  'journeys/advanced-example-helpers.ts',
+  'journeys/advanced-example.journey.ts',
+  'lightweight/heartbeat.yml',
+  '.github/workflows/run-synthetics.yml',
+  'README.md',
+];
+export const CONFIG_PATH = 'synthetics.config.ts';
+
+export class Generator {
+  pkgManager = 'npm';
+  constructor(public projectDir: string) {}
+
+  async directory() {
+    progress(
+      `Initializing Synthetics project in '${
+        relative(process.cwd(), this.projectDir) || '.'
+      }'`
+    );
+    if (!existsSync(this.projectDir)) {
+      await mkdir(this.projectDir);
+    }
+  }
+
+  async questions() {
+    if (process.env.TEST_QUESTIONS) {
+      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',
+      required: true,
+      result(value) {
+        return onCloud ? cloudIDToKibanaURL(value) : value;
+      },
+    }).run();
+
+    const auth = await new Input({
+      name: 'auth',
+      header: yellow(
+        `Generate API key from Kibana ${getMonitorManagementURL(url)}`
+      ),
+      required: true,
+      message: 'What is your API key',
+    }).run();
+
+    const allLocations = await getLocations({ url, auth });
+    const locChoices = formatLocations(allLocations);
+    if (locChoices.length === 0) {
+      throw 'Follow the docs to set up your first private locations - https://www.elastic.co/guide/en/observability/current/uptime-set-up-choose-agent.html#private-locations';
+    }
+
+    const monitorQues = [
+      {
+        type: 'select',
+        name: 'locations',
+        hint: '(Use <space> to select, <return> to submit)',
+        message: 'Select the locations where you want to run monitors',
+        choices: locChoices,
+        multiple: true,
+        validate(value) {
+          return value.length === 0 ? `Select at least one option.` : true;
+        },
+      },
+      {
+        type: 'select',
+        name: 'schedule',
+        message: 'Set default schedule in minutes for all monitors',
+        initial: 3, // Index of the third array item which is 10 minutes
+        choices: ALLOWED_SCHEDULES.map(String),
+        required: true,
+        result(value) {
+          return Number(value) as any;
+        },
+      },
+      {
+        type: 'input',
+        name: 'id',
+        message: 'Choose project id to logically group monitors',
+        initial: basename(this.projectDir),
+      },
+      {
+        type: 'input',
+        name: 'space',
+        message: 'Choose the target Kibana space',
+        initial: 'default',
+      },
+    ];
+
+    // Split and group private and public locations from the answered list.
+    const answers = await prompt<PromptOptions>(monitorQues);
+    const { locations, privateLocations } = groupLocations(answers.locations);
+    return { ...answers, url, locations, privateLocations };
+  }
+
+  async files(answers: PromptOptions) {
+    const fileMap = new Map<string, string>();
+
+    // Setup Synthetics config file
+    fileMap.set(
+      CONFIG_PATH,
+      replaceTemplates(
+        await readFile(join(templateDir, CONFIG_PATH), 'utf-8'),
+        answers
+      )
+    );
+
+    // Setup non-templated files
+    Promise.all(
+      REGULAR_FILES_PATH.map(async file => {
+        fileMap.set(file, await readFile(join(templateDir, file), '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)) {
+      const { override } = await prompt<{ override: boolean }>({
+        type: 'confirm',
+        name: 'override',
+        message: `File ${relativePath} already exists. Override it?`,
+        initial: false,
+      });
+      if (!override) return;
+    }
+
+    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(
+      `Setting up 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} --silent`
+        : `npm i -d ${pkgName} --quiet`
+    );
+
+    // 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
+    if (!pkgJSON.scripts.test) {
+      pkgJSON.scripts.test = 'npx @elastic/synthetics journeys';
+    }
+    // Add push command
+    if (!pkgJSON.scripts.push) {
+      pkgJSON.scripts.push = 'npx @elastic/synthetics push';
+    }
+
+    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';
+    }
+    if (!gitIgnore.includes('.synthetics')) {
+      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(
+    'SYNTHETICS_API_KEY=<value> ' + runCommand(this.pkgManager, 'push')
+  )}
+
+  ${yellow(
+    'Make sure to configure the SYNTHETICS_API_KEY before pushing monitors to Kibana.'
+  )}
+
+Visit https://www.elastic.co/guide/en/observability/current/synthetic-run-tests.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,84 @@
+/**
+ * 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, values: Record<string, any>) {
+  for (const key in values) {
+    const finalValue = values[key];
+    input = input.replace(new RegExp(`'{{` + key + `}}'`, 'g'), () => {
+      if (Array.isArray(finalValue)) {
+        return String(finalValue)
+          .split(',')
+          .filter(Boolean)
+          .map(f => `'${f}'`);
+      }
+      if (typeof finalValue == 'number') {
+        return Number(finalValue);
+      }
+      if (typeof finalValue == 'string') {
+        return `'${finalValue}'`;
+      }
+      return finalValue;
+    });
+  }
+  return input;
+}
+
+export function cloudIDToKibanaURL(id: string) {
+  const ID_SEPARATOR = ':';
+  const VALUE_SEPARATOR = '$';
+  // Ignore values before the separator
+  const index = id.lastIndexOf(ID_SEPARATOR);
+  if (index >= 0) {
+    id = id.substring(index + 1);
+  }
+
+  // Decode the base64 string
+  const decoded = Buffer.from(id, 'base64').toString();
+  const words = decoded.split(VALUE_SEPARATOR);
+
+  // construct the kibana and ES urls from decoded value
+  const [host, port = '443'] = words[0].split(ID_SEPARATOR);
+  const [kibanaId, kibanaPort = port] = words[2].split(ID_SEPARATOR);
+  const kibanaURL = `https://${kibanaId}.${host}:${kibanaPort}`;
+
+  return kibanaURL;
+}

package/src/helpers.ts

@@ -23,21 +23,21 @@
  *
  */
 
-import { red, green, yellow, cyan } from 'kleur/colors';
+import { red, green, yellow, cyan, bold, grey } from 'kleur/colors';
 import os from 'os';
 import { resolve, join, dirname } from 'path';
 import fs from 'fs';
-import { promisify } from 'util';
+import { lstat, readdir } from 'fs/promises';
 import { performance } from 'perf_hooks';
-import { HooksArgs, HooksCallback } 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 rmdirAsync = promisify(fs.rmdir);
-export const mkdirAsync = promisify(fs.mkdir);
+import sourceMapSupport from 'source-map-support';
+import {
+  HooksArgs,
+  HooksCallback,
+  NetworkConditions,
+  Location,
+  ThrottlingOptions,
+} from './common_types';
+import micromatch from 'micromatch';
 
 const SEPARATOR = '\n';
 
@@ -55,6 +55,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' : '✖'),
 };
@@ -170,11 +171,11 @@ export async function totalist(
   pre = ''
 ) {
   dir = resolve('.', dir);
-  await readdirAsync(dir).then(arr => {
+  await readdir(dir).then(arr => {
     return Promise.all(
       arr.map(str => {
         const abs = join(dir, str);
-        return lstatAsync(abs).then(stats =>
+        return lstat(abs).then(stats =>
           stats.isDirectory()
             ? totalist(abs, callback, join(pre, str))
             : callback(join(pre, str), abs)
@@ -233,10 +234,21 @@ export function rewriteErrorStack(stack: string, indexes: [number, number]) {
   return stack;
 }
 
-export function formatError(error: Error) {
-  if (!(error instanceof Error)) {
+// formatError prefers receiving proper Errors, but since at runtime
+// non Error exceptions can be thrown, it tolerates though. The
+// redundant type Error | any expresses that.
+export function formatError(error: Error | any) {
+  if (error === undefined || error === null) {
     return;
   }
+
+  if (!(error instanceof Error)) {
+    return {
+      message: `Error "${error}" received, with type "${typeof error}". (Do not throw exceptions without using \`new Error("my message")\`)`,
+      name: '',
+      stack: '',
+    };
+  }
   const { name, message, stack } = error;
   const indexes = findPWLogsIndexes(message);
   return {
@@ -247,13 +259,167 @@ export function formatError(error: Error) {
 }
 
 const cwd = process.cwd();
+/**
+ * All the settings that are related to the Synthetics is stored
+ * under this directory
+ * Examples: Screenshots, Project setup
+ */
+export const SYNTHETICS_PATH = join(cwd, '.synthetics');
 /**
  * Synthetics cache path that is based on the process id to make sure
  * each process does not modify the caching layer used by other process
  * once we move to executing journeys in parallel
  */
-export const CACHE_PATH = join(cwd, '.synthetics', process.pid.toString());
+export const CACHE_PATH = join(SYNTHETICS_PATH, 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,
+  };
+}
+
+export const THROTTLING_WARNING_MSG = `Throttling may not be active when the tests run - see
+https://github.com/elastic/synthetics/blob/main/docs/throttling.md for more details`;
+
+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
+      // correctly, So we use source-map-support to map the CallSite to the
+      // original source from our cached source map
+      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);
+  };
+}
+
+// Safely parse ND JSON (Newline delimitted JSON) chunks
+export function safeNDJSONParse(data: string | string[]) {
+  // data may not be at proper newline boundaries, so we make sure everything is split
+  // on proper newlines
+  const chunks = Array.isArray(data) ? data : [data];
+  const lines = chunks.join('\n').split(/\r?\n/);
+  return lines
+    .filter(l => l.match(/\S/)) // remove blank lines
+    .map(line => {
+      try {
+        return JSON.parse(line);
+      } catch (e) {
+        throw `Error ${e} could not parse data '${line}'`;
+      }
+    });
+}
+
+// Console helpers
+export function write(message: string, live?: boolean) {
+  process.stderr.write(message + (live ? '\r' : '\n'));
+}
+
+export function progress(message: string) {
+  write(cyan(bold(`${symbols.progress} ${message}`)));
+}
+
+export async function liveProgress(promise: Promise<any>, message: string) {
+  const start = now();
+  const interval = setInterval(() => {
+    apiProgress(`${message} (${Math.trunc(now() - start)}ms)`, true);
+  }, 500);
+  promise.finally(() => clearInterval(interval));
+  const result = await promise;
+  apiProgress(`${message} (${Math.trunc(now() - start)}ms)`);
+  return result;
+}
+
+export function apiProgress(message: string, live = false) {
+  write(grey(`> ${message}`), live);
+}
+
+export function error(message: string) {
+  write(red(message));
+}
+
+export function done(message: string) {
+  write(bold(green(`${symbols['succeeded']} ${message}`)));
+}
+
+export function warn(message: string) {
+  write(bold(yellow(`${symbols['warning']} ${message}`)));
+}
+
+export function removeTrailingSlash(url: string) {
+  return url.replace(/\/+$/, '');
+}
+
+export function getMonitorManagementURL(url) {
+  return removeTrailingSlash(url) + '/app/uptime/manage-monitors/all';
+}
+
+/**
+ * Matches tests based on the provided args. Proitize tags over match
+ * - tags pattern that matches only tags
+ * - match pattern that matches both name and tags
+ */
+export function isMatch(
+  tags: Array<string>,
+  name: string,
+  tagsPattern?: Array<string>,
+  matchPattern?: string
+) {
+  if (tagsPattern) {
+    return tagsMatch(tags, tagsPattern);
+  }
+  if (matchPattern) {
+    return (
+      micromatch.isMatch(name, matchPattern) || tagsMatch(tags, matchPattern)
+    );
+  }
+  return true;
+}
+
+export function tagsMatch(tags, pattern) {
+  const matchess = micromatch(tags || ['*'], pattern);
+  return matchess.length > 0;
+}

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
@@ -63,6 +52,7 @@ export type {
   ChromiumBrowser,
   ChromiumBrowserContext,
   CDPSession,
+  APIRequestContext,
 } from 'playwright-chromium';
 
 /**
@@ -72,3 +62,12 @@ 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';