@elastic/synthetics 1.24.4 → 1.25.0

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 });
   }

package/src/index.ts

@@ -35,6 +35,7 @@ export async function run(options: RunOptions) {
  */
 export {
   journey,
+  apiJourney,
   step,
   monitor,
   beforeAll,
@@ -82,6 +83,11 @@ export type {
   JourneyWithAnnotations,
   JourneyOptions,
   StepWithAnnotations,
+  APIJourney,
+  APIJourneyCallback,
+  APIJourneyCallbackOpts,
+  APIJourneyOptions,
+  APIJourneyWithAnnotations,
 } from './dsl';
 
 export type {

package/src/loader.ts

@@ -24,7 +24,10 @@
  */
 
 import { stdin, cwd } from 'process';
-import { extname, resolve } from 'path';
+import { extname, resolve, join } from 'path';
+import { tmpdir } from 'os';
+import { mkdtempSync, writeFileSync, rmSync } from 'fs';
+import Module from 'module';
 import { CliArgs } from './common_types';
 import { step, journey } from './core';
 import { log } from './core/logger';
@@ -83,7 +86,21 @@ export async function loadTestFiles(options: CliArgs, args: string[]) {
   requireSuites(suites);
 }
 
-const loadInlineScript = source => {
+/**
+ * A leading `import`/`export` opts the inline source into module loading;
+ * anything else is treated as legacy statements with injected locals.
+ * Keying off `import`/`export` (not a `journey(` regex) avoids false
+ * matches inside strings/comments that would strip the implicit injection.
+ */
+const isModuleInlineSource = (source: string): boolean => {
+  return /^\s*(?:import|export)\b/m.test(source);
+};
+
+const loadInlineScript = (source: string) => {
+  if (isModuleInlineSource(source)) {
+    loadInlineModule(source);
+    return;
+  }
   const scriptFn = new Function(
     'step',
     'page',
@@ -109,6 +126,65 @@ const loadInlineScript = source => {
   });
 };
 
+const SYNTHETICS_PKG_ROOT = resolve(__dirname, '..');
+let syntheticsAliasInstalled = false;
+
+/**
+ * Alias `@elastic/synthetics` (and subpaths) to this package so an inline
+ * module materialised in a temp dir — whose ancestors may lack a
+ * `node_modules` entry — resolves to the currently running code.
+ */
+const installSyntheticsRequireAlias = () => {
+  if (syntheticsAliasInstalled) return;
+  syntheticsAliasInstalled = true;
+  const PKG = '@elastic/synthetics';
+  const ModuleInternal = Module as unknown as {
+    _resolveFilename: (
+      request: string,
+      parent: NodeModule,
+      isMain?: boolean,
+      options?: Record<string, unknown>
+    ) => string;
+  };
+  const originalResolve = ModuleInternal._resolveFilename;
+  ModuleInternal._resolveFilename = function (
+    request,
+    parent,
+    isMain,
+    options
+  ) {
+    if (request === PKG || request.startsWith(`${PKG}/`)) {
+      const subpath = request === PKG ? '' : request.slice(PKG.length + 1);
+      const aliased = subpath
+        ? join(SYNTHETICS_PKG_ROOT, subpath)
+        : SYNTHETICS_PKG_ROOT;
+      return originalResolve.call(this, aliased, parent, isMain, options);
+    }
+    return originalResolve.call(this, request, parent, isMain, options);
+  };
+};
+
+/**
+ * Materialise a self-contained inline module to disk and `require` it. The
+ * esbuild transform hook rewrites ESM → CJS, so the script registers its
+ * journeys on import instead of being wrapped in an implicit journey.
+ */
+const loadInlineModule = (source: string) => {
+  installSyntheticsRequireAlias();
+  const dir = mkdtempSync(join(tmpdir(), 'synthetics-inline-'));
+  // Best-effort cleanup so long-lived hosts don't accumulate temp dirs.
+  process.once('exit', () => {
+    try {
+      rmSync(dir, { recursive: true, force: true });
+    } catch {
+      /* best-effort */
+    }
+  });
+  const file = join(dir, 'inline.journey.ts');
+  writeFileSync(file, source);
+  require(file);
+};
+
 /**
  * Read the input from STDIN and run it as inline journey
  */

package/src/network-timings.ts

@@ -0,0 +1,130 @@
+/**
+ * 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 { Request } from 'playwright-core';
+import { NetworkInfo } from './common_types';
+
+/**
+ * Resource Timing shape shared by `Request.timing()` and (>= 1.62)
+ * `APIResponse.timing()`. Values are milliseconds relative to `startTime`,
+ * `-1` when a phase did not happen or is unknown (e.g. reused keep-alive
+ * socket, HAR replay).
+ */
+export type ResourceTiming = ReturnType<Request['timing']>;
+
+export const roundMilliSecs = (value: number): number => {
+  return Math.floor(value * 1000) / 1000;
+};
+
+/**
+ * First positive number in the list, used to derive the `blocked` phase from
+ * whichever Resource Timing marker fired first.
+ */
+export const firstPositive = (numbers: number[]): number | null => {
+  for (let i = 0; i < numbers.length; ++i) {
+    if (numbers[i] > 0) {
+      return numbers[i];
+    }
+  }
+  return null;
+};
+
+/**
+ * Maps a Playwright Resource Timing object into the per-phase `NetworkInfo`
+ * timings. `total` is left at `-1` for the caller to fill via `calcTotalTime`
+ * once `loadEndTime`/`requestSentTime` are known. `receive` resolves to `-1`
+ * until `responseEnd` is available (browser journeys learn it on
+ * `requestfinished`); API journeys have the full timing up front.
+ */
+export function getResourceTimings(
+  rtiming: ResourceTiming
+): NetworkInfo['timings'] {
+  const blocked =
+    roundMilliSecs(
+      firstPositive([
+        rtiming.domainLookupStart,
+        rtiming.connectStart,
+        rtiming.requestStart,
+      ])
+    ) || -1;
+  const dns =
+    rtiming.domainLookupEnd !== -1
+      ? roundMilliSecs(rtiming.domainLookupEnd - rtiming.domainLookupStart)
+      : -1;
+  const connect =
+    rtiming.connectEnd !== -1
+      ? roundMilliSecs(rtiming.connectEnd - rtiming.connectStart)
+      : -1;
+  const ssl =
+    rtiming.secureConnectionStart !== -1
+      ? roundMilliSecs(rtiming.connectEnd - rtiming.secureConnectionStart)
+      : -1;
+  const wait =
+    rtiming.responseStart !== -1
+      ? roundMilliSecs(rtiming.responseStart - rtiming.requestStart)
+      : -1;
+  const receive =
+    rtiming.responseEnd !== -1
+      ? roundMilliSecs(rtiming.responseEnd - rtiming.responseStart)
+      : -1;
+
+  return {
+    blocked,
+    dns,
+    ssl,
+    connect,
+    send: 0, // not exposed via the Resource Timing API
+    wait,
+    receive,
+    total: -1,
+  };
+}
+
+/**
+ * Returns the `total` phase by summing the positive phases. Falls back to the
+ * wall-clock span between `requestSentTime` and `loadEndTime` when Resource
+ * Timing data is unavailable (`startTime <= 0`, e.g. HAR replay or aborted
+ * requests). Pure — the caller assigns the result onto `timings.total`.
+ */
+export function calcTotalTime(
+  entry: NetworkInfo,
+  rtiming: ResourceTiming
+): number {
+  if (rtiming.startTime <= 0) {
+    const end =
+      entry.loadEndTime || entry.responseReceivedTime || entry.requestSentTime;
+    const total = roundMilliSecs((end - entry.requestSentTime) * 1000);
+    return total <= 0 ? -1 : total;
+  }
+
+  const { timings } = entry;
+  return [
+    timings.blocked,
+    timings.dns,
+    timings.connect,
+    timings.wait,
+    timings.receive,
+  ].reduce((pre, cur) => ((cur || -1) > 0 ? cur + pre : pre), 0);
+}