@oneuptime/common 12.0.33 → 13.0.0

package/Tests/Server/Utils/Monitor/NetworkInventoryUtil.test.ts

@@ -20,6 +20,8 @@ import SnmpVendorTemplateUtil, {
 import NetworkDeviceMonitoringMethod from "../../../../Types/NetworkDevice/NetworkDeviceMonitoringMethod";
 import { NetworkDevicePollMode } from "../../../../Server/Utils/Monitor/NetworkDeviceHydrationUtil";
 import logger from "../../../../Server/Utils/Logger";
+import { JSONObject } from "../../../../Types/JSON";
+import { FindOperator } from "typeorm";
 
 /*
  * NetworkInventoryUtil.updateFromWalk is the single writer that keeps the
@@ -47,6 +49,8 @@ let deviceUpdateSpy: jest.SpyInstance;
 let interfaceFindSpy: jest.SpyInstance;
 let interfaceUpsertSpy: jest.SpyInstance;
 let endpointUpsertSpy: jest.SpyInstance;
+let deviceLookupSpy: jest.SpyInstance;
+let macWriteSpy: jest.SpyInstance;
 
 function mockServices(
   existingInterfaces: Array<NetworkInterface> = [],
@@ -119,6 +123,19 @@ function mockServices(
   endpointUpsertSpy = jest
     .spyOn(NetworkEndpointService, "upsertDiscoveredEndpoints")
     .mockResolvedValue(undefined as never);
+  /*
+   * Device MAC learning follows the endpoint upsert on any walk that
+   * carried ARP bindings: one findBy for the devices registered at the
+   * bound addresses, then a hook-free compare-and-set write per device the
+   * planner picked. Stubbed here so the ARP cases never reach a database;
+   * the learning block seeds findBy with real rows where it matters.
+   */
+  deviceLookupSpy = jest
+    .spyOn(NetworkDeviceService, "findBy")
+    .mockResolvedValue([]);
+  macWriteSpy = jest
+    .spyOn(NetworkDeviceService, "updateColumnsByIdWithoutHooks")
+    .mockResolvedValue(undefined);
 }
 
 function deviceUpdatePayload(): DeviceUpdatePayload {
@@ -1101,6 +1118,306 @@ describe("NetworkInventoryUtil.updateFromWalk — endpoint discovery", () => {
   });
 });
 
+/*
+ * A walked router's ARP table binds the address a managed device is
+ * registered at to the MAC the switches learned - the one fact a ping-only
+ * register or handset never reports about itself. After the endpoint
+ * inventory is written, the walk hands those bindings to
+ * NetworkDeviceMacLearningUtil, which stamps the MAC on the device row while
+ * its column is still empty. The planner's rules are pinned in
+ * Tests/Utils/Monitor/DeviceMacLearningUtil.test.ts and the database contract
+ * in Tests/Server/Utils/Monitor/NetworkDeviceMacLearningUtil.test.ts; what is
+ * pinned HERE is the hand-off from the walk: when learning runs, what it is
+ * scoped by, and that a failure in it stays in it.
+ */
+describe("NetworkInventoryUtil.updateFromWalk — device MAC learning", () => {
+  const SITE_ID: ObjectID = new ObjectID(
+    "5a5a5a5a-0000-4000-8000-00000000000a",
+  );
+  const OTHER_SITE_ID: ObjectID = new ObjectID(
+    "5b5b5b5b-0000-4000-8000-00000000000b",
+  );
+  const REGISTER_ID: string = "8f2c1f0e-0000-4000-8000-0000000000bb";
+  const HANDSET_ID: string = "8f2c1f0e-0000-4000-8000-0000000000cc";
+  const REGISTER_IP: string = "10.0.0.5";
+  const REGISTER_MAC: string = "aa:bb:cc:00:11:22";
+
+  // A managed, ping-only device registered at the address the router bound.
+  function registeredDevice(
+    id: string,
+    overrides?: { siteId?: ObjectID; macAddress?: string },
+  ): NetworkDevice {
+    const row: NetworkDevice = new NetworkDevice();
+    row.id = new ObjectID(id);
+    row.hostname = REGISTER_IP;
+    if (overrides?.siteId) {
+      row.siteId = overrides.siteId;
+    }
+    if (overrides?.macAddress !== undefined) {
+      row.macAddress = overrides.macAddress;
+    }
+    return row;
+  }
+
+  // The ARP table spelling differs from the column's: learning normalizes.
+  function arpWalk(): Partial<SnmpMonitorResponse> {
+    return {
+      arpEntries: [
+        {
+          ipAddress: REGISTER_IP,
+          macAddress: "AA-BB-CC-00-11-22",
+          interfaceIndex: 3,
+          entryType: "dynamic",
+        },
+      ],
+    };
+  }
+
+  /*
+   * The addresses the device lookup asked about. QueryHelper.any renders
+   * them into a TypeORM Raw operator with a RANDOM parameter name, so the
+   * list is recovered from the operator's parameters.
+   */
+  function addressesLookedUp(): Array<string> {
+    const query: JSONObject = (deviceLookupSpy.mock.calls[0]![0] as JSONObject)[
+      "query"
+    ] as JSONObject;
+    const operator: FindOperator<string> = query[
+      "hostname"
+    ] as unknown as FindOperator<string>;
+    const parameters: Record<string, unknown> =
+      (operator.objectLiteralParameters || {}) as Record<string, unknown>;
+    const values: Array<unknown> =
+      (Object.values(parameters)[0] as Array<unknown>) || [];
+    return values.map((value: unknown): string => {
+      return String(value);
+    });
+  }
+
+  function spyError(): jest.SpyInstance {
+    return jest.spyOn(logger, "error").mockImplementation(() => {
+      return undefined;
+    });
+  }
+
+  test("a walk carrying an ARP entry looks up the devices at the bound address, in the walked device's project", async () => {
+    mockServices([], { siteId: SITE_ID });
+    deviceLookupSpy.mockResolvedValue([
+      registeredDevice(REGISTER_ID, { siteId: SITE_ID }),
+    ]);
+
+    await runWalk(arpWalk());
+
+    expect(deviceLookupSpy).toHaveBeenCalledTimes(1);
+
+    const query: JSONObject = (deviceLookupSpy.mock.calls[0]![0] as JSONObject)[
+      "query"
+    ] as JSONObject;
+
+    expect((query["projectId"] as ObjectID).toString()).toBe(PROJECT_ID);
+    expect(addressesLookedUp()).toEqual([REGISTER_IP]);
+  });
+
+  test("a device with an empty MAC in the router's site is stamped through the hook-free compare-and-set write", async () => {
+    mockServices([], { siteId: SITE_ID });
+    deviceLookupSpy.mockResolvedValue([
+      registeredDevice(REGISTER_ID, { siteId: SITE_ID }),
+    ]);
+
+    await runWalk(arpWalk());
+
+    expect(macWriteSpy).toHaveBeenCalledTimes(1);
+
+    const write: JSONObject = macWriteSpy.mock.calls[0]![0] as JSONObject;
+
+    expect((write["id"] as ObjectID).toString()).toBe(REGISTER_ID);
+    expect(write["data"]).toEqual({
+      macAddress: REGISTER_MAC,
+      isMacAddressLearned: true,
+    });
+    expect(write["expectedData"]).toEqual({
+      macAddress: null,
+      deletedAt: null,
+    });
+    // The walked router's own row is untouched by learning.
+    expect(deviceUpdateSpy).toHaveBeenCalledTimes(1);
+    expect(deviceUpdatePayload()).not.toHaveProperty("macAddress");
+  });
+
+  test("learning runs after the endpoint inventory has been written", async () => {
+    mockServices([], { siteId: SITE_ID });
+
+    await runWalk(arpWalk());
+
+    expect(endpointUpsertSpy).toHaveBeenCalledTimes(1);
+    expect(deviceLookupSpy).toHaveBeenCalledTimes(1);
+    expect(endpointUpsertSpy.mock.invocationCallOrder[0]!).toBeLessThan(
+      deviceLookupSpy.mock.invocationCallOrder[0]!,
+    );
+  });
+
+  test("a walk with FDB entries only never looks devices up", async () => {
+    mockServices([], { siteId: SITE_ID });
+
+    await runWalk({
+      interfaces: [walkedInterface({ interfaceIndex: 5, name: "Gi0/5" })],
+      fdbEntries: [
+        {
+          macAddress: REGISTER_MAC,
+          bridgePort: 5,
+          interfaceIndex: 5,
+          status: "learned",
+        },
+      ],
+    });
+
+    // The attachment was still written; only the ARP half was absent.
+    expect(endpointUpsertSpy).toHaveBeenCalledTimes(1);
+    expect(deviceLookupSpy).not.toHaveBeenCalled();
+    expect(macWriteSpy).not.toHaveBeenCalled();
+  });
+
+  test("a walk without endpoint arrays at all never looks devices up", async () => {
+    mockServices([], { siteId: SITE_ID });
+
+    await runWalk({ interfaces: [walkedInterface()] });
+
+    expect(deviceLookupSpy).not.toHaveBeenCalled();
+    expect(macWriteSpy).not.toHaveBeenCalled();
+  });
+
+  /*
+   * Learning keys off the bindings the attachment pass KEPT, not the raw
+   * ARP rows: an entry for the router's own interface MAC is dropped there
+   * and must not come back as a lookup here.
+   */
+  test("an ARP entry the attachment pass discards never reaches learning", async () => {
+    mockServices([], { siteId: SITE_ID });
+
+    await runWalk({
+      interfaces: [
+        walkedInterface({ interfaceIndex: 3, macAddress: REGISTER_MAC }),
+      ],
+      ...arpWalk(),
+    });
+
+    expect(endpointUpsertSpy).not.toHaveBeenCalled();
+    expect(deviceLookupSpy).not.toHaveBeenCalled();
+    expect(macWriteSpy).not.toHaveBeenCalled();
+  });
+
+  test("a failure in the learning step is logged and does not prevent the walk from completing", async () => {
+    mockServices([], { siteId: SITE_ID });
+    deviceLookupSpy.mockRejectedValue(new Error("connection reset"));
+    const error: jest.SpyInstance = spyError();
+
+    const snmpResponse: SnmpMonitorResponse = await runWalk(arpWalk());
+
+    // Nothing escaped, and everything before the learning step landed.
+    expect(snmpResponse).toBeDefined();
+    expect(deviceUpdateSpy).toHaveBeenCalledTimes(1);
+    expect(endpointUpsertSpy).toHaveBeenCalledTimes(1);
+    expect(macWriteSpy).not.toHaveBeenCalled();
+
+    const messages: Array<string> = error.mock.calls.map(
+      (call: Array<unknown>) => {
+        return String(call[0]);
+      },
+    );
+
+    /*
+     * Its OWN catch, naming the device - never the outer "failed to update
+     * network inventory" line, which would read as the endpoint upsert
+     * having failed too.
+     */
+    expect(
+      messages.some((message: string) => {
+        return message.includes("MAC") && message.includes(DEVICE_ID);
+      }),
+    ).toBe(true);
+    expect(
+      messages.some((message: string) => {
+        return message.includes("Failed to update network inventory");
+      }),
+    ).toBe(false);
+  });
+
+  test("a failing MAC write is contained the same way", async () => {
+    mockServices([], { siteId: SITE_ID });
+    deviceLookupSpy.mockResolvedValue([
+      registeredDevice(REGISTER_ID, { siteId: SITE_ID }),
+    ]);
+    macWriteSpy.mockRejectedValue(new Error("deadlock detected"));
+    const error: jest.SpyInstance = spyError();
+
+    await expect(runWalk(arpWalk())).resolves.toBeDefined();
+
+    expect(endpointUpsertSpy).toHaveBeenCalledTimes(1);
+    expect(error).toHaveBeenCalled();
+  });
+
+  test("the observing device's site scopes the match: a device in another site is not stamped", async () => {
+    mockServices([], { siteId: SITE_ID });
+    deviceLookupSpy.mockResolvedValue([
+      registeredDevice(REGISTER_ID, { siteId: OTHER_SITE_ID }),
+    ]);
+
+    await runWalk(arpWalk());
+
+    // Looked up - the read is project-wide by design - but refused.
+    expect(deviceLookupSpy).toHaveBeenCalledTimes(1);
+    expect(macWriteSpy).not.toHaveBeenCalled();
+  });
+
+  test("an observing device with no site stamps only a device with no site", async () => {
+    // The default device carries no siteId: a project without sites.
+    mockServices();
+    const siteless: NetworkDevice = registeredDevice(HANDSET_ID);
+    deviceLookupSpy.mockResolvedValue([
+      registeredDevice(REGISTER_ID, { siteId: SITE_ID }),
+    ]);
+
+    await runWalk(arpWalk());
+    expect(macWriteSpy).not.toHaveBeenCalled();
+
+    deviceLookupSpy.mockResolvedValue([siteless]);
+
+    await runWalk(arpWalk());
+    expect(macWriteSpy).toHaveBeenCalledTimes(1);
+    expect(
+      (
+        (macWriteSpy.mock.calls[0]![0] as JSONObject)["id"] as ObjectID
+      ).toString(),
+    ).toBe(HANDSET_ID);
+  });
+
+  test("a device that already carries a MAC is left alone", async () => {
+    mockServices([], { siteId: SITE_ID });
+    deviceLookupSpy.mockResolvedValue([
+      registeredDevice(REGISTER_ID, {
+        siteId: SITE_ID,
+        macAddress: "00:11:22:33:44:55",
+      }),
+    ]);
+
+    await runWalk(arpWalk());
+
+    expect(deviceLookupSpy).toHaveBeenCalledTimes(1);
+    expect(macWriteSpy).not.toHaveBeenCalled();
+  });
+
+  test("selects siteId on the device read, or learning could never scope by site", async () => {
+    mockServices();
+
+    await runWalk();
+
+    const findArgs: { select?: Record<string, boolean> } = deviceFindSpy.mock
+      .calls[0]![0] as unknown as { select?: Record<string, boolean> };
+
+    expect(findArgs.select?.["siteId"]).toBe(true);
+  });
+});
+
 describe("NetworkInventoryUtil.updateFromWalk — vendor health template auto-apply", () => {
   /*
    * The automatic counterpart of the dashboard's vendor-template banner:

package/Tests/Server/Utils/Monitor/SeriesContextEnricher.test.ts

@@ -0,0 +1,356 @@
+import { JSONObject } from "../../../../Types/JSON";
+import MonitorType from "../../../../Types/Monitor/MonitorType";
+import SeriesContextEnricher from "../../../../Server/Utils/Monitor/SeriesContextEnricher";
+
+/*
+ * The regression this enricher exists for:
+ *
+ * A grouped Kubernetes monitor raised 49 alerts on one test cluster, all
+ * titled
+ *
+ *   "[K8s] Pod CPU Saturating Container Limit (>90%) - oneuptime-test -
+ *    Pod CPU Saturating Container Limit"
+ *
+ * character for character. The pod that was actually throttled was known
+ * - it was stored on the alert as seriesLabels - but the title comes
+ * from the criteria template, which is one fixed string shared by every
+ * series, so the alert list, the Slack message and the phone
+ * notification all showed the same undifferentiated line.
+ *
+ * The tests below fix the two halves of that: identity reaches the
+ * title, and it never fights a template the user wrote themselves.
+ */
+
+const POD_LABELS: JSONObject = {
+  "resource.k8s.namespace.name": "prod",
+  "resource.k8s.pod.name": "checkout-7d9f-2xk",
+  "resource.k8s.node.name": "ip-10-0-3-14",
+};
+
+describe("SeriesContextEnricher", () => {
+  describe("enrichTitle", () => {
+    test("appends the series identity to a template-rendered title", () => {
+      expect(
+        SeriesContextEnricher.enrichTitle({
+          title: "[K8s] Pod CPU Saturating Container Limit (>90%)",
+          seriesLabels: POD_LABELS,
+        }),
+      ).toBe(
+        "[K8s] Pod CPU Saturating Container Limit (>90%) - Pod: checkout-7d9f-2xk | Namespace: prod | Node: ip-10-0-3-14",
+      );
+    });
+
+    test("two series of one monitor no longer share a title", () => {
+      const title: string = "[K8s] Pod CPU Saturating Container Limit (>90%)";
+
+      const first: string = SeriesContextEnricher.enrichTitle({
+        title,
+        seriesLabels: {
+          "resource.k8s.namespace.name": "prod",
+          "resource.k8s.pod.name": "checkout-7d9f-2xk",
+        },
+      });
+      const second: string = SeriesContextEnricher.enrichTitle({
+        title,
+        seriesLabels: {
+          "resource.k8s.namespace.name": "prod",
+          "resource.k8s.pod.name": "search-5b2c-9qq",
+        },
+      });
+
+      expect(first).not.toBe(second);
+      expect(first).toContain("checkout-7d9f-2xk");
+      expect(second).toContain("search-5b2c-9qq");
+    });
+
+    test("is a no-op for a monitor with no group-by", () => {
+      const title: string = "[K8s] etcd No Leader";
+
+      expect(
+        SeriesContextEnricher.enrichTitle({ title, seriesLabels: {} }),
+      ).toBe(title);
+      expect(
+        SeriesContextEnricher.enrichTitle({ title, seriesLabels: undefined }),
+      ).toBe(title);
+    });
+
+    test("is a no-op when every label value is empty", () => {
+      /*
+       * A grouped series keeps its keys even when the attribute was
+       * missing, so this is a real shape - and appending " - " to the
+       * title for it would be worse than doing nothing.
+       */
+      const title: string = "Disk usage high";
+
+      expect(
+        SeriesContextEnricher.enrichTitle({
+          title,
+          seriesLabels: { mountpoint: "", device: "" },
+        }),
+      ).toBe(title);
+    });
+
+    test("leaves a title alone when the user's own template already named the series", () => {
+      /*
+       * The user wrote `{{resource.k8s.pod.name}}` into their criteria
+       * title, which has already expanded by the time the enricher runs.
+       * Appending would duplicate the pod name.
+       */
+      const title: string =
+        "Pod checkout-7d9f-2xk in prod is throttled on ip-10-0-3-14";
+
+      expect(
+        SeriesContextEnricher.enrichTitle({ title, seriesLabels: POD_LABELS }),
+      ).toBe(title);
+    });
+
+    test("adds only the labels the title is missing", () => {
+      const enriched: string = SeriesContextEnricher.enrichTitle({
+        title: "Pod checkout-7d9f-2xk is throttled",
+        seriesLabels: POD_LABELS,
+      });
+
+      expect(enriched).toBe(
+        "Pod checkout-7d9f-2xk is throttled - Namespace: prod | Node: ip-10-0-3-14",
+      );
+      // The pod name appears once, not twice.
+      expect(enriched.split("checkout-7d9f-2xk")).toHaveLength(2);
+    });
+
+    test("running twice over its own output changes nothing", () => {
+      const once: string = SeriesContextEnricher.enrichTitle({
+        title: "Pod CPU high",
+        seriesLabels: POD_LABELS,
+      });
+      const twice: string = SeriesContextEnricher.enrichTitle({
+        title: once,
+        seriesLabels: POD_LABELS,
+      });
+
+      expect(twice).toBe(once);
+    });
+
+    test("a threshold in the title does not swallow a short label value", () => {
+      /*
+       * Ceph pool ids and Proxmox vmids are one or two characters. Naive
+       * substring matching answers "does 'Restarts > 3' mention 3?" with
+       * yes, and the alert loses the only thing identifying which pool
+       * broke.
+       */
+      expect(
+        SeriesContextEnricher.enrichTitle({
+          title: "[Ceph] Pool Near Full - restarts > 3",
+          seriesLabels: { pool_id: "3" },
+        }),
+      ).toBe("[Ceph] Pool Near Full - restarts > 3 - Pool: 3");
+    });
+
+    test("a short label value is still idempotent on a second pass", () => {
+      const once: string = SeriesContextEnricher.enrichTitle({
+        title: "[Ceph] Pool Near Full",
+        seriesLabels: { pool_id: "3" },
+      });
+
+      expect(
+        SeriesContextEnricher.enrichTitle({
+          title: once,
+          seriesLabels: { pool_id: "3" },
+        }),
+      ).toBe(once);
+    });
+
+    test("a value embedded inside a longer word does not count as mentioned", () => {
+      /*
+       * A container called `webapp` must not be considered named just
+       * because the title happens to contain the word "webapps".
+       */
+      expect(
+        SeriesContextEnricher.enrichTitle({
+          title: "All webapps are unhealthy",
+          seriesLabels: { "resource.container.name": "webapp" },
+        }),
+      ).toBe("All webapps are unhealthy - Container: webapp");
+    });
+
+    test("a value on a token boundary does count as mentioned", () => {
+      const title: string = "Container checkout-7d9f-2xk is unhealthy";
+
+      expect(
+        SeriesContextEnricher.enrichTitle({
+          title,
+          seriesLabels: { "resource.k8s.pod.name": "checkout-7d9f-2xk" },
+        }),
+      ).toBe(title);
+    });
+
+    test("never overflows the title column", () => {
+      /*
+       * `Alert.title` and `Incident.title` are LongText (500). An
+       * overflow does not shorten the title - it fails the INSERT, and
+       * the alert does not exist at all. A labelling improvement must
+       * never turn into a dropped page.
+       */
+      const longValue: string = "x".repeat(250);
+
+      const enriched: string = SeriesContextEnricher.enrichTitle({
+        title: `[K8s] ${"y".repeat(300)}`,
+        seriesLabels: {
+          "resource.k8s.pod.name": longValue,
+          "resource.k8s.namespace.name": longValue,
+          "resource.k8s.node.name": longValue,
+        },
+      });
+
+      expect(enriched.length).toBeLessThanOrEqual(500);
+    });
+
+    test("leaves an already-oversized title exactly as the user wrote it", () => {
+      /*
+       * Such a title was going to fail with or without this enricher.
+       * Silently truncating what the user wrote is not this module's
+       * call to make.
+       */
+      const title: string = "z".repeat(600);
+
+      expect(
+        SeriesContextEnricher.enrichTitle({
+          title,
+          seriesLabels: { "resource.k8s.pod.name": "web-1" },
+        }),
+      ).toBe(title);
+    });
+
+    test("handles an empty title without producing a leading separator", () => {
+      expect(
+        SeriesContextEnricher.enrichTitle({
+          title: "",
+          seriesLabels: { "resource.k8s.pod.name": "web-1" },
+        }),
+      ).toBe(" - Pod: web-1");
+    });
+  });
+
+  describe("enrichDescription", () => {
+    test("appends the full resource block and the first commands", () => {
+      const enriched: string = SeriesContextEnricher.enrichDescription({
+        description: "A pod's CPU usage has exceeded 90% of its limit.",
+        seriesLabels: POD_LABELS,
+        monitorType: MonitorType.Kubernetes,
+      });
+
+      expect(enriched).toContain(
+        "A pod's CPU usage has exceeded 90% of its limit.",
+      );
+      expect(enriched).toContain("**Affected resource**");
+      expect(enriched).toContain("- **Pod:** `checkout-7d9f-2xk`");
+      expect(enriched).toContain("- **Namespace:** `prod`");
+      expect(enriched).toContain("- **Node:** `ip-10-0-3-14`");
+      expect(enriched).toContain("**Start here**");
+      expect(enriched).toContain(
+        "kubectl describe pod checkout-7d9f-2xk -n prod",
+      );
+    });
+
+    test("lists EVERY label, not just the three that fit in a title", () => {
+      const enriched: string = SeriesContextEnricher.enrichDescription({
+        description: "Throttled.",
+        seriesLabels: {
+          ...POD_LABELS,
+          "resource.k8s.container.name": "app",
+          "resource.k8s.cluster.name": "prod-eu",
+        },
+        monitorType: MonitorType.Kubernetes,
+      });
+
+      expect(enriched).toContain("- **Container:** `app`");
+      expect(enriched).toContain("- **Cluster:** `prod-eu`");
+    });
+
+    test("is a no-op for a monitor with no group-by", () => {
+      const description: string = "etcd has no leader.";
+
+      expect(
+        SeriesContextEnricher.enrichDescription({
+          description,
+          seriesLabels: {},
+          monitorType: MonitorType.Kubernetes,
+        }),
+      ).toBe(description);
+      expect(
+        SeriesContextEnricher.enrichDescription({
+          description,
+          seriesLabels: undefined,
+          monitorType: MonitorType.Kubernetes,
+        }),
+      ).toBe(description);
+    });
+
+    test("skips the resource block when the description already names every label", () => {
+      const description: string =
+        "Pod checkout-7d9f-2xk in prod on ip-10-0-3-14 is throttled.";
+
+      const enriched: string = SeriesContextEnricher.enrichDescription({
+        description,
+        seriesLabels: POD_LABELS,
+        monitorType: MonitorType.Kubernetes,
+      });
+
+      expect(enriched).not.toContain("**Affected resource**");
+      // The commands are still added - they are not a restatement.
+      expect(enriched).toContain("**Start here**");
+    });
+
+    test("still adds commands for a monitor type that has them, and none for one that does not", () => {
+      const withCommands: string = SeriesContextEnricher.enrichDescription({
+        description: "High CPU.",
+        seriesLabels: { "resource.container.name": "nginx" },
+        monitorType: MonitorType.Docker,
+      });
+      const withoutCommands: string = SeriesContextEnricher.enrichDescription({
+        description: "High latency.",
+        seriesLabels: { "service.name": "checkout-api" },
+        monitorType: MonitorType.Metrics,
+      });
+
+      expect(withCommands).toContain("docker logs --tail 200 nginx");
+      expect(withoutCommands).not.toContain("**Start here**");
+      // ...but the resource identity is still there.
+      expect(withoutCommands).toContain("- **Service:** `checkout-api`");
+    });
+
+    test("running twice adds nothing the second time", () => {
+      const once: string = SeriesContextEnricher.enrichDescription({
+        description: "Throttled.",
+        seriesLabels: POD_LABELS,
+        monitorType: MonitorType.Kubernetes,
+      });
+      const twice: string = SeriesContextEnricher.enrichDescription({
+        description: once,
+        seriesLabels: POD_LABELS,
+        monitorType: MonitorType.Kubernetes,
+      });
+
+      expect(twice).toBe(once);
+    });
+
+    test("an empty description becomes the blocks alone, with no leading blank lines", () => {
+      const enriched: string = SeriesContextEnricher.enrichDescription({
+        description: "",
+        seriesLabels: { "resource.k8s.pod.name": "web-1" },
+        monitorType: MonitorType.Kubernetes,
+      });
+
+      expect(enriched.startsWith("**Affected resource**")).toBe(true);
+    });
+
+    test("separates the original description from the appended blocks", () => {
+      const enriched: string = SeriesContextEnricher.enrichDescription({
+        description: "Throttled.",
+        seriesLabels: { "resource.k8s.pod.name": "web-1" },
+        monitorType: MonitorType.Kubernetes,
+      });
+
+      expect(enriched).toContain("Throttled.\n\n**Affected resource**");
+    });
+  });
+});