@oneuptime/common 12.0.13 → 12.0.15

package/Tests/Types/Monitor/IncomingMonitorDefaultCriteria.test.ts

@@ -0,0 +1,470 @@
+import FilterCondition from "../../../Types/Filter/FilterCondition";
+import {
+  CheckOn,
+  CriteriaFilter,
+  FilterType,
+} from "../../../Types/Monitor/CriteriaFilter";
+import MonitorCriteria from "../../../Types/Monitor/MonitorCriteria";
+import MonitorCriteriaInstance from "../../../Types/Monitor/MonitorCriteriaInstance";
+import MonitorType from "../../../Types/Monitor/MonitorType";
+import ObjectID from "../../../Types/ObjectID";
+
+/*
+ * Incoming Request and Incoming Email monitors are push-driven: the sender
+ * decides when data arrives and what it says. Their out-of-the-box criteria
+ * therefore read the payload body rather than the arrival clock:
+ *
+ *   offline -> body CONTAINS "error"
+ *   online  -> body DOES NOT CONTAIN "error"
+ *
+ * These tests pin that contract down (shape, wiring, incident/alert
+ * templates, validation, serialization) so the defaults cannot silently
+ * drift back to the old "received in the last 30 minutes" heartbeat check.
+ */
+
+const ONLINE_STATUS_ID: ObjectID = new ObjectID("100000000000000000000011");
+const OFFLINE_STATUS_ID: ObjectID = new ObjectID("100000000000000000000012");
+const INCIDENT_SEVERITY_ID: ObjectID = new ObjectID("100000000000000000000013");
+const ALERT_SEVERITY_ID: ObjectID = new ObjectID("100000000000000000000014");
+
+const KEYWORD: string =
+  MonitorCriteriaInstance.DEFAULT_INCOMING_BODY_ERROR_KEYWORD;
+
+interface IncomingMonitorCase {
+  label: string;
+  monitorType: MonitorType;
+  bodyCheckOn: CheckOn;
+  // How the body is named in the human-readable copy.
+  bodyLabel: string;
+  // The check the defaults deliberately no longer use.
+  retiredCheckOn: CheckOn;
+}
+
+const CASES: Array<IncomingMonitorCase> = [
+  {
+    label: "Incoming Request",
+    monitorType: MonitorType.IncomingRequest,
+    bodyCheckOn: CheckOn.RequestBody,
+    bodyLabel: "request body",
+    retiredCheckOn: CheckOn.IncomingRequest,
+  },
+  {
+    label: "Incoming Email",
+    monitorType: MonitorType.IncomingEmail,
+    bodyCheckOn: CheckOn.EmailBody,
+    bodyLabel: "email body",
+    retiredCheckOn: CheckOn.EmailReceivedAt,
+  },
+];
+
+function buildOnline(
+  testCase: IncomingMonitorCase,
+  monitorName: string = "Payments API",
+): MonitorCriteriaInstance {
+  const instance: MonitorCriteriaInstance | null =
+    MonitorCriteriaInstance.getDefaultOnlineMonitorCriteriaInstance({
+      monitorType: testCase.monitorType,
+      monitorStatusId: ONLINE_STATUS_ID,
+      monitorName: monitorName,
+    });
+
+  if (!instance) {
+    throw new Error(`${testCase.label} has no default online criteria`);
+  }
+
+  return instance;
+}
+
+function buildOffline(
+  testCase: IncomingMonitorCase,
+  monitorName: string = "Payments API",
+): MonitorCriteriaInstance {
+  return MonitorCriteriaInstance.getDefaultOfflineMonitorCriteriaInstance({
+    monitorType: testCase.monitorType,
+    monitorStatusId: OFFLINE_STATUS_ID,
+    incidentSeverityId: INCIDENT_SEVERITY_ID,
+    alertSeverityId: ALERT_SEVERITY_ID,
+    monitorName: monitorName,
+  });
+}
+
+describe("Incoming monitor default criteria", () => {
+  describe("DEFAULT_INCOMING_BODY_ERROR_KEYWORD", () => {
+    test('is the lower-cased word "error"', () => {
+      expect(KEYWORD).toBe("error");
+    });
+  });
+
+  describe.each(CASES)(
+    "$label monitor",
+    (testCase: IncomingMonitorCase): void => {
+      describe("online criteria", () => {
+        test(`checks that the ${testCase.bodyLabel} does not contain the error keyword`, () => {
+          const instance: MonitorCriteriaInstance = buildOnline(testCase);
+
+          expect(instance.data?.filters).toHaveLength(1);
+
+          const filter: CriteriaFilter = instance.data!.filters[0]!;
+
+          expect(filter.checkOn).toBe(testCase.bodyCheckOn);
+          expect(filter.filterType).toBe(FilterType.NotContains);
+          expect(filter.value).toBe(KEYWORD);
+        });
+
+        test("no longer checks the arrival clock", () => {
+          const instance: MonitorCriteriaInstance = buildOnline(testCase);
+
+          const checkOns: Array<CheckOn> = instance.data!.filters.map(
+            (filter: CriteriaFilter) => {
+              return filter.checkOn;
+            },
+          );
+
+          expect(checkOns).not.toContain(testCase.retiredCheckOn);
+
+          const filterTypes: Array<FilterType | undefined> =
+            instance.data!.filters.map((filter: CriteriaFilter) => {
+              return filter.filterType;
+            });
+
+          expect(filterTypes).not.toContain(FilterType.RecievedInMinutes);
+          expect(filterTypes).not.toContain(FilterType.NotRecievedInMinutes);
+        });
+
+        test("flips the monitor status but never opens incidents or alerts", () => {
+          const instance: MonitorCriteriaInstance = buildOnline(testCase);
+
+          expect(instance.data?.changeMonitorStatus).toBe(true);
+          expect(instance.data?.createIncidents).toBe(false);
+          expect(instance.data?.createAlerts).toBe(false);
+          expect(instance.data?.incidents).toEqual([]);
+          expect(instance.data?.alerts).toEqual([]);
+        });
+
+        test("points at the online monitor status and uses an All filter condition", () => {
+          const instance: MonitorCriteriaInstance = buildOnline(testCase);
+
+          expect(instance.data?.monitorStatusId?.toString()).toBe(
+            ONLINE_STATUS_ID.toString(),
+          );
+          expect(instance.data?.filterCondition).toBe(FilterCondition.All);
+        });
+
+        test("names itself after the monitor and explains the body check", () => {
+          const instance: MonitorCriteriaInstance = buildOnline(
+            testCase,
+            "Checkout Webhook",
+          );
+
+          expect(instance.data?.name).toBe(
+            "Check if Checkout Webhook is online",
+          );
+          expect(instance.data?.description).toContain(testCase.bodyLabel);
+          expect(instance.data?.description).toContain("does not contain");
+          expect(instance.data?.description).toContain(KEYWORD);
+        });
+
+        test("gets a fresh id on every call", () => {
+          const first: MonitorCriteriaInstance = buildOnline(testCase);
+          const second: MonitorCriteriaInstance = buildOnline(testCase);
+
+          expect(first.data?.id).toBeTruthy();
+          expect(first.data?.id).not.toBe(second.data?.id);
+        });
+      });
+
+      describe("offline criteria", () => {
+        test(`checks that the ${testCase.bodyLabel} contains the error keyword`, () => {
+          const instance: MonitorCriteriaInstance = buildOffline(testCase);
+
+          expect(instance.data?.filters).toHaveLength(1);
+
+          const filter: CriteriaFilter = instance.data!.filters[0]!;
+
+          expect(filter.checkOn).toBe(testCase.bodyCheckOn);
+          expect(filter.filterType).toBe(FilterType.Contains);
+          expect(filter.value).toBe(KEYWORD);
+        });
+
+        test("no longer checks the arrival clock", () => {
+          const instance: MonitorCriteriaInstance = buildOffline(testCase);
+
+          const checkOns: Array<CheckOn> = instance.data!.filters.map(
+            (filter: CriteriaFilter) => {
+              return filter.checkOn;
+            },
+          );
+
+          expect(checkOns).not.toContain(testCase.retiredCheckOn);
+
+          const filterTypes: Array<FilterType | undefined> =
+            instance.data!.filters.map((filter: CriteriaFilter) => {
+              return filter.filterType;
+            });
+
+          expect(filterTypes).not.toContain(FilterType.NotRecievedInMinutes);
+          expect(filterTypes).not.toContain(FilterType.RecievedInMinutes);
+        });
+
+        test("opens an auto-resolving incident with the configured severity", () => {
+          const instance: MonitorCriteriaInstance = buildOffline(
+            testCase,
+            "Checkout Webhook",
+          );
+
+          expect(instance.data?.createIncidents).toBe(true);
+          expect(instance.data?.incidents).toHaveLength(1);
+
+          const incident: NonNullable<
+            typeof instance.data
+          >["incidents"][number] = instance.data!.incidents[0]!;
+
+          expect(incident.title).toBe("Checkout Webhook is offline");
+          expect(incident.autoResolveIncident).toBe(true);
+          expect(incident.incidentSeverityId?.toString()).toBe(
+            INCIDENT_SEVERITY_ID.toString(),
+          );
+          expect(incident.onCallPolicyIds).toEqual([]);
+          expect(incident.description).toContain(testCase.bodyLabel);
+          expect(incident.description).toContain(KEYWORD);
+        });
+
+        test("ships an alert template that stays switched off by default", () => {
+          const instance: MonitorCriteriaInstance = buildOffline(
+            testCase,
+            "Checkout Webhook",
+          );
+
+          expect(instance.data?.createAlerts).toBe(false);
+          expect(instance.data?.alerts).toHaveLength(1);
+
+          const alert: NonNullable<typeof instance.data>["alerts"][number] =
+            instance.data!.alerts[0]!;
+
+          expect(alert.title).toBe("Checkout Webhook is offline");
+          expect(alert.autoResolveAlert).toBe(true);
+          expect(alert.alertSeverityId?.toString()).toBe(
+            ALERT_SEVERITY_ID.toString(),
+          );
+          expect(alert.description).toContain(testCase.bodyLabel);
+          expect(alert.description).toContain(KEYWORD);
+        });
+
+        test("does not claim that nothing was received", () => {
+          const instance: MonitorCriteriaInstance = buildOffline(testCase);
+
+          expect(instance.data?.incidents[0]?.description).not.toContain(
+            "No email received",
+          );
+          expect(instance.data?.alerts[0]?.description).not.toContain(
+            "No email received",
+          );
+        });
+
+        test("points at the offline monitor status and uses an Any filter condition", () => {
+          const instance: MonitorCriteriaInstance = buildOffline(testCase);
+
+          expect(instance.data?.monitorStatusId?.toString()).toBe(
+            OFFLINE_STATUS_ID.toString(),
+          );
+          expect(instance.data?.filterCondition).toBe(FilterCondition.Any);
+          expect(instance.data?.changeMonitorStatus).toBe(true);
+        });
+
+        test("names itself after the monitor and explains the body check", () => {
+          const instance: MonitorCriteriaInstance = buildOffline(
+            testCase,
+            "Checkout Webhook",
+          );
+
+          expect(instance.data?.name).toBe(
+            "Check if Checkout Webhook is offline",
+          );
+          expect(instance.data?.description).toContain(testCase.bodyLabel);
+          expect(instance.data?.description).toContain("contains");
+          expect(instance.data?.description).toContain(KEYWORD);
+        });
+      });
+
+      describe("online and offline together", () => {
+        test("are exact complements of each other", () => {
+          const online: CriteriaFilter =
+            buildOnline(testCase).data!.filters[0]!;
+          const offline: CriteriaFilter =
+            buildOffline(testCase).data!.filters[0]!;
+
+          expect(online.checkOn).toBe(offline.checkOn);
+          expect(online.value).toBe(offline.value);
+          expect(online.filterType).toBe(FilterType.NotContains);
+          expect(offline.filterType).toBe(FilterType.Contains);
+        });
+
+        test("target different monitor statuses", () => {
+          expect(
+            buildOnline(testCase).data?.monitorStatusId?.toString(),
+          ).not.toBe(buildOffline(testCase).data?.monitorStatusId?.toString());
+        });
+
+        test("neither evaluates over a time window", () => {
+          for (const instance of [
+            buildOnline(testCase),
+            buildOffline(testCase),
+          ]) {
+            for (const filter of instance.data!.filters) {
+              expect(filter.evaluateOverTime).toBeFalsy();
+              expect(filter.evaluateOverTimeOptions).toBeUndefined();
+            }
+          }
+        });
+      });
+
+      describe("validation", () => {
+        test("the online criteria is valid", () => {
+          expect(
+            MonitorCriteriaInstance.getValidationError(
+              buildOnline(testCase),
+              testCase.monitorType,
+            ),
+          ).toBeNull();
+        });
+
+        test("the offline criteria is valid", () => {
+          expect(
+            MonitorCriteriaInstance.getValidationError(
+              buildOffline(testCase),
+              testCase.monitorType,
+            ),
+          ).toBeNull();
+        });
+
+        /*
+         * Contains / Not Contains are value-carrying filter types, so an
+         * empty default would trip getValidationError the moment a user
+         * opened the monitor form. Guard the keyword against being emptied.
+         */
+        test("a blank keyword would fail validation - so the default must not be blank", () => {
+          const instance: MonitorCriteriaInstance = buildOnline(testCase);
+          instance.data!.filters[0]!.value = "";
+
+          expect(
+            MonitorCriteriaInstance.getValidationError(
+              instance,
+              testCase.monitorType,
+            ),
+          ).toContain("Value is required");
+          expect(KEYWORD).not.toBe("");
+        });
+      });
+
+      describe("serialization", () => {
+        test("survives a toJSON / fromJSON round-trip", () => {
+          const original: MonitorCriteriaInstance = buildOffline(testCase);
+          const restored: MonitorCriteriaInstance =
+            MonitorCriteriaInstance.fromJSON(original.toJSON());
+
+          expect(restored.data?.filters[0]?.checkOn).toBe(testCase.bodyCheckOn);
+          expect(restored.data?.filters[0]?.filterType).toBe(
+            FilterType.Contains,
+          );
+          expect(restored.data?.filters[0]?.value).toBe(KEYWORD);
+          expect(restored.data?.filterCondition).toBe(FilterCondition.Any);
+        });
+
+        test("clone() is a deep copy of the body filter", () => {
+          const original: MonitorCriteriaInstance = buildOnline(testCase);
+          const clone: MonitorCriteriaInstance =
+            MonitorCriteriaInstance.clone(original);
+
+          clone.data!.filters[0]!.value = "mutated";
+
+          expect(original.data?.filters[0]?.value).toBe(KEYWORD);
+        });
+      });
+
+      describe("MonitorCriteria.getDefaultMonitorCriteria", () => {
+        test("composes the offline body check first and the online body check second", () => {
+          const criteria: MonitorCriteria =
+            MonitorCriteria.getDefaultMonitorCriteria({
+              monitorType: testCase.monitorType,
+              monitorName: "Payments API",
+              onlineMonitorStatusId: ONLINE_STATUS_ID,
+              offlineMonitorStatusId: OFFLINE_STATUS_ID,
+              defaultIncidentSeverityId: INCIDENT_SEVERITY_ID,
+              defaultAlertSeverityId: ALERT_SEVERITY_ID,
+            });
+
+          const instances: Array<MonitorCriteriaInstance> =
+            criteria.data!.monitorCriteriaInstanceArray;
+
+          expect(instances).toHaveLength(2);
+
+          expect(instances[0]?.data?.filters[0]?.checkOn).toBe(
+            testCase.bodyCheckOn,
+          );
+          expect(instances[0]?.data?.filters[0]?.filterType).toBe(
+            FilterType.Contains,
+          );
+          expect(instances[0]?.data?.monitorStatusId?.toString()).toBe(
+            OFFLINE_STATUS_ID.toString(),
+          );
+
+          expect(instances[1]?.data?.filters[0]?.checkOn).toBe(
+            testCase.bodyCheckOn,
+          );
+          expect(instances[1]?.data?.filters[0]?.filterType).toBe(
+            FilterType.NotContains,
+          );
+          expect(instances[1]?.data?.monitorStatusId?.toString()).toBe(
+            ONLINE_STATUS_ID.toString(),
+          );
+        });
+
+        test("passes validation as a whole", () => {
+          const criteria: MonitorCriteria =
+            MonitorCriteria.getDefaultMonitorCriteria({
+              monitorType: testCase.monitorType,
+              monitorName: "Payments API",
+              onlineMonitorStatusId: ONLINE_STATUS_ID,
+              offlineMonitorStatusId: OFFLINE_STATUS_ID,
+              defaultIncidentSeverityId: INCIDENT_SEVERITY_ID,
+              defaultAlertSeverityId: ALERT_SEVERITY_ID,
+            });
+
+          expect(
+            MonitorCriteria.getValidationError(criteria, testCase.monitorType),
+          ).toBeNull();
+        });
+      });
+    },
+  );
+
+  /*
+   * The two incoming monitor types now share a shape but must not share
+   * a CheckOn - an email monitor reading "Request Body" would evaluate
+   * nothing at all.
+   */
+  test("each incoming monitor type reads its own body field", () => {
+    const requestOnline: MonitorCriteriaInstance = buildOnline(CASES[0]!);
+    const emailOnline: MonitorCriteriaInstance = buildOnline(CASES[1]!);
+
+    expect(requestOnline.data?.filters[0]?.checkOn).toBe(CheckOn.RequestBody);
+    expect(emailOnline.data?.filters[0]?.checkOn).toBe(CheckOn.EmailBody);
+  });
+
+  /*
+   * Other push-driven monitor types are untouched by this change; a
+   * regression there would be easy to miss because they share the same
+   * builder.
+   */
+  test("does not change the Ping defaults", () => {
+    const online: MonitorCriteriaInstance | null =
+      MonitorCriteriaInstance.getDefaultOnlineMonitorCriteriaInstance({
+        monitorType: MonitorType.Ping,
+        monitorStatusId: ONLINE_STATUS_ID,
+        monitorName: "Gateway",
+      });
+
+    expect(online?.data?.filters[0]?.checkOn).toBe(CheckOn.IsOnline);
+    expect(online?.data?.filters[0]?.filterType).toBe(FilterType.True);
+  });
+});

package/Tests/Types/Monitor/MonitorCriteriaInstance.test.ts

@@ -108,7 +108,7 @@ describe("MonitorCriteriaInstance", () => {
       );
     });
 
-    test("IncomingRequest monitor uses a RecievedInMinutes filter", () => {
+    test("IncomingRequest monitor is online while the request body carries no error", () => {
       const instance: MonitorCriteriaInstance | null =
         MonitorCriteriaInstance.getDefaultOnlineMonitorCriteriaInstance({
           monitorType: MonitorType.IncomingRequest,
@@ -116,11 +116,13 @@ describe("MonitorCriteriaInstance", () => {
           monitorName: "Heartbeat",
         });
       expect(instance).not.toBeNull();
-      expect(instance?.data?.filters[0]?.checkOn).toBe(CheckOn.IncomingRequest);
+      expect(instance?.data?.filters[0]?.checkOn).toBe(CheckOn.RequestBody);
       expect(instance?.data?.filters[0]?.filterType).toBe(
-        FilterType.RecievedInMinutes,
+        FilterType.NotContains,
+      );
+      expect(instance?.data?.filters[0]?.value).toBe(
+        MonitorCriteriaInstance.DEFAULT_INCOMING_BODY_ERROR_KEYWORD,
       );
-      expect(instance?.data?.filters[0]?.value).toBe(30);
     });
 
     test("Metrics monitor threads the first metric alias into options", () => {

package/Tests/Types/Monitor/MonitorStepConfigHelpers.test.ts

@@ -0,0 +1,165 @@
+import {
+  DEFAULT_MONITOR_REQUEST_TIMEOUT_IN_MS,
+  MAX_MONITOR_REQUEST_TIMEOUT_IN_MS,
+  clampMonitorRequestTimeoutInMs,
+} from "../../../Types/Monitor/MonitorStep";
+import { describe, expect, test } from "@jest/globals";
+
+/*
+ * clampMonitorRequestTimeoutInMs constrains a per-step request timeout to the
+ * range the probe accepts. It has three decision points:
+ *   1. a falsy value (0 / NaN and, defensively, null / undefined) -> DEFAULT
+ *   2. a non-positive value (value <= 0) -> DEFAULT
+ *   3. a value above the cap (value > MAX) -> MAX
+ * anything else passes through unchanged. These tests walk each branch, both
+ * boundaries and the defensive coercions the callers can hand it.
+ *
+ * Note: with the current config DEFAULT and MAX happen to share the value
+ * 60000, so every assertion checks the constant that names the branch under
+ * test rather than the bare number, keeping the intent readable even if the
+ * two constants diverge later.
+ */
+
+describe("clampMonitorRequestTimeoutInMs", () => {
+  describe("invalid / non-positive inputs fall back to the default", () => {
+    test("zero returns the default (caught by the falsy check)", () => {
+      const result: number = clampMonitorRequestTimeoutInMs(0);
+      expect(result).toBe(DEFAULT_MONITOR_REQUEST_TIMEOUT_IN_MS);
+    });
+
+    test("negative zero returns the default", () => {
+      const result: number = clampMonitorRequestTimeoutInMs(-0);
+      expect(result).toBe(DEFAULT_MONITOR_REQUEST_TIMEOUT_IN_MS);
+    });
+
+    test("NaN returns the default (NaN is falsy)", () => {
+      const result: number = clampMonitorRequestTimeoutInMs(NaN);
+      expect(result).toBe(DEFAULT_MONITOR_REQUEST_TIMEOUT_IN_MS);
+    });
+
+    test("a small negative value returns the default (value <= 0 branch)", () => {
+      const result: number = clampMonitorRequestTimeoutInMs(-1);
+      expect(result).toBe(DEFAULT_MONITOR_REQUEST_TIMEOUT_IN_MS);
+    });
+
+    test("a negative fraction returns the default", () => {
+      const result: number = clampMonitorRequestTimeoutInMs(-0.5);
+      expect(result).toBe(DEFAULT_MONITOR_REQUEST_TIMEOUT_IN_MS);
+    });
+
+    test("a large negative value returns the default, not a clamp", () => {
+      const result: number = clampMonitorRequestTimeoutInMs(-999999);
+      expect(result).toBe(DEFAULT_MONITOR_REQUEST_TIMEOUT_IN_MS);
+    });
+
+    test("negative Infinity returns the default", () => {
+      const result: number = clampMonitorRequestTimeoutInMs(-Infinity);
+      expect(result).toBe(DEFAULT_MONITOR_REQUEST_TIMEOUT_IN_MS);
+    });
+
+    /*
+     * The signature is typed as number, but real callers (JSON / DB rows,
+     * loosely typed UI state) can hand it a missing value. The falsy guard is
+     * what protects the probe here, so exercise it explicitly.
+     */
+    test("undefined coerced through the signature returns the default", () => {
+      const result: number = clampMonitorRequestTimeoutInMs(
+        undefined as unknown as number,
+      );
+      expect(result).toBe(DEFAULT_MONITOR_REQUEST_TIMEOUT_IN_MS);
+    });
+
+    test("null coerced through the signature returns the default", () => {
+      const result: number = clampMonitorRequestTimeoutInMs(
+        null as unknown as number,
+      );
+      expect(result).toBe(DEFAULT_MONITOR_REQUEST_TIMEOUT_IN_MS);
+    });
+  });
+
+  describe("in-range values pass through unchanged", () => {
+    test("the smallest positive integer is returned as-is", () => {
+      const result: number = clampMonitorRequestTimeoutInMs(1);
+      expect(result).toBe(1);
+    });
+
+    test("a fractional millisecond value is preserved", () => {
+      const result: number = clampMonitorRequestTimeoutInMs(1500.75);
+      expect(result).toBe(1500.75);
+    });
+
+    test("a typical mid-range timeout is returned unchanged", () => {
+      const result: number = clampMonitorRequestTimeoutInMs(30000);
+      expect(result).toBe(30000);
+    });
+
+    test("a value just below the cap is not clamped", () => {
+      const justUnder: number = MAX_MONITOR_REQUEST_TIMEOUT_IN_MS - 1;
+      const result: number = clampMonitorRequestTimeoutInMs(justUnder);
+      expect(result).toBe(justUnder);
+    });
+  });
+
+  describe("the upper boundary", () => {
+    test("a value exactly at the cap is returned, not clamped (> is strict)", () => {
+      const result: number = clampMonitorRequestTimeoutInMs(
+        MAX_MONITOR_REQUEST_TIMEOUT_IN_MS,
+      );
+      expect(result).toBe(MAX_MONITOR_REQUEST_TIMEOUT_IN_MS);
+    });
+
+    test("one millisecond over the cap is clamped down to the cap", () => {
+      const result: number = clampMonitorRequestTimeoutInMs(
+        MAX_MONITOR_REQUEST_TIMEOUT_IN_MS + 1,
+      );
+      expect(result).toBe(MAX_MONITOR_REQUEST_TIMEOUT_IN_MS);
+    });
+  });
+
+  describe("values well above the cap are clamped", () => {
+    test("a value far above the cap is clamped to the cap", () => {
+      const result: number = clampMonitorRequestTimeoutInMs(
+        MAX_MONITOR_REQUEST_TIMEOUT_IN_MS * 10,
+      );
+      expect(result).toBe(MAX_MONITOR_REQUEST_TIMEOUT_IN_MS);
+    });
+
+    test("positive Infinity is clamped to the cap", () => {
+      const result: number = clampMonitorRequestTimeoutInMs(Infinity);
+      expect(result).toBe(MAX_MONITOR_REQUEST_TIMEOUT_IN_MS);
+    });
+  });
+
+  describe("purity and stability", () => {
+    test("the same input always yields the same output", () => {
+      const first: number = clampMonitorRequestTimeoutInMs(45000);
+      const second: number = clampMonitorRequestTimeoutInMs(45000);
+      expect(first).toBe(second);
+      expect(first).toBe(45000);
+    });
+
+    test("the exported cap is a positive finite number", () => {
+      expect(Number.isFinite(MAX_MONITOR_REQUEST_TIMEOUT_IN_MS)).toBe(true);
+      expect(MAX_MONITOR_REQUEST_TIMEOUT_IN_MS).toBeGreaterThan(0);
+    });
+
+    test("the clamped result never exceeds the cap across a sweep", () => {
+      const samples: Array<number> = [
+        -5000,
+        0,
+        1,
+        500,
+        60000,
+        60001,
+        250000,
+        Infinity,
+        NaN,
+      ];
+      for (const sample of samples) {
+        const result: number = clampMonitorRequestTimeoutInMs(sample);
+        expect(result).toBeLessThanOrEqual(MAX_MONITOR_REQUEST_TIMEOUT_IN_MS);
+        expect(result).toBeGreaterThan(0);
+      }
+    });
+  });
+});