@oneuptime/common 11.7.2 → 11.7.4

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

@@ -7,17 +7,21 @@ import {
 import MonitorStep from "../../../Types/Monitor/MonitorStep";
 import MonitorStepKubernetesMonitor from "../../../Types/Monitor/MonitorStepKubernetesMonitor";
 import MetricsAggregationType from "../../../Types/Metrics/MetricsAggregationType";
+import { FilterType } from "../../../Types/Monitor/CriteriaFilter";
 import ObjectID from "../../../Types/ObjectID";
 
 /*
- * These tests lock in the subtle, easy-to-regress decisions in the per-node
- * ratio alert templates (request utilization + usage utilization):
+ * These tests lock in the subtle, easy-to-regress decisions in the
+ * per-series ratio alert templates (node request/usage utilization, plus
+ * the autoscaling and container-limit saturation templates):
  *
  *   1. Group-by uses the ClickHouse-stored `resource.`-prefixed attribute
  *      name (`resource.k8s.node.name`), not the bare `k8s.node.name`.
  *      OneUptime stamps OTel resource attributes with a `resource.` prefix
  *      at ingest, so the bare key would match nothing and collapse every
- *      node into one mislabeled series.
+ *      node into one mislabeled series. The key differs per template — the
+ *      HPA template groups per HPA and the pod-limit templates per pod —
+ *      so each case carries its own expected key.
  *
  *   2. The aggregation differs by numerator shape:
  *        - Request utilization sums MANY container series per node, and both
@@ -27,9 +31,17 @@ import ObjectID from "../../../Types/ObjectID";
  *          (kubeletstats) and denominator (k8s_cluster) come from different
  *          receivers, so `Avg` on both sides gives the correct per-minute
  *          ratio regardless of each receiver's scrape count.
+ *        - The saturation templates are all `Avg` — see the pod-memory
+ *          template's note in KubernetesAlertTemplates.ts for the
+ *          multi-container trade-off that choice accepts.
  *
  *   3. The criteria reference the FORMULA alias (the computed percentage),
  *      not a raw query alias.
+ *
+ *   4. The unhealthy and healthy criteria PARTITION the value range — no
+ *      gap (a value that matches neither leaves the monitor stuck in its
+ *      previous status) and no overlap (a value that matches both makes the
+ *      resulting status depend on evaluation order).
  */
 
 interface RatioTemplateCase {
@@ -41,6 +53,7 @@ interface RatioTemplateCase {
   resultAlias: string;
   aggregation: MetricsAggregationType;
   threshold: number;
+  groupBy: string;
 }
 
 const RATIO_TEMPLATES: Array<RatioTemplateCase> = [
@@ -54,6 +67,7 @@ const RATIO_TEMPLATES: Array<RatioTemplateCase> = [
     resultAlias: "node_cpu_request_utilization",
     aggregation: MetricsAggregationType.Sum,
     threshold: 90,
+    groupBy: "resource.k8s.node.name",
   },
   {
     id: "k8s-node-memory-request-utilization",
@@ -64,6 +78,7 @@ const RATIO_TEMPLATES: Array<RatioTemplateCase> = [
     resultAlias: "node_memory_request_utilization",
     aggregation: MetricsAggregationType.Sum,
     threshold: 90,
+    groupBy: "resource.k8s.node.name",
   },
   // Usage utilization — Avg/Avg (one series per node, cross-receiver).
   {
@@ -75,6 +90,7 @@ const RATIO_TEMPLATES: Array<RatioTemplateCase> = [
     resultAlias: "node_cpu_utilization",
     aggregation: MetricsAggregationType.Avg,
     threshold: 90,
+    groupBy: "resource.k8s.node.name",
   },
   {
     id: "k8s-high-memory",
@@ -85,6 +101,50 @@ const RATIO_TEMPLATES: Array<RatioTemplateCase> = [
     resultAlias: "node_memory_utilization",
     aggregation: MetricsAggregationType.Avg,
     threshold: 85,
+    groupBy: "resource.k8s.node.name",
+  },
+  /*
+   * Autoscaling / limit saturation — Avg/Avg, and NOT keyed on the node.
+   *
+   * The HPA ratio groups per HPA object; the two pod-limit ratios group
+   * per pod. Locking the group-by key here is the point of these cases:
+   * these were the first ratio templates in this file not keyed on
+   * `resource.k8s.node.name`, so a copy-paste of the node key would
+   * silently collapse every HPA (or every pod) into one mislabeled
+   * series that still renders and still alerts.
+   */
+  {
+    id: "k8s-hpa-at-max-replicas",
+    numerator: "k8s.hpa.current_replicas",
+    denominator: "k8s.hpa.max_replicas",
+    numAlias: "current_replicas",
+    denAlias: "max_replicas",
+    resultAlias: "hpa_replica_saturation",
+    aggregation: MetricsAggregationType.Avg,
+    threshold: 90,
+    groupBy: "resource.k8s.hpa.name",
+  },
+  {
+    id: "k8s-pod-memory-limit-saturation",
+    numerator: "k8s.pod.memory.usage",
+    denominator: "k8s.container.memory_limit",
+    numAlias: "used_mem",
+    denAlias: "limit_mem",
+    resultAlias: "pod_memory_limit_saturation",
+    aggregation: MetricsAggregationType.Avg,
+    threshold: 90,
+    groupBy: "resource.k8s.pod.name",
+  },
+  {
+    id: "k8s-pod-cpu-limit-saturation",
+    numerator: "k8s.pod.cpu.utilization",
+    denominator: "k8s.container.cpu_limit",
+    numAlias: "used_cpu",
+    denAlias: "limit_cpu",
+    resultAlias: "pod_cpu_limit_saturation",
+    aggregation: MetricsAggregationType.Avg,
+    threshold: 90,
+    groupBy: "resource.k8s.pod.name",
   },
 ];
 
@@ -108,8 +168,8 @@ function getKubernetesMonitor(step: MonitorStep): MonitorStepKubernetesMonitor {
   return kubernetesMonitor;
 }
 
-describe("KubernetesAlertTemplates - per-node ratio templates", () => {
-  test("all four ratio templates are registered", () => {
+describe("KubernetesAlertTemplates - per-series ratio templates", () => {
+  test("all ratio templates are registered", () => {
     const ids: Array<string> = getAllKubernetesAlertTemplates().map(
       (t: KubernetesAlertTemplate) => {
         return t.id;
@@ -121,7 +181,7 @@ describe("KubernetesAlertTemplates - per-node ratio templates", () => {
   });
 
   test.each(RATIO_TEMPLATES)(
-    "$id is a per-node ($aggregation/$aggregation) ratio keyed on resource.k8s.node.name",
+    "$id is a ($aggregation/$aggregation) ratio keyed on $groupBy",
     (tc: RatioTemplateCase) => {
       const template: KubernetesAlertTemplate | undefined =
         getKubernetesAlertTemplateById(tc.id);
@@ -162,16 +222,19 @@ describe("KubernetesAlertTemplates - per-node ratio templates", () => {
       );
 
       /*
-       * Decision (1): group by the resource-prefixed node attribute on BOTH
+       * Decision (1): group by the resource-prefixed attribute on BOTH
        * queries so the per-series fingerprints line up for the formula join.
        */
       expect(numerator.metricQueryData.groupByAttributeKeys).toEqual([
-        "resource.k8s.node.name",
+        tc.groupBy,
       ]);
       expect(denominator.metricQueryData.groupByAttributeKeys).toEqual([
-        "resource.k8s.node.name",
+        tc.groupBy,
       ]);
 
+      // The `resource.` prefix is load-bearing — a bare OTel key matches nothing.
+      expect(tc.groupBy.startsWith("resource.")).toBe(true);
+
       // Formula divides numerator by denominator and scales to a percentage.
       expect(formulaConfigs[0].metricFormulaData.metricFormula).toBe(
         `(${tc.numAlias} / ${tc.denAlias}) * 100`,
@@ -190,4 +253,109 @@ describe("KubernetesAlertTemplates - per-node ratio templates", () => {
       expect(offlineFilters[0].value).toBe(tc.threshold);
     },
   );
+
+  /*
+   * Decision (4): unhealthy and healthy must be exact complements at the
+   * same threshold. Both halves are hand-written per template, so the
+   * failure mode is a strict/non-strict slip — pairing `> 90` with
+   * `< 90` leaves exactly 90 matching neither criterion (the monitor
+   * silently holds its previous status), and pairing `>= 90` with
+   * `<= 90` makes 90 match both (status depends on evaluation order).
+   */
+  const COMPLEMENT_OF: Record<string, string> = {
+    [FilterType.GreaterThan]: FilterType.LessThanOrEqualTo,
+    [FilterType.GreaterThanOrEqualTo]: FilterType.LessThan,
+  };
+
+  test.each(RATIO_TEMPLATES)(
+    "$id unhealthy/healthy criteria partition the range at $threshold",
+    (tc: RatioTemplateCase) => {
+      const template: KubernetesAlertTemplate | undefined =
+        getKubernetesAlertTemplateById(tc.id);
+      const step: MonitorStep = template!.getMonitorStep(buildArgs());
+
+      const instances: Array<any> = step.data?.monitorCriteria.data
+        ?.monitorCriteriaInstanceArray as Array<any>;
+      const [offline, online] = instances;
+
+      const offlineFilter: any = offline.data.filters[0];
+      const onlineFilter: any = online.data.filters[0];
+
+      // Same metric, same threshold — only the comparison direction differs.
+      expect(onlineFilter.metricMonitorOptions.metricAlias).toBe(
+        tc.resultAlias,
+      );
+      expect(onlineFilter.value).toBe(tc.threshold);
+
+      expect(COMPLEMENT_OF[offlineFilter.filterType]).toBe(
+        onlineFilter.filterType,
+      );
+
+      // The unhealthy criterion is the one that opens incidents/alerts.
+      expect(offline.data.createIncidents).toBe(true);
+      expect(offline.data.createAlerts).toBe(true);
+      expect(online.data.createIncidents).toBe(false);
+      expect(online.data.createAlerts).toBe(false);
+    },
+  );
+});
+
+/*
+ * The three saturation templates exist to catch the CAUSE of the
+ * "under-resourced workload behind an autoscaler" failure — limits too
+ * low, HPA driven to its ceiling, cluster filled — rather than its
+ * downstream symptoms (node pressure, pending pods, NotReady), which the
+ * older node-side templates already cover. These assertions pin the
+ * properties that make them useful for that: they must be discoverable in
+ * the picker under a category, and severity must reflect that memory
+ * saturation ends in an OOMKill while CPU saturation only throttles.
+ */
+describe("KubernetesAlertTemplates - autoscaling & limit saturation", () => {
+  const SATURATION_TEMPLATES: Array<{
+    id: string;
+    category: string;
+    severity: string;
+  }> = [
+    {
+      id: "k8s-hpa-at-max-replicas",
+      category: "Workload",
+      severity: "Critical",
+    },
+    {
+      id: "k8s-pod-memory-limit-saturation",
+      category: "Workload",
+      // Crossing a memory limit is an immediate kill, not a slowdown.
+      severity: "Critical",
+    },
+    {
+      id: "k8s-pod-cpu-limit-saturation",
+      category: "Workload",
+      // CFS throttling degrades latency; it never kills the container.
+      severity: "Warning",
+    },
+  ];
+
+  test.each(SATURATION_TEMPLATES)(
+    "$id is registered as a $severity $category template",
+    (tc: { id: string; category: string; severity: string }) => {
+      const template: KubernetesAlertTemplate | undefined =
+        getKubernetesAlertTemplateById(tc.id);
+
+      expect(template).toBeDefined();
+      expect(template!.category).toBe(tc.category);
+      expect(template!.severity).toBe(tc.severity);
+      expect(template!.name.length).toBeGreaterThan(0);
+      expect(template!.description.length).toBeGreaterThan(0);
+    },
+  );
+
+  test("every template id is unique", () => {
+    const ids: Array<string> = getAllKubernetesAlertTemplates().map(
+      (t: KubernetesAlertTemplate) => {
+        return t.id;
+      },
+    );
+
+    expect(new Set(ids).size).toBe(ids.length);
+  });
 });

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

@@ -0,0 +1,105 @@
+import { JSONObject } from "../../../Types/JSON";
+import DnsRecordType from "../../../Types/Monitor/DnsMonitor/DnsRecordType";
+import MonitorStepDnsMonitor, {
+  MonitorStepDnsMonitorUtil,
+} from "../../../Types/Monitor/MonitorStepDnsMonitor";
+
+describe("MonitorStepDnsMonitorUtil", () => {
+  describe("getDefault", () => {
+    test("returns an empty query on port 53 with an A record", () => {
+      const def: MonitorStepDnsMonitor = MonitorStepDnsMonitorUtil.getDefault();
+
+      expect(def.queryName).toBe("");
+      expect(def.recordType).toBe(DnsRecordType.A);
+      expect(def.hostname).toBe("");
+      expect(def.port).toBe(53);
+      expect(def.timeout).toBe(5000);
+      expect(def.retries).toBe(3);
+    });
+  });
+
+  describe("fromJSON", () => {
+    test("reads through explicit values", () => {
+      const parsed: MonitorStepDnsMonitor = MonitorStepDnsMonitorUtil.fromJSON({
+        queryName: "oneuptime.com",
+        recordType: DnsRecordType.MX,
+        hostname: "8.8.8.8",
+        port: 5353,
+        timeout: 2000,
+        retries: 5,
+      });
+
+      expect(parsed.queryName).toBe("oneuptime.com");
+      expect(parsed.recordType).toBe(DnsRecordType.MX);
+      expect(parsed.hostname).toBe("8.8.8.8");
+      expect(parsed.port).toBe(5353);
+      expect(parsed.timeout).toBe(2000);
+      expect(parsed.retries).toBe(5);
+    });
+
+    test("falls back to defaults for missing or falsy fields", () => {
+      const parsed: MonitorStepDnsMonitor = MonitorStepDnsMonitorUtil.fromJSON(
+        {},
+      );
+
+      expect(parsed.queryName).toBe("");
+      expect(parsed.recordType).toBe(DnsRecordType.A);
+      // An empty hostname collapses to undefined (system-default resolver).
+      expect(parsed.hostname).toBeUndefined();
+      expect(parsed.port).toBe(53);
+      expect(parsed.timeout).toBe(5000);
+      expect(parsed.retries).toBe(3);
+    });
+
+    test("treats an empty hostname as the system default resolver", () => {
+      const parsed: MonitorStepDnsMonitor = MonitorStepDnsMonitorUtil.fromJSON({
+        queryName: "oneuptime.com",
+        hostname: "",
+      });
+
+      expect(parsed.hostname).toBeUndefined();
+    });
+  });
+
+  describe("toJSON / round-trip", () => {
+    test("serializes every field", () => {
+      const monitor: MonitorStepDnsMonitor = {
+        queryName: "example.com",
+        recordType: DnsRecordType.AAAA,
+        hostname: "1.1.1.1",
+        port: 53,
+        timeout: 7000,
+        retries: 2,
+      };
+
+      const json: JSONObject = MonitorStepDnsMonitorUtil.toJSON(monitor);
+
+      expect(json).toEqual({
+        queryName: "example.com",
+        recordType: DnsRecordType.AAAA,
+        hostname: "1.1.1.1",
+        port: 53,
+        timeout: 7000,
+        retries: 2,
+      });
+    });
+
+    test("fromJSON(toJSON(x)) preserves a populated monitor", () => {
+      const monitor: MonitorStepDnsMonitor = {
+        queryName: "example.com",
+        recordType: DnsRecordType.TXT,
+        hostname: "9.9.9.9",
+        port: 5300,
+        timeout: 4000,
+        retries: 4,
+      };
+
+      const roundTripped: MonitorStepDnsMonitor =
+        MonitorStepDnsMonitorUtil.fromJSON(
+          MonitorStepDnsMonitorUtil.toJSON(monitor),
+        );
+
+      expect(roundTripped).toEqual(monitor);
+    });
+  });
+});

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

@@ -0,0 +1,131 @@
+import { JSONObject } from "../../../Types/JSON";
+import MonitorStepDnssecMonitor, {
+  MonitorStepDnssecMonitorUtil,
+} from "../../../Types/Monitor/MonitorStepDnssecMonitor";
+
+describe("MonitorStepDnssecMonitorUtil", () => {
+  describe("getDefault", () => {
+    test("returns three public resolvers and nameserver consistency on", () => {
+      const def: MonitorStepDnssecMonitor =
+        MonitorStepDnssecMonitorUtil.getDefault();
+
+      expect(def.domainName).toBe("");
+      expect(def.resolvers).toEqual(["1.1.1.1", "8.8.8.8", "9.9.9.9"]);
+      expect(def.checkNameserverConsistency).toBe(true);
+      expect(def.signatureExpiryWarningDays).toBe(7);
+      expect(def.timeout).toBe(10000);
+      expect(def.retries).toBe(3);
+    });
+  });
+
+  describe("fromJSON resolvers handling", () => {
+    test("keeps only non-empty string resolvers", () => {
+      const parsed: MonitorStepDnssecMonitor =
+        MonitorStepDnssecMonitorUtil.fromJSON({
+          domainName: "oneuptime.com",
+          resolvers: ["1.1.1.1", "", "8.8.4.4", 123, null],
+        });
+
+      expect(parsed.resolvers).toEqual(["1.1.1.1", "8.8.4.4"]);
+    });
+
+    test("restores default resolvers when the provided list filters down to empty", () => {
+      const parsed: MonitorStepDnssecMonitor =
+        MonitorStepDnssecMonitorUtil.fromJSON({
+          domainName: "oneuptime.com",
+          resolvers: ["", 5, null],
+        });
+
+      expect(parsed.resolvers).toEqual(["1.1.1.1", "8.8.8.8", "9.9.9.9"]);
+    });
+
+    test("restores default resolvers when resolvers is not an array", () => {
+      const parsed: MonitorStepDnssecMonitor =
+        MonitorStepDnssecMonitorUtil.fromJSON({
+          domainName: "oneuptime.com",
+          resolvers: "1.1.1.1" as unknown as Array<string>,
+        });
+
+      expect(parsed.resolvers).toEqual(["1.1.1.1", "8.8.8.8", "9.9.9.9"]);
+    });
+  });
+
+  describe("fromJSON checkNameserverConsistency handling", () => {
+    test("honors an explicit false", () => {
+      const parsed: MonitorStepDnssecMonitor =
+        MonitorStepDnssecMonitorUtil.fromJSON({
+          domainName: "oneuptime.com",
+          checkNameserverConsistency: false,
+        });
+
+      expect(parsed.checkNameserverConsistency).toBe(false);
+    });
+
+    test("defaults to true when the field is absent or non-boolean", () => {
+      expect(
+        MonitorStepDnssecMonitorUtil.fromJSON({ domainName: "oneuptime.com" })
+          .checkNameserverConsistency,
+      ).toBe(true);
+
+      expect(
+        MonitorStepDnssecMonitorUtil.fromJSON({
+          domainName: "oneuptime.com",
+          checkNameserverConsistency: "yes" as unknown as boolean,
+        }).checkNameserverConsistency,
+      ).toBe(true);
+    });
+  });
+
+  describe("fromJSON numeric defaults", () => {
+    test("falls back for falsy numeric fields", () => {
+      const parsed: MonitorStepDnssecMonitor =
+        MonitorStepDnssecMonitorUtil.fromJSON({
+          domainName: "oneuptime.com",
+          signatureExpiryWarningDays: 0,
+          timeout: 0,
+          retries: 0,
+        });
+
+      expect(parsed.signatureExpiryWarningDays).toBe(7);
+      expect(parsed.timeout).toBe(10000);
+      expect(parsed.retries).toBe(3);
+    });
+  });
+
+  describe("round-trip", () => {
+    test("fromJSON(toJSON(x)) preserves a populated monitor", () => {
+      const monitor: MonitorStepDnssecMonitor = {
+        domainName: "example.com",
+        resolvers: ["8.8.8.8"],
+        checkNameserverConsistency: false,
+        signatureExpiryWarningDays: 14,
+        timeout: 20000,
+        retries: 5,
+      };
+
+      const roundTripped: MonitorStepDnssecMonitor =
+        MonitorStepDnssecMonitorUtil.fromJSON(
+          MonitorStepDnssecMonitorUtil.toJSON(monitor),
+        );
+
+      expect(roundTripped).toEqual(monitor);
+    });
+
+    test("toJSON emits every field", () => {
+      const json: JSONObject = MonitorStepDnssecMonitorUtil.toJSON(
+        MonitorStepDnssecMonitorUtil.getDefault(),
+      );
+
+      expect(Object.keys(json).sort()).toEqual(
+        [
+          "checkNameserverConsistency",
+          "domainName",
+          "resolvers",
+          "retries",
+          "signatureExpiryWarningDays",
+          "timeout",
+        ].sort(),
+      );
+    });
+  });
+});

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

@@ -0,0 +1,60 @@
+import { JSONObject } from "../../../Types/JSON";
+import MonitorStepDomainMonitor, {
+  MonitorStepDomainMonitorUtil,
+} from "../../../Types/Monitor/MonitorStepDomainMonitor";
+
+describe("MonitorStepDomainMonitorUtil", () => {
+  describe("getDefault", () => {
+    test("returns an empty domain with 10s timeout and 3 retries", () => {
+      const def: MonitorStepDomainMonitor =
+        MonitorStepDomainMonitorUtil.getDefault();
+
+      expect(def.domainName).toBe("");
+      expect(def.timeout).toBe(10000);
+      expect(def.retries).toBe(3);
+    });
+  });
+
+  describe("fromJSON", () => {
+    test("reads through explicit values", () => {
+      const parsed: MonitorStepDomainMonitor =
+        MonitorStepDomainMonitorUtil.fromJSON({
+          domainName: "oneuptime.com",
+          timeout: 3000,
+          retries: 7,
+        });
+
+      expect(parsed.domainName).toBe("oneuptime.com");
+      expect(parsed.timeout).toBe(3000);
+      expect(parsed.retries).toBe(7);
+    });
+
+    test("falls back to defaults for missing or falsy fields", () => {
+      const parsed: MonitorStepDomainMonitor =
+        MonitorStepDomainMonitorUtil.fromJSON({
+          domainName: "",
+          timeout: 0,
+          retries: 0,
+        });
+
+      expect(parsed.domainName).toBe("");
+      expect(parsed.timeout).toBe(10000);
+      expect(parsed.retries).toBe(3);
+    });
+  });
+
+  describe("round-trip", () => {
+    test("toJSON emits every field and fromJSON restores it", () => {
+      const monitor: MonitorStepDomainMonitor = {
+        domainName: "example.com",
+        timeout: 5000,
+        retries: 2,
+      };
+
+      const json: JSONObject = MonitorStepDomainMonitorUtil.toJSON(monitor);
+      expect(json).toEqual(monitor);
+
+      expect(MonitorStepDomainMonitorUtil.fromJSON(json)).toEqual(monitor);
+    });
+  });
+});

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

@@ -0,0 +1,82 @@
+import { JSONObject } from "../../../Types/JSON";
+import ExternalStatusPageProviderType from "../../../Types/Monitor/ExternalStatusPageProviderType";
+import MonitorStepExternalStatusPageMonitor, {
+  MonitorStepExternalStatusPageMonitorUtil,
+} from "../../../Types/Monitor/MonitorStepExternalStatusPageMonitor";
+
+describe("MonitorStepExternalStatusPageMonitorUtil", () => {
+  describe("getDefault", () => {
+    test("returns an auto-detected provider with no component filters", () => {
+      const def: MonitorStepExternalStatusPageMonitor =
+        MonitorStepExternalStatusPageMonitorUtil.getDefault();
+
+      expect(def.statusPageUrl).toBe("");
+      expect(def.provider).toBe(ExternalStatusPageProviderType.Auto);
+      expect(def.componentGroupName).toBeUndefined();
+      expect(def.componentName).toBeUndefined();
+      expect(def.timeout).toBe(10000);
+      expect(def.retries).toBe(3);
+    });
+  });
+
+  describe("fromJSON", () => {
+    test("reads through explicit values", () => {
+      const parsed: MonitorStepExternalStatusPageMonitor =
+        MonitorStepExternalStatusPageMonitorUtil.fromJSON({
+          statusPageUrl: "https://status.example.com",
+          provider: ExternalStatusPageProviderType.AtlassianStatuspage,
+          componentGroupName: "APIs",
+          componentName: "Ingest",
+          timeout: 4000,
+          retries: 1,
+        });
+
+      expect(parsed.statusPageUrl).toBe("https://status.example.com");
+      expect(parsed.provider).toBe(
+        ExternalStatusPageProviderType.AtlassianStatuspage,
+      );
+      expect(parsed.componentGroupName).toBe("APIs");
+      expect(parsed.componentName).toBe("Ingest");
+      expect(parsed.timeout).toBe(4000);
+      expect(parsed.retries).toBe(1);
+    });
+
+    test("falls back to defaults for missing or falsy fields", () => {
+      const parsed: MonitorStepExternalStatusPageMonitor =
+        MonitorStepExternalStatusPageMonitorUtil.fromJSON({
+          statusPageUrl: "",
+          componentGroupName: "",
+          componentName: "",
+          timeout: 0,
+          retries: 0,
+        });
+
+      expect(parsed.statusPageUrl).toBe("");
+      expect(parsed.provider).toBe(ExternalStatusPageProviderType.Auto);
+      expect(parsed.componentGroupName).toBeUndefined();
+      expect(parsed.componentName).toBeUndefined();
+      expect(parsed.timeout).toBe(10000);
+      expect(parsed.retries).toBe(3);
+    });
+  });
+
+  describe("round-trip", () => {
+    test("fromJSON(toJSON(x)) preserves a populated monitor", () => {
+      const monitor: MonitorStepExternalStatusPageMonitor = {
+        statusPageUrl: "https://status.incident.io/x",
+        provider: ExternalStatusPageProviderType.IncidentIo,
+        componentGroupName: "Core",
+        componentName: "Dashboard",
+        timeout: 15000,
+        retries: 5,
+      };
+
+      const json: JSONObject =
+        MonitorStepExternalStatusPageMonitorUtil.toJSON(monitor);
+      const roundTripped: MonitorStepExternalStatusPageMonitor =
+        MonitorStepExternalStatusPageMonitorUtil.fromJSON(json);
+
+      expect(roundTripped).toEqual(monitor);
+    });
+  });
+});