@elastic/synthetics 1.24.3 → 1.25.0

package/src/core/gatherer.ts

@@ -32,7 +32,12 @@ import {
 } from 'playwright-core';
 import { PluginManager } from '../plugins';
 import { log } from './logger';
-import { Driver, NetworkConditions, RunOptions } from '../common_types';
+import {
+  APIDriver,
+  Driver,
+  NetworkConditions,
+  RunOptions,
+} from '../common_types';
 
 // Default timeout for Playwright actions and Navigations
 const DEFAULT_TIMEOUT = 50000;
@@ -71,9 +76,19 @@ export class Gatherer {
     });
   }
 
-  static async setupDriver(options: RunOptions): Promise<Driver> {
-    await Gatherer.launchBrowser(options);
+  static async setupDriver<T extends 'browser' | 'api' = 'browser'>(
+    options: RunOptions,
+    journeyType: T = 'browser' as T
+  ): Promise<T extends 'api' ? APIDriver : Driver> {
     const { playwrightOptions } = options;
+
+    if (journeyType === 'api') {
+      const request = await apiRequest.newContext({ ...playwrightOptions });
+      return { request } as T extends 'api' ? APIDriver : Driver;
+    }
+
+    await Gatherer.launchBrowser(options);
+
     const context = await Gatherer.browser.newContext({
       ...playwrightOptions,
       userAgent: await Gatherer.getUserAgent(playwrightOptions?.userAgent),
@@ -96,7 +111,13 @@ export class Gatherer {
     const page = await context.newPage();
     const client = await context.newCDPSession(page);
     const request = await apiRequest.newContext({ ...playwrightOptions });
-    return { browser: Gatherer.browser, context, page, client, request };
+    return {
+      browser: Gatherer.browser,
+      context,
+      page,
+      client,
+      request,
+    } as T extends 'api' ? APIDriver : Driver;
   }
 
   static async getUserAgent(userAgent?: string) {
@@ -136,14 +157,22 @@ export class Gatherer {
    * Starts recording all events related to the v8 devtools protocol
    * https://chromedevtools.github.io/devtools-protocol/v8/
    */
-  static async beginRecording(driver: Driver, options: RunOptions) {
+  static async beginRecording(driver: Driver | APIDriver, options: RunOptions) {
     log('Gatherer: started recording');
     const { network, metrics } = options;
     Gatherer.pluginManager = new PluginManager(driver);
     Gatherer.pluginManager.registerAll(options);
-    const plugins = [await Gatherer.pluginManager.start('browserconsole')];
-    network && plugins.push(await Gatherer.pluginManager.start('network'));
-    metrics && plugins.push(await Gatherer.pluginManager.start('performance'));
+    const plugins = [];
+    if ('browser' in driver) {
+      plugins.push(await Gatherer.pluginManager.start('browserconsole'));
+      network && plugins.push(await Gatherer.pluginManager.start('network'));
+      metrics &&
+        plugins.push(await Gatherer.pluginManager.start('performance'));
+    } else {
+      // Network is the only data source for API journeys, so always capture
+      // it regardless of `options.network`.
+      plugins.push(await Gatherer.pluginManager.start('network'));
+    }
     await Promise.all(plugins);
     return Gatherer.pluginManager;
   }
@@ -153,10 +182,12 @@ export class Gatherer {
     await Gatherer.pluginManager.unregisterAll();
   }
 
-  static async dispose(driver: Driver) {
+  static async dispose(driver: Driver | APIDriver) {
     log(`Gatherer: closing all contexts`);
     await driver.request.dispose();
-    await driver.context.close();
+    if ('context' in driver) {
+      await driver.context.close();
+    }
   }
 
   static async stop() {

package/src/core/globals.ts

@@ -26,7 +26,7 @@
 import Runner from './runner';
 
 /**
- * Use a gloabl Runner which would be accessed by the runtime and
+ * Use a global Runner which would be accessed by the runtime and
  * required to handle the local vs global invocation through CLI
  */
 const SYNTHETICS_RUNNER = Symbol.for('SYNTHETICS_RUNNER');

package/src/core/index.ts

@@ -24,6 +24,10 @@
  */
 
 import {
+  APIJourney,
+  APIJourneyCallback,
+  APIJourneyOptions,
+  APIJourneyWithAnnotations,
   Journey,
   JourneyCallback,
   JourneyOptions,
@@ -60,6 +64,30 @@ export const journey = createJourney() as JourneyWithAnnotations;
 journey.skip = createJourney('skip');
 journey.only = createJourney('only');
 
+const createAPIJourney = (type?: 'skip' | 'only') =>
+  wrapFnWithLocation(
+    (
+      location: Location,
+      options: APIJourneyOptions | string,
+      callback: APIJourneyCallback
+    ) => {
+      log(`API Journey register: ${JSON.stringify(options)}`);
+      if (typeof options === 'string') {
+        options = { name: options, id: options };
+      }
+      const j = new APIJourney(options, callback, location);
+      if (type) {
+        j[type] = true;
+      }
+      runner._addJourney(j);
+      return j;
+    }
+  );
+
+export const apiJourney = createAPIJourney() as APIJourneyWithAnnotations;
+apiJourney.skip = createAPIJourney('skip');
+apiJourney.only = createAPIJourney('only');
+
 const createStep = (type?: 'skip' | 'soft' | 'only') =>
   wrapFnWithLocation(
     (location: Location, name: string, callback: VoidCallback) => {

package/src/core/runner.ts

@@ -25,7 +25,7 @@
 
 import { join } from 'path';
 import { mkdir, rm, writeFile } from 'fs/promises';
-import { Journey } from '../dsl/journey';
+import { Journey, JourneyCallbackOpts } from '../dsl/journey';
 import { Step } from '../dsl/step';
 import { reporters, Reporter } from '../reporters';
 import {
@@ -44,6 +44,7 @@ import {
   JourneyResult,
   StepResult,
   PushOptions,
+  APIDriver,
 } from '../common_types';
 import { PerformanceManager, filterBrowserMessages } from '../plugins';
 import { Gatherer } from './gatherer';
@@ -66,7 +67,7 @@ export interface RunnerInfo {
    */
   readonly currentJourney: Journey | undefined;
   /**
-   * All registerd journeys
+   * All registered journeys
    */
   readonly journeys: Journey[];
 }
@@ -78,7 +79,7 @@ export default class Runner implements RunnerInfo {
   #journeys: Journey[] = [];
   #hooks: SuiteHooks = { beforeAll: [], afterAll: [] };
   #screenshotPath = join(CACHE_PATH, 'screenshots');
-  #driver?: Driver;
+  #driver?: Driver | APIDriver;
   #browserDelay = -1;
   #hookError: Error | undefined;
   #monitor?: Monitor;
@@ -210,18 +211,22 @@ export default class Runner implements RunnerInfo {
   async #runStep(step: Step, options: RunOptions): Promise<StepResult> {
     log(`Runner: start step (${step.name})`);
     const { metrics, screenshots, filmstrips, trace } = options;
-    /**
-     * URL needs to be the first navigation request of any step
-     * Listening for request solves the case where `about:blank` would be
-     * reported for failed navigations
-     */
-    const captureUrl = req => {
-      if (!step.url && req.isNavigationRequest()) {
-        step.url = req.url();
-      }
-      this.#driver.context.off('request', captureUrl);
-    };
-    this.#driver.context.on('request', captureUrl);
+
+    if ('context' in this.#driver) {
+      /**
+       * URL needs to be the first navigation request of any step
+       * Listening for request solves the case where `about:blank` would be
+       * reported for failed navigations
+       */
+      const captureUrl = req => {
+        if (!step.url && req.isNavigationRequest()) {
+          step.url = req.url();
+        }
+        'context' in this.#driver &&
+          this.#driver.context.off('request', captureUrl);
+      };
+      this.#driver.context.on('request', captureUrl);
+    }
 
     const data: StepResult = {};
     const traceEnabled = trace || filmstrips;
@@ -240,30 +245,32 @@ export default class Runner implements RunnerInfo {
       step.status = 'failed';
       step.error = error;
     } finally {
-      /**
-       * Collect all step level metrics and trace events
-       */
-      if (metrics) {
-        data.pagemetrics = await (
-          Gatherer.pluginManager.get('performance') as PerformanceManager
-        ).getMetrics();
-      }
-      if (traceEnabled) {
-        const traceOutput = await Gatherer.pluginManager.stop('trace');
-        Object.assign(data, traceOutput);
-      }
-      /**
-       * Capture screenshot for the newly created pages
-       * via popup or new windows/tabs
-       *
-       * Last open page will get us the correct screenshot
-       */
-      const pages = this.#driver.context.pages();
-      const page = pages[pages.length - 1];
-      if (page) {
-        step.url ??= page.url();
-        if (screenshots && screenshots !== 'off') {
-          await this.captureScreenshot(page, step);
+      if ('context' in this.#driver) {
+        /**
+         * Collect all step level metrics and trace events
+         */
+        if (metrics) {
+          data.pagemetrics = await (
+            Gatherer.pluginManager.get('performance') as PerformanceManager
+          ).getMetrics();
+        }
+        if (traceEnabled) {
+          const traceOutput = await Gatherer.pluginManager.stop('trace');
+          Object.assign(data, traceOutput);
+        }
+        /**
+         * Capture screenshot for the newly created pages
+         * via popup or new windows/tabs
+         *
+         * Last open page will get us the correct screenshot
+         */
+        const pages = this.#driver.context.pages();
+        const page = pages[pages.length - 1];
+        if (page) {
+          step.url ??= page.url();
+          if (screenshots && screenshots !== 'off') {
+            await this.captureScreenshot(page, step);
+          }
         }
       }
     }
@@ -310,22 +317,24 @@ export default class Runner implements RunnerInfo {
 
   async #startJourney(journey: Journey, options: RunOptions) {
     journey._startTime = monotonicTimeInSeconds();
-    this.#driver = await Gatherer.setupDriver(options);
+    this.#driver = await Gatherer.setupDriver(options, journey.type);
     await Gatherer.beginRecording(this.#driver, options);
-    /**
-     * For each journey we create the screenshots folder for
-     * caching all screenshots and clear them at end of each journey
-     */
-    await mkdir(this.#screenshotPath, { recursive: true });
+    if (journey.type === 'browser') {
+      /**
+       * For each journey we create the screenshots folder for
+       * caching all screenshots and clear them at end of each journey
+       */
+      await mkdir(this.#screenshotPath, { recursive: true });
+    }
     const params = options.params;
     this.#reporter?.onJourneyStart?.(journey, {
       timestamp: getTimestamp(),
       params,
     });
     /**
-     * Exeucute the journey callback which registers the steps for current journey
+     * Execute the journey callback which registers the steps for current journey
      */
-    journey.cb({ ...this.#driver, params, info: this });
+    journey.cb({ ...this.#driver, params, info: this } as JourneyCallbackOpts);
   }
 
   async #endJourney(
@@ -335,24 +344,34 @@ export default class Runner implements RunnerInfo {
   ) {
     // Enhance the journey results
     const pOutput = await Gatherer.pluginManager.output();
-    const bConsole = filterBrowserMessages(
-      pOutput.browserconsole,
-      journey.status
-    );
-    await this.#reporter?.onJourneyEnd?.(journey, {
-      browserDelay: this.#browserDelay,
-      timestamp: getTimestamp(),
-      options,
-      networkinfo: pOutput.networkinfo,
-      browserconsole: bConsole,
-    });
+    const isBrowserJourney = journey.type === 'browser';
+    const bConsole = isBrowserJourney
+      ? filterBrowserMessages(pOutput.browserconsole, journey.status)
+      : undefined;
+    if (isBrowserJourney) {
+      await this.#reporter?.onJourneyEnd?.(journey, {
+        browserDelay: this.#browserDelay,
+        timestamp: getTimestamp(),
+        options,
+        networkinfo: pOutput.networkinfo,
+        browserconsole: bConsole,
+      });
+    } else {
+      await this.#reporter?.onJourneyEnd?.(journey, {
+        timestamp: getTimestamp(),
+        options,
+        networkinfo: pOutput.networkinfo,
+      });
+    }
     await Gatherer.endRecording();
     await Gatherer.dispose(this.#driver);
     // clear screenshots cache after each journey
-    await rm(this.#screenshotPath, { recursive: true, force: true });
+    if (isBrowserJourney) {
+      await rm(this.#screenshotPath, { recursive: true, force: true });
+    }
     return Object.assign(result, {
       networkinfo: pOutput.networkinfo,
-      browserconsole: bConsole,
+      ...(isBrowserJourney ? { browserconsole: bConsole } : {}),
       ...journey,
     });
   }
@@ -516,9 +535,9 @@ export default class Runner implements RunnerInfo {
     const { dryRun, grepOpts } = options;
 
     // collect all journeys with `.only` annotation and skip the rest
-    const onlyJournerys = this.#journeys.filter(j => j.only);
-    if (onlyJournerys.length > 0) {
-      this.#journeys = onlyJournerys;
+    const onlyJourneys = this.#journeys.filter(j => j.only);
+    if (onlyJourneys.length > 0) {
+      this.#journeys = onlyJourneys;
     } else {
       // filter journeys based on tags and skip annotations
       this.#journeys = this.#journeys.filter(
@@ -551,9 +570,16 @@ export default class Runner implements RunnerInfo {
 
   async _runJourneys(options: RunOptions) {
     const result: RunResult = {};
-    const browserStart = monotonicTimeInSeconds();
-    await Gatherer.launchBrowser(options);
-    this.#browserDelay = monotonicTimeInSeconds() - browserStart;
+    /**
+     * Only spin up a Chromium browser if at least one browser journey is
+     * scheduled to run. Pure API-journey suites skip launch entirely.
+     */
+    const hasBrowserJourneys = this.#journeys.some(j => j.type === 'browser');
+    if (hasBrowserJourneys) {
+      const browserStart = monotonicTimeInSeconds();
+      await Gatherer.launchBrowser(options);
+      this.#browserDelay = monotonicTimeInSeconds() - browserStart;
+    }
 
     for (const journey of this.#journeys) {
       const journeyResult: JourneyResult = this.#hookError
@@ -578,7 +604,7 @@ export default class Runner implements RunnerInfo {
     this.#journeys = [];
     this.#active = false;
     /**
-     * Clear all cache data stored for post processing by
+     * Clear all cache data stored for post-processing by
      * the current synthetic agent run
      */
     await rm(CACHE_PATH, { recursive: true, force: true });

package/src/dsl/api-journey.ts

@@ -0,0 +1,93 @@
+/**
+ * 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 { APIRequestContext } from 'playwright-core';
+import { Location, Params } from '../common_types';
+
+import { Journey } from './journey';
+import { Monitor, MonitorConfig } from './monitor';
+import { RunnerInfo } from '../core/runner';
+
+export type APIJourneyOptions = {
+  name: string;
+  id?: string;
+  tags?: string[];
+};
+
+export type APIJourneyCallbackOpts = {
+  params: Params;
+  request: APIRequestContext;
+  info: RunnerInfo;
+};
+export type APIJourneyCallback = (options: APIJourneyCallbackOpts) => void;
+
+type APIJourneyType = (
+  options: string | APIJourneyOptions,
+  callback: APIJourneyCallback
+) => APIJourney;
+
+/**
+ * Same step-based model as a browser `Journey` but without a Chromium
+ * context. `type === 'api'` lets the runner/gatherer/plugin-manager skip
+ * browser-only setup.
+ */
+export class APIJourney extends Journey {
+  constructor(
+    options: APIJourneyOptions | string,
+    cb: APIJourneyCallback,
+    location?: Location
+  ) {
+    const opts =
+      typeof options === 'string'
+        ? { name: options, id: options }
+        : { ...options };
+    // Runner narrows callback args by `journey.type`, so the cast is sound.
+    super({ ...opts, type: 'api' }, cb as any, location);
+  }
+
+  // Register as an `api` project monitor on `synthetics push`.
+  override _updateMonitor(config: MonitorConfig) {
+    this._setMonitor(
+      new Monitor({
+        name: this.name,
+        id: this.id,
+        type: 'api',
+        tags: this.tags ?? [],
+        ...config,
+      })
+    );
+  }
+}
+
+export type APIJourneyWithAnnotations = APIJourneyType & {
+  /**
+   * Skip this journey and all its steps
+   */
+  skip: APIJourneyType;
+  /**
+   * Run only this journey and skip rest of the journeys
+   */
+  only: APIJourneyType;
+};

package/src/dsl/index.ts

@@ -24,4 +24,5 @@
  */
 
 export * from './journey';
+export * from './api-journey';
 export * from './step';

package/src/dsl/journey.ts

@@ -50,7 +50,7 @@ export type JourneyOptions = {
 
 type HookType = 'before' | 'after';
 export type Hooks = Record<HookType, Array<HooksCallback>>;
-type JourneyCallbackOpts = {
+export type JourneyCallbackOpts = {
   page: Page;
   context: BrowserContext;
   browser: Browser;
@@ -62,6 +62,7 @@ type JourneyCallbackOpts = {
 export type JourneyCallback = (options: JourneyCallbackOpts) => void;
 
 export class Journey {
+  readonly type: 'browser' | 'api' = 'browser';
   readonly name: string;
   readonly id?: string;
   readonly tags?: string[];
@@ -78,10 +79,11 @@ export class Journey {
   error?: Error;
 
   constructor(
-    options: JourneyOptions,
+    options: JourneyOptions & { type?: 'browser' | 'api' },
     cb: JourneyCallback,
     location?: Location
   ) {
+    this.type = options.type ?? 'browser';
     this.name = options.name;
     this.id = options.id || options.name;
     this.tags = options.tags;
@@ -144,13 +146,23 @@ export class Journey {
     /**
      * Use defaults values from journey for monitor object (id, name and tags)
      */
-    this.#monitor = new Monitor({
-      name: this.name,
-      id: this.id,
-      type: 'browser',
-      tags: this.tags ?? [],
-      ...config,
-    });
+    this._setMonitor(
+      new Monitor({
+        name: this.name,
+        id: this.id,
+        type: 'browser',
+        tags: this.tags ?? [],
+        ...config,
+      })
+    );
+  }
+
+  /**
+   * Subclasses use this to swap in a monitor with a different default
+   * `type` while reusing the source-location and name-filter wiring.
+   */
+  protected _setMonitor(monitor: Monitor) {
+    this.#monitor = monitor;
     this.#monitor.setSource(this.location);
     this.#monitor.setFilter({ match: this.name });
   }