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

package/src/core/runner.ts

@@ -23,12 +23,11 @@
  *
  */
 
-import { once, EventEmitter } from 'events';
 import { join } from 'path';
 import { rm } from 'fs/promises';
 import { Journey } from '../dsl/journey';
 import { Step } from '../dsl/step';
-import { reporters } from '../reporters';
+import { reporters, Reporter } from '../reporters';
 import {
   CACHE_PATH,
   monotonicTimeInSeconds,
@@ -39,20 +38,20 @@ import {
   writeFileAsync,
 } from '../helpers';
 import {
-  StatusValue,
   HooksCallback,
   Params,
-  NetworkConditions,
-  PluginOutput,
   HooksArgs,
   Driver,
   Screenshot,
   RunOptions,
+  JourneyResult,
+  StepResult,
 } from '../common_types';
-import { PageMetrics, PluginManager } from '../plugins';
+import { PluginManager } from '../plugins';
 import { PerformanceManager } from '../plugins';
 import { Gatherer } from './gatherer';
 import { log } from './logger';
+import { Monitor, MonitorConfig } from '../dsl/monitor';
 
 type HookType = 'beforeAll' | 'afterAll';
 export type SuiteHooks = Record<HookType, Array<HooksCallback>>;
@@ -64,73 +63,16 @@ type JourneyContext = {
   pluginManager: PluginManager;
 };
 
-type StepResult = {
-  status: StatusValue;
-  url?: string;
-  error?: Error;
-  pagemetrics?: PageMetrics;
-  filmstrips?: PluginOutput['filmstrips'];
-  metrics?: PluginOutput['metrics'];
-  traces?: PluginOutput['traces'];
-};
-
-type JourneyResult = {
-  status: StatusValue;
-  error?: Error;
-  networkinfo?: PluginOutput['networkinfo'];
-  browserconsole?: PluginOutput['browserconsole'];
-};
-
 type RunResult = Record<string, JourneyResult>;
 
-interface StepEvent {
-  step: Step;
-  journey: Journey;
-}
-
-interface JourneyEvent {
-  journey: Journey;
-  timestamp: number;
-  params?: Params;
-}
-
-interface Events {
-  start: {
-    numJourneys: number;
-    networkConditions?: NetworkConditions;
-  };
-  'journey:register': {
-    journey: Journey;
-  };
-  'journey:start': JourneyEvent;
-  'journey:end': JourneyEvent &
-    JourneyResult & {
-      start: number;
-      end: number;
-      options: RunOptions;
-      timestamp: number;
-    };
-  'journey:end:reported': unknown;
-  'step:start': StepEvent;
-  'step:end': StepEvent &
-    StepResult & {
-      start: number;
-      end: number;
-    };
-  end: unknown;
-}
-
-export default interface Runner {
-  on<K extends keyof Events>(name: K, listener: (v: Events[K]) => void): this;
-  emit<K extends keyof Events>(event: K, args: Events[K]): boolean;
-}
-
-export default class Runner extends EventEmitter {
-  active = false;
-  currentJourney?: Journey = null;
+export default class Runner {
+  #active = false;
+  #reporter: Reporter;
+  #currentJourney?: Journey = null;
   journeys: Journey[] = [];
   hooks: SuiteHooks = { beforeAll: [], afterAll: [] };
   hookError: Error | undefined;
+  monitor?: Monitor;
   static screenshotPath = join(CACHE_PATH, 'screenshots');
 
   static async createContext(options: RunOptions): Promise<JourneyContext> {
@@ -181,13 +123,38 @@ export default class Runner extends EventEmitter {
     }
   }
 
+  get currentJourney() {
+    return this.#currentJourney;
+  }
+
   addHook(type: HookType, callback: HooksCallback) {
     this.hooks[type].push(callback);
   }
 
+  updateMonitor(config: MonitorConfig) {
+    if (!this.monitor) {
+      this.monitor = new Monitor(config);
+      return;
+    }
+    this.monitor.update(config);
+  }
+
   addJourney(journey: Journey) {
     this.journeys.push(journey);
-    this.currentJourney = journey;
+    this.#currentJourney = journey;
+  }
+
+  setReporter(options: RunOptions) {
+    /**
+     * Set up the corresponding reporter and fallback
+     * to default reporter if not provided
+     */
+    const { reporter, outfd } = options;
+    const Reporter =
+      typeof reporter === 'function'
+        ? reporter
+        : reporters[reporter] || reporters['default'];
+    this.#reporter = new Reporter({ fd: outfd });
   }
 
   async runBeforeAllHook(args: HooksArgs) {
@@ -288,7 +255,7 @@ export default class Runner extends EventEmitter {
     let skipStep = false;
     for (const step of journey.steps) {
       const start = monotonicTimeInSeconds();
-      this.emit('step:start', { journey, step });
+      this.#reporter?.onStepStart?.(journey, step);
       let data: StepResult = { status: 'succeeded' };
       if (skipStep) {
         data.status = 'skipped';
@@ -299,9 +266,7 @@ export default class Runner extends EventEmitter {
          */
         if (data.error) skipStep = true;
       }
-      this.emit('step:end', {
-        journey,
-        step,
+      this.#reporter?.onStepEnd?.(journey, step, {
         start,
         end: monotonicTimeInSeconds(),
         ...data,
@@ -315,12 +280,16 @@ export default class Runner extends EventEmitter {
   }
 
   registerJourney(journey: Journey, context: JourneyContext) {
-    this.currentJourney = journey;
+    this.#currentJourney = journey;
     const timestamp = getTimestamp();
     const { params } = context;
-    this.emit('journey:start', { journey, timestamp, params });
+    this.#reporter?.onJourneyStart?.(journey, {
+      timestamp,
+      params,
+    });
     /**
-     * Load and register the steps for the current journey
+     * Exeucute the journey callback which would
+     * register the steps for the current journey
      */
     journey.callback({ ...context.driver, params });
   }
@@ -332,9 +301,8 @@ export default class Runner extends EventEmitter {
   ) {
     const end = monotonicTimeInSeconds();
     const { pluginManager, start, status, error } = result;
-    const pluginOutput = pluginManager.output();
-    this.emit('journey:end', {
-      journey,
+    const pluginOutput = await pluginManager.output();
+    await this.#reporter?.onJourneyEnd?.(journey, {
       status,
       error,
       start,
@@ -344,13 +312,6 @@ export default class Runner extends EventEmitter {
       ...pluginOutput,
       browserconsole: status == 'failed' ? pluginOutput.browserconsole : [],
     });
-    /**
-     * Wait for the all the reported events to be consumed aschronously
-     * by reporter.
-     */
-    if (options.reporter === 'json') {
-      await once(this, 'journey:end:reported');
-    }
     // clear screenshots cache after each journey
     await rm(Runner.screenshotPath, { recursive: true, force: true });
   }
@@ -360,8 +321,7 @@ export default class Runner extends EventEmitter {
    */
   async runFakeJourney(journey: Journey, options: RunOptions) {
     const start = monotonicTimeInSeconds();
-    this.emit('journey:start', {
-      journey,
+    this.#reporter.onJourneyStart?.(journey, {
       timestamp: getTimestamp(),
       params: options.params,
     });
@@ -369,24 +329,18 @@ export default class Runner extends EventEmitter {
       status: 'failed',
       error: this.hookError,
     };
-    this.emit('journey:end', {
-      journey,
+    await this.#reporter.onJourneyEnd?.(journey, {
       timestamp: getTimestamp(),
       start,
       options,
       end: monotonicTimeInSeconds(),
       ...result,
     });
-    if (options.reporter === 'json') {
-      await once(this, 'journey:end:reported');
-    }
     return result;
   }
 
   async runJourney(journey: Journey, options: RunOptions) {
-    const result: JourneyResult = {
-      status: 'succeeded',
-    };
+    const result: JourneyResult = { status: 'succeeded' };
     const context = await Runner.createContext(options);
     log(`Runner: start journey (${journey.name})`);
     try {
@@ -419,18 +373,10 @@ export default class Runner extends EventEmitter {
   }
 
   async init(options: RunOptions) {
-    const { reporter, outfd, networkConditions } = options;
-    /**
-     * Set up the corresponding reporter and fallback
-     */
-    const Reporter =
-      typeof reporter === 'function'
-        ? reporter
-        : reporters[reporter] || reporters['default'];
-    new Reporter(this, { fd: outfd });
-    this.emit('start', {
+    this.setReporter(options);
+    this.#reporter.onStart?.({
       numJourneys: this.journeys.length,
-      networkConditions,
+      networkConditions: options.networkConditions,
     });
     /**
      * Set up the directory for caching screenshots
@@ -438,12 +384,39 @@ export default class Runner extends EventEmitter {
     await mkdirAsync(CACHE_PATH, { recursive: true });
   }
 
+  buildMonitors(options: RunOptions) {
+    /**
+     * Update the global monitor configuration required for
+     * setting defaults
+     */
+    this.updateMonitor({
+      throttling: options.throttling,
+      schedule: options.schedule,
+      locations: options.locations,
+      params: options.params,
+      playwrightOptions: options.playwrightOptions,
+    });
+
+    const monitors: Monitor[] = [];
+    for (const journey of this.journeys) {
+      this.#currentJourney = journey;
+      /**
+       * Execute dummy callback to get all monitor specific
+       * configurations for the current journey
+       */
+      journey.callback({ params: options.params } as any);
+      journey.monitor.update(this.monitor?.config);
+      monitors.push(journey.monitor);
+    }
+    return monitors;
+  }
+
   async run(options: RunOptions) {
     const result: RunResult = {};
-    if (this.active) {
+    if (this.#active) {
       return result;
     }
-    this.active = true;
+    this.#active = true;
     log(`Runner: run ${this.journeys.length} journeys`);
     this.init(options);
     await this.runBeforeAllHook({
@@ -457,7 +430,7 @@ export default class Runner extends EventEmitter {
        * Used by heartbeat to gather all registered journeys
        */
       if (dryRun) {
-        this.emit('journey:register', { journey });
+        this.#reporter.onJourneyRegister?.(journey);
         continue;
       }
       if (!journey.isMatch(match, tags)) {
@@ -478,14 +451,14 @@ export default class Runner extends EventEmitter {
   }
 
   async reset() {
+    this.#currentJourney = null;
+    this.journeys = [];
+    this.#active = false;
     /**
      * Clear all cache data stored for post processing by
      * the current synthetic agent run
      */
     await rm(CACHE_PATH, { recursive: true, force: true });
-    this.currentJourney = null;
-    this.journeys = [];
-    this.active = false;
-    this.emit('end', {});
+    await this.#reporter?.onEnd?.();
   }
 }

package/src/dsl/journey.ts

@@ -27,6 +27,7 @@ import { Browser, Page, BrowserContext, CDPSession } from 'playwright-chromium';
 import micromatch, { isMatch } from 'micromatch';
 import { Step } from './step';
 import { VoidCallback, HooksCallback, Params, Location } from '../common_types';
+import { Monitor, MonitorConfig } from './monitor';
 
 export type JourneyOptions = {
   name: string;
@@ -52,6 +53,7 @@ export class Journey {
   location?: Location;
   steps: Step[] = [];
   hooks: Hooks = { before: [], after: [] };
+  monitor: Monitor;
 
   constructor(
     options: JourneyOptions,
@@ -63,6 +65,7 @@ export class Journey {
     this.tags = options.tags;
     this.callback = callback;
     this.location = location;
+    this.updateMonitor({});
   }
 
   addStep(name: string, callback: VoidCallback, location?: Location) {
@@ -74,6 +77,21 @@ export class Journey {
   addHook(type: HookType, callback: HooksCallback) {
     this.hooks[type].push(callback);
   }
+
+  updateMonitor(config: MonitorConfig) {
+    /**
+     * Use defaults values from journey for monitor object (id, name and tags)
+     */
+    this.monitor = new Monitor({
+      name: this.name,
+      id: this.id,
+      tags: this.tags ?? [],
+      ...config,
+    });
+    this.monitor.setSource(this.location);
+    this.monitor.setFilter({ match: this.name });
+  }
+
   /**
    * Matches journeys based on the provided args. Proitize tags over match
    * - tags pattern that matches only tags

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/formatter/javascript.ts

@@ -26,7 +26,7 @@
 import {
   JavaScriptLanguageGenerator,
   JavaScriptFormatter,
-} from 'playwright-chromium/lib/server/supplements/recorder/javascript';
+} from 'playwright-core/lib/server/supplements/recorder/javascript';
 
 export type Step = {
   actions: ActionInContext[];

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}`;
+}