@elastic/synthetics 1.24.4 → 1.26.0

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/dsl/monitor.ts

@@ -32,6 +32,7 @@ import {
   ScreenshotOptions,
   Params,
   PlaywrightOptions,
+  CertificateErrorSpkiAllowlist,
 } from '../common_types';
 import { indent, isMatch } from '../helpers';
 import { LocationsMap } from '../locations/public-locations';
@@ -72,6 +73,7 @@ export type MonitorConfig = {
   screenshot?: ScreenshotOptions;
   params?: Params;
   playwrightOptions?: PlaywrightOptions;
+  certificateErrorSpkiAllowlist?: CertificateErrorSpkiAllowlist;
   alert?: AlertConfig;
   /**
    * By default, the monitor will be retested on failure

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

package/src/options.ts

@@ -28,6 +28,7 @@ import { createOption } from 'commander';
 import { readConfig } from './config';
 import type { CliArgs, RunOptions } from './common_types';
 import { isFile, THROTTLING_WARNING_MSG, warn } from './helpers';
+import { normalizeCertificateErrorSpkiAllowlist } from './core/certs';
 import { readFileSync } from 'fs';
 
 type Mode = 'run' | 'push';
@@ -103,6 +104,24 @@ export async function normalizeOptions(
     merge(config?.proxy ?? {}, cliArgs?.proxy || {})
   );
 
+  /**
+   * Merge PEM certificates from the Synthetics config and the CLI. Each entry
+   * can be inline PEM content or a path to a PEM file that we resolve here so
+   * downstream consumers only ever deal with PEM strings used to build the
+   * Chromium SPKI certificate-error allowlist.
+   */
+  const certificateErrorSpkiAllowlist = [
+    ...normalizeCertificateErrorSpkiAllowlist(
+      config.certificateErrorSpkiAllowlist
+    ),
+    ...normalizeCertificateErrorSpkiAllowlist(
+      cliArgs.certificateErrorSpkiAllowlist
+    ),
+  ].map(entry => (isFile(entry) ? readFileSync(entry, 'utf-8') : entry));
+  options.certificateErrorSpkiAllowlist = certificateErrorSpkiAllowlist.length
+    ? certificateErrorSpkiAllowlist
+    : undefined;
+
   /**
    * Merge default options based on the mode of operation whether we are running tests locally
    * or pushing the project monitors
@@ -265,6 +284,11 @@ export function getCommonCommandOpts() {
     "List of Kibana's Maintenance Windows IDs assigned by default. More information on https://www.elastic.co/docs/explore-analyze/alerts-cases/alerts/maintenance-windows."
   );
 
+  const certificateErrorSpkiAllowlist = createOption(
+    '--certificate-error-spki-allowlist <pathOrPem...>',
+    "One or more PEM certificates, each provided as inline content or a path to a PEM file. Their SPKI hashes are used to bypass Chromium certificate errors for matching presented certificates; this does not add a CA to Chromium's trust store."
+  );
+
   return {
     auth,
     authMandatory,
@@ -276,6 +300,7 @@ export function getCommonCommandOpts() {
     match,
     fields,
     maintenanceWindows,
+    certificateErrorSpkiAllowlist,
   };
 }