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

package/src/dsl/monitor.ts

@@ -0,0 +1,87 @@
+/**
+ * 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';
+import { LocationsMap } from './locations';
+
+export type SyntheticsLocationsType = keyof typeof LocationsMap;
+export const SyntheticsLocations = Object.keys(
+  LocationsMap
+) as SyntheticsLocationsType[];
+
+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/dsl/step.ts

@@ -23,16 +23,23 @@
  *
  */
 
-import { VoidCallback } from '../common_types';
+import { Location, VoidCallback } from '../common_types';
 
 export class Step {
   name: string;
   index: number;
   callback: VoidCallback;
+  location?: Location;
 
-  constructor(name: string, index: number, callback: VoidCallback) {
+  constructor(
+    name: string,
+    index: number,
+    callback: VoidCallback,
+    location: Location
+  ) {
     this.name = name;
     this.index = index;
     this.callback = callback;
+    this.location = location;
   }
 }

package/src/formatter/javascript.ts

@@ -0,0 +1,367 @@
+/**
+ * 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 {
+  JavaScriptLanguageGenerator,
+  JavaScriptFormatter,
+} from 'playwright-core/lib/server/supplements/recorder/javascript';
+
+export type Step = {
+  actions: ActionInContext[];
+  name?: string;
+};
+
+export type Steps = Step[];
+
+export type ActionInContext = {
+  pageAlias: string;
+  frameName?: string;
+  frameUrl: string;
+  isMainFrame: boolean;
+  action: Action;
+  committed?: boolean;
+  modified?: boolean;
+  title?: string;
+};
+
+export type Action = {
+  name: string;
+  selector?: string;
+  url?: string;
+  key?: string;
+  signals: Signal[];
+  modifiers?: number;
+  button?: 'left' | 'middle' | 'right';
+  clickCount?: number;
+  text?: string;
+  value?: string;
+  isAssert?: boolean;
+  command?: string;
+  files?: string[];
+  options?: string[];
+};
+
+export type Signal = {
+  name: string;
+  url?: string;
+  isAsync?: boolean;
+  popupAlias?: string;
+  downloadAlias?: string;
+  dialogAlias?: string;
+};
+
+export class SyntheticsGenerator extends JavaScriptLanguageGenerator {
+  private previousContext: ActionInContext;
+  private insideStep: boolean;
+
+  constructor(private isSuite: boolean) {
+    super(true);
+    this.insideStep = false;
+    this.previousContext = undefined;
+  }
+
+  /**
+   * Generate code for an action.
+   * @param actionInContext The action to create code for.
+   * @returns the strings generated for the action.
+   */
+  generateAction(actionInContext: ActionInContext) {
+    const { action, pageAlias } = actionInContext;
+    if (action.name === 'openPage') {
+      return '';
+    }
+    // Don't cleanup page object managed by Synthetics
+    const isCleanUp = action.name === 'closePage' && pageAlias === 'page';
+    if (isCleanUp) {
+      return '';
+    }
+
+    const stepIndent = this.insideStep ? 2 : 0;
+    const offset = this.isSuite ? 2 + stepIndent : 0 + stepIndent;
+    const formatter = new JavaScriptFormatter(offset);
+
+    const subject = actionInContext.isMainFrame
+      ? pageAlias
+      : actionInContext.frameName
+      ? `${pageAlias}.frame(${formatObject({
+          name: actionInContext.frameName,
+        })})`
+      : `${pageAlias}.frame(${formatObject({
+          url: actionInContext.frameUrl,
+        })})`;
+
+    const signals = toSignalMap(action);
+
+    if (signals.dialog) {
+      formatter.add(`  ${pageAlias}.once('dialog', dialog => {
+    console.log(\`Dialog message: $\{dialog.message()}\`);
+    dialog.dismiss().catch(() => {});
+  });`);
+    }
+
+    const emitPromiseAll =
+      signals.waitForNavigation || signals.popup || signals.download;
+    if (emitPromiseAll) {
+      // Generate either await Promise.all([]) or
+      // const [popup1] = await Promise.all([]).
+      let leftHandSide = '';
+      if (signals.popup)
+        leftHandSide = `const [${signals.popup.popupAlias}] = `;
+      else if (signals.download) leftHandSide = `const [download] = `;
+      formatter.add(`${leftHandSide}await Promise.all([`);
+    }
+
+    // Popup signals.
+    if (signals.popup) formatter.add(`${pageAlias}.waitForEvent('popup'),`);
+
+    // Navigation signal.
+    if (signals.waitForNavigation)
+      formatter.add(
+        `${pageAlias}.waitForNavigation(/*{ url: ${quote(
+          signals.waitForNavigation.url
+        )} }*/),`
+      );
+
+    // Download signals.
+    if (signals.download)
+      formatter.add(`${pageAlias}.waitForEvent('download'),`);
+
+    const prefix =
+      signals.popup || signals.waitForNavigation || signals.download
+        ? ''
+        : 'await ';
+    const actionCall = super._generateActionCall(action);
+    // Add assertion from Synthetics.
+    const isAssert = action.name === 'assert' && action.isAssert;
+
+    if (!isAssert) {
+      const suffix = signals.waitForNavigation || emitPromiseAll ? '' : ';';
+      formatter.add(`${prefix}${subject}.${actionCall}${suffix}`);
+
+      if (emitPromiseAll) {
+        formatter.add(`]);`);
+      } else if (signals.assertNavigation) {
+        formatter.add(
+          `  expect(${pageAlias}.url()).toBe(${quote(
+            signals.assertNavigation.url
+          )});`
+        );
+      }
+    } else if (action.command) {
+      formatter.add(toAssertCall(pageAlias, action));
+    }
+
+    this.previousContext = actionInContext;
+    return formatter.format();
+  }
+
+  isNewStep(actioninContext: ActionInContext) {
+    const { action, frameUrl } = actioninContext;
+    if (action.name === 'navigate') {
+      return true;
+    } else if (action.name === 'click') {
+      return (
+        this.previousContext?.frameUrl === frameUrl && action.signals.length > 0
+      );
+    }
+    return false;
+  }
+
+  generateStepStart(name) {
+    this.insideStep = true;
+    const formatter = new JavaScriptFormatter(this.isSuite ? 2 : 0);
+    formatter.add(`step(${quote(name)}, async () => {`);
+    return formatter.format();
+  }
+
+  generateStepEnd() {
+    if (!this.insideStep) {
+      return '';
+    }
+    this.insideStep = false;
+    const formatter = new JavaScriptFormatter(this.isSuite ? 2 : 0);
+    formatter.add(`});`);
+    return formatter.format();
+  }
+
+  generateHeader() {
+    const formatter = new JavaScriptFormatter(0);
+    formatter.add(`
+      const { journey, step, expect } = require('@elastic/synthetics');
+
+      journey('Recorded journey', async ({ page, context }) => {`);
+    return formatter.format();
+  }
+
+  generateFooter() {
+    return `});`;
+  }
+
+  /**
+   * Generates JavaScript code from a custom set of steps and nested actions.
+   *
+   * This function makes no assumptions about where steps should be created,
+   * and instead follows the step definitions the caller has defined.
+   * @param steps IR to use for code generation
+   * @returns a list of the code strings outputted by the generator
+   */
+  generateFromSteps(steps: Steps): string {
+    const text = [];
+    if (this.isSuite) {
+      text.push(this.generateHeader());
+    }
+    for (const step of steps) {
+      if (step.actions.length === 0)
+        throw Error('Cannot process an empty step');
+      text.push(
+        this.generateStepStart(
+          step.name ??
+            step.actions[0].title ??
+            actionTitle(step.actions[0].action)
+        )
+      );
+
+      for (const action of step.actions) {
+        const actionText = this.generateAction(action);
+        if (actionText.length) text.push(actionText);
+      }
+
+      text.push(this.generateStepEnd());
+    }
+    if (this.isSuite) {
+      text.push(this.generateFooter());
+    }
+    return text.filter(s => !!s).join('\n');
+  }
+}
+
+// TODO: Replace once Playwright releases new version
+export function quote(text: string, char = "'") {
+  const stringified = JSON.stringify(text);
+  const escapedText = stringified
+    .substring(1, stringified.length - 1)
+    .replace(/\\"/g, '"');
+  if (char === "'") return char + escapedText.replace(/[']/g, "\\'") + char;
+  if (char === '"') return char + escapedText.replace(/["]/g, '\\"') + char;
+  if (char === '`') return char + escapedText.replace(/[`]/g, '`') + char;
+  throw new Error('Invalid escape char');
+}
+
+function toSignalMap(action) {
+  let waitForNavigation;
+  let assertNavigation;
+  let popup;
+  let download;
+  let dialog;
+  for (const signal of action.signals) {
+    if (signal.name === 'navigation' && signal.isAsync)
+      waitForNavigation = signal;
+    else if (signal.name === 'navigation' && !signal.isAsync)
+      assertNavigation = signal;
+    else if (signal.name === 'popup') popup = signal;
+    else if (signal.name === 'download') download = signal;
+    else if (signal.name === 'dialog') dialog = signal;
+  }
+  return {
+    waitForNavigation,
+    assertNavigation,
+    popup,
+    download,
+    dialog,
+  };
+}
+
+function toAssertCall(pageAlias, action) {
+  const { command, selector, value } = action;
+  switch (command) {
+    case 'textContent':
+    case 'innerText':
+      return `expect(await ${pageAlias}.${command}(${quote(
+        selector
+      )})).toMatch(${quote(value)});`;
+    case 'isVisible':
+    case 'isHidden':
+    case 'isChecked':
+    case 'isEditable':
+    case 'isEnabled':
+    case 'isDisabled':
+      return `expect(await ${pageAlias}.${command}(${quote(
+        selector
+      )})).toBeTruthy();`;
+  }
+}
+
+function formatObject(value, indent = '  ') {
+  if (typeof value === 'string') return quote(value);
+  if (Array.isArray(value))
+    return `[${value.map(o => formatObject(o)).join(', ')}]`;
+  if (typeof value === 'object') {
+    const keys = Object.keys(value);
+    if (!keys.length) return '{}';
+    const tokens = [];
+    for (const key of keys) tokens.push(`${key}: ${formatObject(value[key])}`);
+    return `{\n${indent}${tokens.join(`,\n${indent}`)}\n}`;
+  }
+  return String(value);
+}
+
+/**
+ * Generates an appropriate title string based on the action type/data.
+ * @param action Playwright action IR
+ * @returns title string
+ */
+export function actionTitle(action: Action) {
+  switch (action.name) {
+    case 'openPage':
+      return `Open new page`;
+    case 'closePage':
+      return `Close page`;
+    case 'check':
+      return `Check ${action.selector}`;
+    case 'uncheck':
+      return `Uncheck ${action.selector}`;
+    case 'click': {
+      if (action.clickCount === 1) return `Click ${action.selector}`;
+      if (action.clickCount === 2) return `Double click ${action.selector}`;
+      if (action.clickCount === 3) return `Triple click ${action.selector}`;
+      return `${action.clickCount}× click`;
+    }
+    case 'fill':
+      return `Fill ${action.selector}`;
+    case 'setInputFiles':
+      if (action.files.length === 0) return `Clear selected files`;
+      else return `Upload ${action.files.join(', ')}`;
+    case 'navigate':
+      return `Go to ${action.url}`;
+    case 'press':
+      return (
+        `Press ${action.key}` + (action.modifiers ? ' with modifiers' : '')
+      );
+    case 'select':
+      return `Select ${action.options.join(', ')}`;
+    case 'assert':
+      return `Assert ${action.selector} ${action.command}`;
+  }
+}

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/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();
+  }
+}