@elastic/synthetics 1.24.4 → 1.26.0

package/src/reporters/json.ts

@@ -51,6 +51,7 @@ import {
   JourneyStartResult,
   StepEndResult,
   JourneyEndResult,
+  APIJourneyEndResult,
   PageMetrics,
 } from '../common_types';
 import { inspect } from 'util';
@@ -137,6 +138,25 @@ function getMetadata() {
   };
 }
 
+// ECS `server.ip`/`server.port`. Emitted for API journeys only; browser
+// output keeps the address under `http.response` to preserve its shape.
+function formatServer(response: NetworkInfo['response']) {
+  if (!response?.remoteIPAddress && !response?.remotePort) return undefined;
+  return {
+    ip: response.remoteIPAddress,
+    port: response.remotePort,
+  };
+}
+
+// Epoch seconds -> ISO-8601, tolerating missing/non-finite input. A
+// malformed cert date would otherwise throw `RangeError` and sink the
+// whole `journey/end` document (see json.test.ts regression).
+function epochToIso(epochSeconds: number | undefined): string | undefined {
+  if (epochSeconds == null || !Number.isFinite(epochSeconds)) return undefined;
+  const date = new Date(epochSeconds * 1000);
+  return Number.isNaN(date.getTime()) ? undefined : date.toISOString();
+}
+
 function formatTLS(tls: SecurityDetails) {
   if (!tls || !tls.protocol) {
     return;
@@ -151,8 +171,8 @@ function formatTLS(tls: SecurityDetails) {
         subject: {
           common_name: tls.subjectName,
         },
-        not_after: new Date(tls.validTo * 1000).toISOString(),
-        not_before: new Date(tls.validFrom * 1000).toISOString(),
+        not_after: epochToIso(tls.validTo),
+        not_before: epochToIso(tls.validFrom),
       },
     },
     version_protocol: name,
@@ -208,6 +228,7 @@ export function formatNetworkFields(network: NetworkInfo) {
       response,
     },
     tls: formatTLS(response?.securityDetails),
+    ...(browser?.name === 'api' && { server: formatServer(response) }),
   };
 
   const pickItems: Array<keyof NetworkInfo> = [
@@ -257,10 +278,15 @@ function journeyInfo(journey: Partial<Journey>, type: OutputFields['type']) {
   if (!journey) {
     return;
   }
+  // Surface non-default journey types (e.g. `api`) for downstream routing;
+  // browser output omits the field to stay byte-compatible.
+  const journeyType =
+    journey.type && journey.type !== 'browser' ? journey.type : undefined;
   const info: JourneyInfo = {
     name: journey.name,
     id: journey.id,
     tags: journey.tags,
+    ...(journeyType ? { type: journeyType } : {}),
   };
   const isEnd = type === 'journey/end';
   if (isEnd) {
@@ -439,40 +465,42 @@ export default class JSONReporter extends BaseReporter {
 
   override async onJourneyEnd(
     journey: Journey,
-    {
-      timestamp,
-      browserDelay,
-      networkinfo,
-      browserconsole,
-      options,
-    }: JourneyEndResult
+    result: JourneyEndResult | APIJourneyEndResult
   ) {
-    const { ssblocks, screenshots } = options;
-    const writeScreenshots =
-      screenshots === 'on' ||
-      (screenshots === 'only-on-failure' && journey.status === 'failed');
-    if (writeScreenshots) {
-      await gatherScreenshots(
-        join(CACHE_PATH, 'screenshots'),
-        async screenshot => {
-          const { data, timestamp, step } = screenshot;
-          if (!data) {
-            return;
-          }
-          if (ssblocks) {
-            await this.writeScreenshotBlocks(journey, screenshot);
-          } else {
-            this.writeJSON({
-              type: 'step/screenshot',
-              timestamp,
-              journey,
-              step,
-              blob: data,
-              blob_mime: 'image/jpeg',
-            });
+    const { timestamp, networkinfo, options } = result;
+    const isAPIJourney = journey.type === 'api';
+    // Browser-only fields; absent for API journeys.
+    const browserDelay = (result as JourneyEndResult).browserDelay;
+    const browserconsole = (result as JourneyEndResult).browserconsole;
+
+    if (!isAPIJourney) {
+      const { ssblocks, screenshots } = options;
+      const writeScreenshots =
+        screenshots === 'on' ||
+        (screenshots === 'only-on-failure' && journey.status === 'failed');
+      if (writeScreenshots) {
+        await gatherScreenshots(
+          join(CACHE_PATH, 'screenshots'),
+          async screenshot => {
+            const { data, timestamp, step } = screenshot;
+            if (!data) {
+              return;
+            }
+            if (ssblocks) {
+              await this.writeScreenshotBlocks(journey, screenshot);
+            } else {
+              this.writeJSON({
+                type: 'step/screenshot',
+                timestamp,
+                journey,
+                step,
+                blob: data,
+                blob_mime: 'image/jpeg',
+              });
+            }
           }
-        }
-      );
+        );
+      }
     }
 
     if (networkinfo) {
@@ -504,18 +532,23 @@ export default class JSONReporter extends BaseReporter {
       });
     }
 
+    const endPayload: Payload = {
+      status: journey.status,
+      // Omit `browser_delay_us` for API journeys where it has no meaning;
+      // key order preserves the existing browser wire shape.
+      ...(isAPIJourney
+        ? {}
+        : { browser_delay_us: getDurationInUs(browserDelay) }),
+      // timestamp in microseconds at which the current node process began, measured in Unix time.
+      process_startup_epoch_us: Math.trunc(processStart * 1000),
+    };
+
     this.writeJSON({
       type: 'journey/end',
       journey,
       timestamp,
       error: journey.error,
-      payload: {
-        status: journey.status,
-        // convert from monotonic seconds time to microseconds
-        browser_delay_us: getDurationInUs(browserDelay),
-        // timestamp in microseconds at which the current node process began, measured in Unix time.
-        process_startup_epoch_us: Math.trunc(processStart * 1000),
-      },
+      payload: endPayload,
     });
   }
 

package/templates/README.md

@@ -9,7 +9,9 @@ You can always use this command to scafold new Synthetics projects.
 Key places to look:
 
 - The `synthetics.config.ts` file contains configuration for your project.
-- The `journeys` directory contains both basic and more advanced examples of using synthetics. It tests a publicly hosted [Todos List](https://elastic.github.io/synthetics-demo/).
+- The `journeys` directory contains both basic and more advanced examples of using synthetics:
+  - `example.journey.ts` and `advanced-example.journey.ts` are **browser journeys** that drive Chromium against a publicly hosted [Todos List](https://elastic.github.io/synthetics-demo/).
+  - `api-example.journey.ts` and `advanced-api-example.journey.ts` are **API journeys** that run without a browser, hitting [jsonplaceholder.typicode.com](https://jsonplaceholder.typicode.com) for a quick, runnable demonstration of multi-step API monitoring. Use these for OAuth-protected endpoints, multi-step API flows, and high-frequency lightweight checks.
 - The `.github` directory contains an example github action, demonstrating the use of a CI service for automatically running tests on merges and PR creation.
 
 To run the tests locally, use the following command:

package/templates/journeys/advanced-api-example-helpers.ts

@@ -0,0 +1,79 @@
+import {
+  step,
+  APIRequestContext,
+  APIResponse,
+  expect,
+} from '@elastic/synthetics';
+
+// Helpers for `advanced-api-example.journey.ts` — same idea as
+// `advanced-example-helpers.ts` for browser journeys, but operating on
+// `APIRequestContext` instead of `Page`. Wrapping each call in a `step`
+// gives you per-request timing, status, and error attribution in the
+// reporter output.
+
+/**
+ * Generic "assert this call returns the expected status" wrapper. Useful
+ * when a step is just a single request with a known good status code
+ * and you don't need to inspect the body.
+ */
+export const expectStatusStep = (
+  name: string,
+  call: () => Promise<APIResponse>,
+  expectedStatus = 200
+) => {
+  step(name, async () => {
+    const res = await call();
+    expect(res.status()).toBe(expectedStatus);
+  });
+};
+
+export const listTodosStep = (
+  request: APIRequestContext,
+  apiUrl: string,
+  state: { ids: number[] }
+) => {
+  step('list todos', async () => {
+    const res = await request.get(`${apiUrl}/todos?_limit=5`);
+    expect(res.status()).toBe(200);
+    const todos: Array<{ id: number }> = await res.json();
+    expect(todos.length).toBeGreaterThan(0);
+    state.ids = todos.map(t => t.id);
+  });
+};
+
+export const createTodoStep = (
+  request: APIRequestContext,
+  apiUrl: string,
+  title: string,
+  state: { createdId?: number }
+) => {
+  step(`create todo "${title}"`, async () => {
+    const res = await request.post(`${apiUrl}/todos`, {
+      data: { title, completed: false, userId: 1 },
+    });
+    expect(res.status()).toBe(201);
+    const created = await res.json();
+    expect(created).toMatchObject({ title, completed: false });
+    state.createdId = created.id;
+  });
+};
+
+/**
+ * Delete a todo whose id is produced by an earlier step. The id is
+ * supplied as a thunk so the step builder can be registered up-front
+ * but resolve the actual id lazily, at execution time, after the
+ * earlier step has populated state.
+ */
+export const deleteTodoStep = (
+  request: APIRequestContext,
+  apiUrl: string,
+  getId: () => number | undefined
+) => {
+  step('delete created todo', async () => {
+    const id = getId();
+    if (id == null) return; // earlier step didn't produce an id; skip silently
+    const res = await request.delete(`${apiUrl}/todos/${id}`);
+    // jsonplaceholder returns 200 for DELETE; real APIs typically 204.
+    expect([200, 204]).toContain(res.status());
+  });
+};

package/templates/journeys/advanced-api-example.journey.ts

@@ -0,0 +1,52 @@
+import { apiJourney, monitor, step, expect } from '@elastic/synthetics';
+import {
+  listTodosStep,
+  createTodoStep,
+  deleteTodoStep,
+} from './advanced-api-example-helpers';
+
+// This file demonstrates the recommended shape for non-trivial API
+// monitors: small, named, reusable step builders, with shared state
+// passed by reference between steps so later steps can act on data
+// produced by earlier ones (e.g. a token from `/auth`, an id from
+// `/create`, etc.).
+//
+// Each step gets its own entry in the reporter output, so you get
+// per-request status, latency, and (for HTTPS) TLS / remote-address
+// telemetry — same as a browser journey's network waterfall.
+//
+// Note on execution order: the journey callback below runs once at
+// *registration* time and every `step(...)` call enqueues a step body
+// that executes later, in order. We register all steps unconditionally
+// at the top level and read `state` only inside step bodies — by the
+// time a step body runs, the steps before it have already populated
+// the shared object. If any prerequisite step fails, the runner skips
+// the rest of the journey, so guards inside later steps are kept
+// minimal.
+
+apiJourney('todos API: list and round-trip a todo', ({ request, params }) => {
+  monitor.use({
+    id: 'todos-api-roundtrip',
+    schedule: 10,
+    tags: ['api', 'todos'],
+  });
+
+  // Shared state populated by earlier steps and consumed by later ones.
+  const state: { ids: number[]; createdId?: number } = { ids: [] };
+
+  listTodosStep(request, params.apiUrl, state);
+  createTodoStep(request, params.apiUrl, 'synthetic check', state);
+
+  // Inline step that reads `state` populated by `listTodosStep`. The
+  // body runs after the previous steps have completed, so by this
+  // point `state.ids` is populated.
+  step('fetch first todo from list', async () => {
+    expect(state.ids.length).toBeGreaterThan(0);
+    const id = state.ids[0];
+    const res = await request.get(`${params.apiUrl}/todos/${id}`);
+    expect(res.status()).toBe(200);
+    expect((await res.json()).id).toBe(id);
+  });
+
+  deleteTodoStep(request, params.apiUrl, () => state.createdId);
+});

package/templates/journeys/api-example.journey.ts

@@ -0,0 +1,35 @@
+import { apiJourney, monitor, step, expect } from '@elastic/synthetics';
+
+// API journeys run without launching a browser — they only use
+// Playwright's APIRequestContext to hit HTTP endpoints. They are pushed
+// to Kibana as HTTP-type monitors and are a good fit for OAuth-protected
+// endpoints, multi-step API flows, and lightweight high-frequency checks.
+//
+// `params.apiUrl` is sourced from `synthetics.config.ts` and points at
+// the jsonplaceholder.typicode.com demo API by default; override it for
+// your own service via `--params '{"apiUrl":"..."}'` or per-environment
+// in the config file.
+
+apiJourney('My Example API Journey', ({ request, params }) => {
+  // Only relevant for the push command to create
+  // monitors in Kibana
+  monitor.use({
+    id: 'example-api-monitor',
+    schedule: 10,
+  });
+
+  step('list todos', async () => {
+    const res = await request.get(`${params.apiUrl}/todos`);
+    expect(res.status()).toBe(200);
+    const todos = await res.json();
+    expect(Array.isArray(todos)).toBe(true);
+    expect(todos.length).toBeGreaterThan(0);
+  });
+
+  step('fetch a single todo', async () => {
+    const res = await request.get(`${params.apiUrl}/todos/1`);
+    expect(res.status()).toBe(200);
+    const todo = await res.json();
+    expect(todo).toMatchObject({ id: 1, userId: expect.any(Number) });
+  });
+});

package/templates/synthetics.config.ts

@@ -4,6 +4,8 @@ export default env => {
   const config: SyntheticsConfig = {
     params: {
       url: 'https://elastic.github.io/synthetics-demo/',
+      // Base URL for the API journey examples; replace with your service.
+      apiUrl: 'https://jsonplaceholder.typicode.com',
     },
     playwrightOptions: {
       ignoreHTTPSErrors: false,

package/.husky/install.mjs

@@ -1,7 +0,0 @@
-// Skip if husky is not installed (CI, production, embedded installs with --omit=dev)
-try {
-  const husky = await import('husky');
-  husky.default();
-} catch (e) {
-  if (e.code !== 'ERR_MODULE_NOT_FOUND') throw e;
-}