@oneuptime/common 11.6.1 → 11.7.0

package/Tests/Utils/Slo/SloDuration.test.ts

@@ -0,0 +1,148 @@
+import {
+  formatDurationCompact,
+  formatErrorBudgetRemaining,
+  formatErrorBudgetRemainingOfTotal,
+} from "../../../Utils/Slo/SloDuration";
+
+const MINUS_SIGN: string = "−";
+
+describe("SloDuration", () => {
+  describe("formatDurationCompact", () => {
+    it("renders seconds under a minute", () => {
+      expect(formatDurationCompact(45)).toBe("45s");
+      expect(formatDurationCompact(1)).toBe("1s");
+    });
+
+    it("renders zero as 0s rather than an empty string", () => {
+      expect(formatDurationCompact(0)).toBe("0s");
+    });
+
+    it("renders minutes and seconds", () => {
+      // 99.9% over 30 days — the canonical error budget.
+      expect(formatDurationCompact(2592)).toBe("43m 12s");
+    });
+
+    it("drops a zero remainder instead of padding it", () => {
+      expect(formatDurationCompact(120)).toBe("2m");
+      expect(formatDurationCompact(7200)).toBe("2h");
+      expect(formatDurationCompact(172800)).toBe("2d");
+    });
+
+    it("renders hours and minutes", () => {
+      // 99% over 90 days.
+      expect(formatDurationCompact(77760)).toBe("21h 36m");
+      expect(formatDurationCompact(7860)).toBe("2h 11m");
+    });
+
+    it("renders days and hours", () => {
+      expect(formatDurationCompact(190800)).toBe("2d 5h");
+    });
+
+    it("shows at most the two most significant units", () => {
+      // 2d 5h 13m 7s — the minutes and seconds are dropped.
+      expect(formatDurationCompact(191587)).toBe("2d 5h");
+    });
+
+    it("skips leading zero units", () => {
+      // 0d 0h 5m 3s.
+      expect(formatDurationCompact(303)).toBe("5m 3s");
+    });
+
+    it("skips an interior zero unit and moves on to the next", () => {
+      /*
+       * Exactly 2 days + 30 seconds: hours and minutes are both zero, so
+       * the second slot is filled by seconds rather than padded with "0h".
+       */
+      expect(formatDurationCompact(172830)).toBe("2d 30s");
+    });
+
+    it("floors fractional seconds instead of rounding up", () => {
+      // A 59.9s budget must never read as a full minute it does not have.
+      expect(formatDurationCompact(59.9)).toBe("59s");
+      expect(formatDurationCompact(0.4)).toBe("0s");
+    });
+
+    it("renders the magnitude of a negative input (sign is the caller's job)", () => {
+      expect(formatDurationCompact(-2592)).toBe("43m 12s");
+    });
+  });
+
+  describe("formatErrorBudgetRemaining", () => {
+    it("labels a positive remainder as left", () => {
+      expect(formatErrorBudgetRemaining(2592)).toBe("43m 12s left");
+    });
+
+    it("renders an exhausted-but-not-overspent budget as 0s left", () => {
+      expect(formatErrorBudgetRemaining(0)).toBe("0s left");
+    });
+
+    it("renders an overspent budget with a minus sign and over budget", () => {
+      expect(formatErrorBudgetRemaining(-750)).toBe(
+        `${MINUS_SIGN}12m 30s over budget`,
+      );
+    });
+
+    it("returns null when the SLO has not been evaluated", () => {
+      expect(formatErrorBudgetRemaining(null)).toBeNull();
+      expect(formatErrorBudgetRemaining(undefined)).toBeNull();
+    });
+
+    it("returns null for non-finite values", () => {
+      expect(formatErrorBudgetRemaining(Number.NaN)).toBeNull();
+      expect(formatErrorBudgetRemaining(Number.POSITIVE_INFINITY)).toBeNull();
+    });
+
+    it("rejects a numeric string rather than coercing it", () => {
+      expect(
+        formatErrorBudgetRemaining("2592" as unknown as number),
+      ).toBeNull();
+    });
+  });
+
+  describe("formatErrorBudgetRemainingOfTotal", () => {
+    it("renders remaining alongside the total", () => {
+      expect(
+        formatErrorBudgetRemainingOfTotal({
+          remainingSeconds: 750,
+          totalSeconds: 2592,
+        }),
+      ).toBe("12m 30s left of 43m 12s");
+    });
+
+    it("keeps the total visible when the budget is overspent", () => {
+      expect(
+        formatErrorBudgetRemainingOfTotal({
+          remainingSeconds: -750,
+          totalSeconds: 2592,
+        }),
+      ).toBe(`${MINUS_SIGN}12m 30s over budget of 43m 12s`);
+    });
+
+    it("omits the total when it is unknown", () => {
+      expect(
+        formatErrorBudgetRemainingOfTotal({
+          remainingSeconds: 750,
+          totalSeconds: null,
+        }),
+      ).toBe("12m 30s left");
+    });
+
+    it("omits a zero total — a brand-new SLO has no elapsed window yet", () => {
+      expect(
+        formatErrorBudgetRemainingOfTotal({
+          remainingSeconds: 0,
+          totalSeconds: 0,
+        }),
+      ).toBe("0s left");
+    });
+
+    it("returns null when the SLO has not been evaluated", () => {
+      expect(
+        formatErrorBudgetRemainingOfTotal({
+          remainingSeconds: null,
+          totalSeconds: 2592,
+        }),
+      ).toBeNull();
+    });
+  });
+});

package/Tests/Utils/Slo/SloHealth.test.ts

@@ -0,0 +1,334 @@
+import SliType from "../../../Types/ServiceLevelObjective/SliType";
+import SloMultiMonitorMode from "../../../Types/ServiceLevelObjective/SloMultiMonitorMode";
+import SloStatus from "../../../Types/ServiceLevelObjective/SloStatus";
+import SloWindowType from "../../../Types/ServiceLevelObjective/SloWindowType";
+import {
+  DEFAULT_AT_RISK_THRESHOLD_PERCENTAGE,
+  getSloBudgetTier,
+  getSloNotice,
+  isRollingWindowNotYetFull,
+  SloBudgetTier,
+  SloNotice,
+  SloNoticeType,
+} from "../../../Utils/Slo/SloHealth";
+
+const SECONDS_PER_DAY: number = 24 * 60 * 60;
+
+/** The full 30-day error budget of a 99.9% SLO: 43m 12s. */
+const THIRTY_DAY_999_BUDGET_SECONDS: number = 0.001 * 30 * SECONDS_PER_DAY;
+
+describe("SloHealth", () => {
+  describe("getSloBudgetTier", () => {
+    it("returns Unknown when the SLO has not been evaluated", () => {
+      expect(getSloBudgetTier({ errorBudgetRemainingPercentage: null })).toBe(
+        SloBudgetTier.Unknown,
+      );
+      expect(
+        getSloBudgetTier({ errorBudgetRemainingPercentage: undefined }),
+      ).toBe(SloBudgetTier.Unknown);
+    });
+
+    it("returns Unknown for non-finite values", () => {
+      expect(
+        getSloBudgetTier({ errorBudgetRemainingPercentage: Number.NaN }),
+      ).toBe(SloBudgetTier.Unknown);
+    });
+
+    it("returns Healthy well above the threshold", () => {
+      expect(getSloBudgetTier({ errorBudgetRemainingPercentage: 68 })).toBe(
+        SloBudgetTier.Healthy,
+      );
+    });
+
+    it("returns Exhausted at exactly zero", () => {
+      expect(getSloBudgetTier({ errorBudgetRemainingPercentage: 0 })).toBe(
+        SloBudgetTier.Exhausted,
+      );
+    });
+
+    it("returns Exhausted when overspent", () => {
+      expect(getSloBudgetTier({ errorBudgetRemainingPercentage: -37 })).toBe(
+        SloBudgetTier.Exhausted,
+      );
+    });
+
+    it("returns AtRisk at exactly the threshold", () => {
+      expect(
+        getSloBudgetTier({
+          errorBudgetRemainingPercentage: DEFAULT_AT_RISK_THRESHOLD_PERCENTAGE,
+        }),
+      ).toBe(SloBudgetTier.AtRisk);
+    });
+
+    it("falls back to the 20% default when no threshold is given", () => {
+      expect(getSloBudgetTier({ errorBudgetRemainingPercentage: 19.9 })).toBe(
+        SloBudgetTier.AtRisk,
+      );
+      expect(getSloBudgetTier({ errorBudgetRemainingPercentage: 20.1 })).toBe(
+        SloBudgetTier.Healthy,
+      );
+    });
+
+    it("honours a custom at-risk threshold instead of the hardcoded 20", () => {
+      /*
+       * The regression this function exists for: at a 50% threshold the
+       * old `remaining <= 20` check rendered 35% green while the worker
+       * had already moved the SLO to At Risk.
+       */
+      expect(
+        getSloBudgetTier({
+          errorBudgetRemainingPercentage: 35,
+          atRiskThresholdPercentage: 50,
+        }),
+      ).toBe(SloBudgetTier.AtRisk);
+
+      expect(
+        getSloBudgetTier({
+          errorBudgetRemainingPercentage: 15,
+          atRiskThresholdPercentage: 5,
+        }),
+      ).toBe(SloBudgetTier.Healthy);
+    });
+
+    it("treats a zero threshold as 'at risk only once exhausted'", () => {
+      expect(
+        getSloBudgetTier({
+          errorBudgetRemainingPercentage: 0.5,
+          atRiskThresholdPercentage: 0,
+        }),
+      ).toBe(SloBudgetTier.Healthy);
+    });
+  });
+
+  describe("getSloNotice", () => {
+    it("returns null for a normally measuring SLO", () => {
+      expect(
+        getSloNotice({
+          isEnabled: true,
+          sloStatus: SloStatus.Healthy,
+          sliType: SliType.MonitorUptime,
+          monitorCount: 2,
+          targetPercentage: 99.9,
+          lastEvaluatedAt: new Date(),
+        }),
+      ).toBeNull();
+    });
+
+    it("reports a disabled SLO ahead of any other reason", () => {
+      /*
+       * A disabled SLO is never evaluated, so its stale Misconfigured
+       * status must not send the user off to attach monitors.
+       */
+      const notice: SloNotice | null = getSloNotice({
+        isEnabled: false,
+        sloStatus: SloStatus.Misconfigured,
+        monitorCount: 0,
+      });
+
+      expect(notice?.type).toBe(SloNoticeType.Info);
+      expect(notice?.title).toBe("This SLO is disabled");
+    });
+
+    it("names 'no monitors' as the reason for Misconfigured", () => {
+      const notice: SloNotice | null = getSloNotice({
+        isEnabled: true,
+        sloStatus: SloStatus.Misconfigured,
+        sliType: SliType.MonitorUptime,
+        monitorCount: 0,
+        targetPercentage: 99.9,
+        lastEvaluatedAt: new Date(),
+      });
+
+      expect(notice?.type).toBe(SloNoticeType.Warning);
+      expect(notice?.title).toBe("No monitors attached");
+    });
+
+    it("names an out-of-range target as the reason for Misconfigured", () => {
+      const notice: SloNotice | null = getSloNotice({
+        isEnabled: true,
+        sloStatus: SloStatus.Misconfigured,
+        sliType: SliType.MonitorUptime,
+        monitorCount: 1,
+        targetPercentage: 100,
+        lastEvaluatedAt: new Date(),
+      });
+
+      expect(notice?.title).toBe("The target is out of range");
+    });
+
+    it("names an unsupported SLI type ahead of the monitor count", () => {
+      const notice: SloNotice | null = getSloNotice({
+        isEnabled: true,
+        sloStatus: SloStatus.Misconfigured,
+        sliType: SliType.Metric,
+        monitorCount: 0,
+        targetPercentage: 99.9,
+        lastEvaluatedAt: new Date(),
+      });
+
+      expect(notice?.body).toContain(SliType.MonitorUptime);
+    });
+
+    it("falls back to a generic reason for Misconfigured", () => {
+      const notice: SloNotice | null = getSloNotice({
+        isEnabled: true,
+        sloStatus: SloStatus.Misconfigured,
+        sliType: SliType.MonitorUptime,
+        monitorCount: 1,
+        targetPercentage: 99.9,
+        lastEvaluatedAt: new Date(),
+      });
+
+      expect(notice?.title).toBe("This SLO cannot be evaluated");
+    });
+
+    it("explains Paused", () => {
+      const notice: SloNotice | null = getSloNotice({
+        isEnabled: true,
+        sloStatus: SloStatus.Paused,
+        sliType: SliType.MonitorUptime,
+        monitorCount: 2,
+        targetPercentage: 99.9,
+        lastEvaluatedAt: new Date(),
+      });
+
+      expect(notice?.type).toBe(SloNoticeType.Info);
+      expect(notice?.title).toBe("Measurement is paused");
+    });
+
+    it("explains a never-evaluated SLO", () => {
+      const notice: SloNotice | null = getSloNotice({
+        isEnabled: true,
+        sloStatus: SloStatus.Healthy,
+        sliType: SliType.MonitorUptime,
+        monitorCount: 1,
+        targetPercentage: 99.9,
+        lastEvaluatedAt: null,
+      });
+
+      expect(notice?.title).toBe("Not evaluated yet");
+    });
+
+    it("says nothing about a healthy SLO whose isEnabled was not selected", () => {
+      // `undefined` means "not loaded", which is not the same as `false`.
+      expect(
+        getSloNotice({
+          sloStatus: SloStatus.Healthy,
+          sliType: SliType.MonitorUptime,
+          monitorCount: 1,
+          targetPercentage: 99.9,
+          lastEvaluatedAt: new Date(),
+        }),
+      ).toBeNull();
+    });
+  });
+
+  describe("isRollingWindowNotYetFull", () => {
+    it("is false for a mature rolling window", () => {
+      expect(
+        isRollingWindowNotYetFull({
+          windowType: SloWindowType.Rolling,
+          windowDays: 30,
+          targetPercentage: 99.9,
+          errorBudgetTotalSeconds: THIRTY_DAY_999_BUDGET_SECONDS,
+        }),
+      ).toBe(false);
+    });
+
+    it("is true for a 30-day SLO carrying only a week of data", () => {
+      expect(
+        isRollingWindowNotYetFull({
+          windowType: SloWindowType.Rolling,
+          windowDays: 30,
+          targetPercentage: 99.9,
+          errorBudgetTotalSeconds: 0.001 * 7 * SECONDS_PER_DAY,
+        }),
+      ).toBe(true);
+    });
+
+    it("stays silent for Monitor Seconds Average — its budget scales with the monitor count", () => {
+      /*
+       * A five-monitor SLO with a week of data carries 35 monitor-days of
+       * budget, which would read as mature against a 30-day yardstick. The
+       * helper declines to guess rather than answer wrongly in either
+       * direction.
+       */
+      expect(
+        isRollingWindowNotYetFull({
+          windowType: SloWindowType.Rolling,
+          windowDays: 30,
+          targetPercentage: 99.9,
+          errorBudgetTotalSeconds: 0.001 * 7 * SECONDS_PER_DAY,
+          multiMonitorMode: SloMultiMonitorMode.MonitorSecondsAverage,
+        }),
+      ).toBe(false);
+    });
+
+    it("still answers for the default Any Monitor Down mode", () => {
+      expect(
+        isRollingWindowNotYetFull({
+          windowType: SloWindowType.Rolling,
+          windowDays: 30,
+          targetPercentage: 99.9,
+          errorBudgetTotalSeconds: 0.001 * 7 * SECONDS_PER_DAY,
+          multiMonitorMode: SloMultiMonitorMode.AnyDown,
+        }),
+      ).toBe(true);
+    });
+
+    it("tolerates the small shortfall between now and the last evaluation", () => {
+      // 0.5% short — a mature SLO must not flicker the banner.
+      expect(
+        isRollingWindowNotYetFull({
+          windowType: SloWindowType.Rolling,
+          windowDays: 30,
+          targetPercentage: 99.9,
+          errorBudgetTotalSeconds: THIRTY_DAY_999_BUDGET_SECONDS * 0.995,
+        }),
+      ).toBe(false);
+    });
+
+    it("is false for calendar-month windows — their budget is never prorated", () => {
+      expect(
+        isRollingWindowNotYetFull({
+          windowType: SloWindowType.CalendarMonth,
+          windowDays: 30,
+          targetPercentage: 99.9,
+          errorBudgetTotalSeconds: 1,
+        }),
+      ).toBe(false);
+    });
+
+    it("is false when the SLO has not been evaluated", () => {
+      expect(
+        isRollingWindowNotYetFull({
+          windowType: SloWindowType.Rolling,
+          windowDays: 30,
+          targetPercentage: 99.9,
+          errorBudgetTotalSeconds: null,
+        }),
+      ).toBe(false);
+    });
+
+    it("is false when the target would make the full-window budget meaningless", () => {
+      expect(
+        isRollingWindowNotYetFull({
+          windowType: SloWindowType.Rolling,
+          windowDays: 30,
+          targetPercentage: 100,
+          errorBudgetTotalSeconds: 60,
+        }),
+      ).toBe(false);
+    });
+
+    it("defaults windowDays to 30 when it is not set", () => {
+      expect(
+        isRollingWindowNotYetFull({
+          windowType: SloWindowType.Rolling,
+          targetPercentage: 99.9,
+          errorBudgetTotalSeconds: 0.001 * 7 * SECONDS_PER_DAY,
+        }),
+      ).toBe(true);
+    });
+  });
+});

package/Tests/Utils/Slo/SloStatusColor.test.ts

@@ -0,0 +1,89 @@
+import { Gray500, Green, Red, Yellow } from "../../../Types/BrandColors";
+import Color from "../../../Types/Color";
+import SloStatus from "../../../Types/ServiceLevelObjective/SloStatus";
+import {
+  getSloStatusColor,
+  getSloStatusText,
+} from "../../../Utils/Slo/SloStatusColor";
+
+describe("SloStatusColor", () => {
+  describe("getSloStatusColor", () => {
+    it("colours a healthy SLO green", () => {
+      expect(getSloStatusColor(SloStatus.Healthy).toString()).toBe(
+        Green.toString(),
+      );
+    });
+
+    it("colours an at-risk SLO yellow", () => {
+      expect(getSloStatusColor(SloStatus.AtRisk).toString()).toBe(
+        Yellow.toString(),
+      );
+    });
+
+    it("colours an exhausted error budget red", () => {
+      expect(getSloStatusColor(SloStatus.BudgetExhausted).toString()).toBe(
+        Red.toString(),
+      );
+    });
+
+    it("colours a misconfigured SLO gray because there is nothing to measure", () => {
+      expect(getSloStatusColor(SloStatus.Misconfigured).toString()).toBe(
+        Gray500.toString(),
+      );
+    });
+
+    it("colours a paused SLO gray because it is deliberately not measured", () => {
+      expect(getSloStatusColor(SloStatus.Paused).toString()).toBe(
+        Gray500.toString(),
+      );
+    });
+
+    it("colours an unset status gray rather than claiming a health colour", () => {
+      expect(getSloStatusColor(undefined).toString()).toBe(Gray500.toString());
+      expect(getSloStatusColor(null).toString()).toBe(Gray500.toString());
+    });
+
+    it("colours an unrecognised persisted status gray", () => {
+      expect(getSloStatusColor("Something New" as SloStatus).toString()).toBe(
+        Gray500.toString(),
+      );
+    });
+
+    it("returns a colour for every member of the SloStatus enum", () => {
+      for (const status of Object.values(SloStatus)) {
+        const color: Color = getSloStatusColor(status);
+
+        expect(color).toBeInstanceOf(Color);
+        expect(color.toString()).toMatch(/^#[0-9a-fA-F]{6}$/);
+      }
+    });
+
+    it("only ever uses the four brand colours the SLO pages use", () => {
+      const allowed: Array<string> = [
+        Green.toString(),
+        Yellow.toString(),
+        Red.toString(),
+        Gray500.toString(),
+      ];
+
+      for (const status of Object.values(SloStatus)) {
+        expect(allowed).toContain(getSloStatusColor(status).toString());
+      }
+    });
+  });
+
+  describe("getSloStatusText", () => {
+    it.each(Object.values(SloStatus))(
+      "passes the %s status through unchanged",
+      (status: SloStatus) => {
+        expect(getSloStatusText(status)).toBe(status);
+      },
+    );
+
+    it("labels an unevaluated SLO Unknown rather than defaulting to Healthy", () => {
+      expect(getSloStatusText(undefined)).toBe("Unknown");
+      expect(getSloStatusText(null)).toBe("Unknown");
+      expect(getSloStatusText(undefined)).not.toBe(SloStatus.Healthy);
+    });
+  });
+});