@oneuptime/common 14.0.2 → 14.0.3

package/Tests/App/Dashboard/LinkIncidentAlertModal.test.tsx

@@ -0,0 +1,154 @@
+import "@testing-library/jest-dom";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  jest,
+  test,
+} from "@jest/globals";
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import * as React from "react";
+import { MemoryRouter } from "react-router-dom";
+
+/*
+ * The shared link dialog, rendered for real (BasicFormModal, BasicForm and
+ * the entity dropdown included): it shows a loader while the recent records
+ * are fetched, then the picker with its label and help text, inside a modal
+ * carrying the page's title, description and submit button. The flows
+ * behind it are covered with a stubbed modal in
+ * IncidentAlertLinkDialog.test.tsx and BulkIncidentLinkActions.test.tsx.
+ */
+
+jest.mock("react-i18next", () => {
+  return {
+    useTranslation: () => {
+      return {
+        t: (key: string, opts?: { defaultValue?: string }): string => {
+          return opts?.defaultValue ?? key;
+        },
+      };
+    },
+  };
+});
+
+import LinkIncidentAlertModal from "../../../../App/FeatureSet/Dashboard/src/Components/IncidentAlert/LinkIncidentAlertModal";
+import Alert from "../../../Models/DatabaseModels/Alert";
+import { DropdownOption } from "../../../UI/Components/Dropdown/Dropdown";
+
+type Deferred = {
+  promise: Promise<Array<DropdownOption>>;
+  resolve: (options: Array<DropdownOption>) => void;
+};
+
+type MakeDeferredFunction = () => Deferred;
+
+const makeDeferred: MakeDeferredFunction = (): Deferred => {
+  let resolve: (options: Array<DropdownOption>) => void = (): void => {};
+  const promise: Promise<Array<DropdownOption>> = new Promise<
+    Array<DropdownOption>
+  >((done: (options: Array<DropdownOption>) => void): void => {
+    resolve = done;
+  });
+
+  return { promise, resolve };
+};
+
+describe("LinkIncidentAlertModal", () => {
+  let deferred: Deferred;
+  let loadOptionCalls: number = 0;
+
+  beforeEach(() => {
+    deferred = makeDeferred();
+    loadOptionCalls = 0;
+  });
+
+  afterEach(() => {
+    cleanup();
+    jest.restoreAllMocks();
+  });
+
+  test("shows a loader until the recent records arrive, then the picker", async () => {
+    render(
+      <MemoryRouter>
+        <LinkIncidentAlertModal
+          title="Link Alert"
+          description="Select an alert to link to this incident."
+          submitButtonText="Link Alert"
+          fieldTitle="Alert"
+          fieldDescription="Recent alerts are listed with their number. Type to search every alert by title."
+          placeholder="Select an alert"
+          modelType={Alert}
+          loadOptions={(): Promise<Array<DropdownOption>> => {
+            loadOptionCalls++;
+            return deferred.promise;
+          }}
+          onSubmit={async (): Promise<void> => {
+            return Promise.resolve();
+          }}
+          onClose={(): void => {}}
+        />
+      </MemoryRouter>,
+    );
+
+    // The modal's title and its submit button.
+    expect(screen.getAllByText("Link Alert")).toHaveLength(2);
+    expect(
+      screen.getByText("Select an alert to link to this incident."),
+    ).toBeInTheDocument();
+    expect(loadOptionCalls).toBe(1);
+    expect(
+      screen.queryByText(
+        "Recent alerts are listed with their number. Type to search every alert by title.",
+      ),
+    ).not.toBeInTheDocument();
+
+    deferred.resolve([
+      { label: "ALT-63: Checkout API is offline", value: "a-63" },
+    ]);
+
+    await waitFor(() => {
+      expect(
+        screen.getByText(
+          "Recent alerts are listed with their number. Type to search every alert by title.",
+        ),
+      ).toBeInTheDocument();
+    });
+
+    expect(screen.getAllByText("Alert").length).toBeGreaterThan(0);
+    expect(loadOptionCalls).toBe(1);
+  });
+
+  test("still shows the picker when the recent records cannot be read", async () => {
+    render(
+      <MemoryRouter>
+        <LinkIncidentAlertModal
+          title="Link Incident"
+          description="Select an incident to link this alert to."
+          submitButtonText="Link Incident"
+          fieldTitle="Incident"
+          fieldDescription="Recent incidents are listed with their number. Type to search every incident by title."
+          placeholder="Select an incident"
+          modelType={Alert}
+          loadOptions={async (): Promise<Array<DropdownOption>> => {
+            throw new Error("Forbidden");
+          }}
+          onSubmit={async (): Promise<void> => {
+            return Promise.resolve();
+          }}
+          onClose={(): void => {}}
+        />
+      </MemoryRouter>,
+    );
+
+    await waitFor(() => {
+      expect(
+        screen.getByText(
+          "Recent incidents are listed with their number. Type to search every incident by title.",
+        ),
+      ).toBeInTheDocument();
+    });
+
+    expect(screen.queryByText("Forbidden")).not.toBeInTheDocument();
+  });
+});

package/Tests/App/Dashboard/MetricDescriptionRules.ts

@@ -0,0 +1,170 @@
+import { expect } from "@jest/globals";
+
+/*
+ * The rules every metric explanation in the dashboard is held to - the text
+ * a customer reads in the (i) tooltip beside a tile, chart or column title.
+ * Shared by the per-resource tests and by MetricDescriptionsCatalog.test.ts,
+ * which applies them to every module under
+ * App/FeatureSet/Dashboard/src/Components/MetricDescriptions.
+ *
+ * Not a test file itself (no .test. in the name), so jest does not run it.
+ */
+
+export const MIN_DESCRIPTION_LENGTH: number = 25;
+// A tooltip is 350px wide; past ~340 characters it stops being "small".
+export const MAX_DESCRIPTION_LENGTH: number = 340;
+
+/*
+ * Words that give away a placeholder or an unfinished sentence rather than
+ * an explanation.
+ */
+const PLACEHOLDER_PATTERN: RegExp = /\b(TODO|TBD|FIXME|lorem|ipsum|XXX)\b/i;
+const DOUBLE_SPACE_PATTERN: RegExp = /\s{2,}/;
+const SENTENCE_END_PATTERN: RegExp = /[.!?)"']$/;
+// A sentence, or a percentile token such as "p95 means ...".
+const SENTENCE_START_PATTERN: RegExp = /^(p\d{2}\b|[A-Z0-9"'(])/;
+const LEAKED_VALUE_PATTERN: RegExp =
+  /\bundefined\b|\bnull\b|\bNaN\b|\[object Object\]/;
+
+/*
+ * A percentile named in the text has to be explained in the same text - the
+ * whole point of the tooltip is that "p95" means nothing to most readers.
+ */
+const PERCENTILE_EXPLANATIONS: Array<{
+  token: RegExp;
+  explained: RegExp;
+  name: string;
+}> = [
+  {
+    token: /\bp50\b/i,
+    explained: /(50%|half|median|typical)/i,
+    name: "p50",
+  },
+  {
+    token: /\bp75\b/i,
+    explained: /(75%|75th)/,
+    name: "p75",
+  },
+  {
+    token: /\bp90\b/i,
+    explained: /(90%|90th)/,
+    name: "p90",
+  },
+  {
+    token: /\bp95\b/i,
+    explained: /(95%|95th)/,
+    name: "p95",
+  },
+  {
+    token: /\bp99\b/i,
+    explained: /(99%|99th)/,
+    name: "p99",
+  },
+];
+
+export function metricDescriptionProblems(text: unknown): Array<string> {
+  const problems: Array<string> = [];
+
+  if (typeof text !== "string") {
+    return [`is not a string (${typeof text})`];
+  }
+
+  if (text !== text.trim()) {
+    problems.push("has leading or trailing whitespace");
+  }
+
+  if (text.length < MIN_DESCRIPTION_LENGTH) {
+    problems.push(`is too short to explain anything (${text.length} chars)`);
+  }
+
+  if (text.length > MAX_DESCRIPTION_LENGTH) {
+    problems.push(
+      `is too long for a small tooltip (${text.length} > ${MAX_DESCRIPTION_LENGTH} chars)`,
+    );
+  }
+
+  if (DOUBLE_SPACE_PATTERN.test(text)) {
+    problems.push("contains a double space or a line break");
+  }
+
+  if (!SENTENCE_END_PATTERN.test(text.trim())) {
+    problems.push("does not end like a sentence");
+  }
+
+  if (!SENTENCE_START_PATTERN.test(text.trim())) {
+    problems.push("does not start like a sentence");
+  }
+
+  if (PLACEHOLDER_PATTERN.test(text)) {
+    problems.push("contains placeholder text");
+  }
+
+  if (LEAKED_VALUE_PATTERN.test(text)) {
+    problems.push("contains a leaked programming value");
+  }
+
+  for (const percentile of PERCENTILE_EXPLANATIONS) {
+    if (percentile.token.test(text) && !percentile.explained.test(text)) {
+      problems.push(`names ${percentile.name} without explaining it`);
+    }
+  }
+
+  return problems;
+}
+
+export function expectReadableMetricDescription(
+  text: unknown,
+  context: string,
+): void {
+  expect({ context, problems: metricDescriptionProblems(text) }).toEqual({
+    context,
+    problems: [],
+  });
+}
+
+/*
+ * Every value of a description record passes the rules, and no two metrics
+ * on one page borrow the same words.
+ */
+export function expectReadableDescriptionRecord(
+  record: Record<string, unknown>,
+  context: string,
+): void {
+  const entries: Array<[string, unknown]> = Object.entries(record);
+
+  expect(entries.length).toBeGreaterThan(0);
+
+  for (const [key, text] of entries) {
+    expectReadableMetricDescription(text, `${context}.${key}`);
+  }
+
+  const seen: Map<string, string> = new Map<string, string>();
+  const duplicates: Array<string> = [];
+
+  for (const [key, text] of entries) {
+    const previous: string | undefined = seen.get(String(text));
+
+    if (previous) {
+      duplicates.push(`${context}.${key} repeats ${context}.${previous}`);
+    } else {
+      seen.set(String(text), key);
+    }
+  }
+
+  expect(duplicates).toEqual([]);
+}
+
+/*
+ * A title that names a percentile gets a description that explains it -
+ * the tile "p95 duration" cannot be explained by "How long requests took."
+ */
+export function expectTitleExplained(title: string, text: string): void {
+  for (const percentile of PERCENTILE_EXPLANATIONS) {
+    if (percentile.token.test(title)) {
+      expect({ title, explains: percentile.explained.test(text) }).toEqual({
+        title,
+        explains: true,
+      });
+    }
+  }
+}

package/Tests/App/Dashboard/MetricDescriptionsCatalog.test.ts

@@ -0,0 +1,206 @@
+import { describe, expect, test } from "@jest/globals";
+import fs from "fs";
+import path from "path";
+import {
+  expectReadableDescriptionRecord,
+  metricDescriptionProblems,
+} from "./MetricDescriptionRules";
+
+/*
+ * Every metric-explanation module in the dashboard, found on disk rather
+ * than listed by hand, so a new resource type's descriptions are held to the
+ * same rules the day they are added. Each module exports one or more
+ * Record<string, string> of tooltip texts.
+ */
+
+const DESCRIPTIONS_DIR: string = path.join(
+  __dirname,
+  "..",
+  "..",
+  "..",
+  "..",
+  "App",
+  "FeatureSet",
+  "Dashboard",
+  "src",
+  "Components",
+  "MetricDescriptions",
+);
+
+const MODULE_FILES: Array<string> = fs
+  .readdirSync(DESCRIPTIONS_DIR)
+  .filter((file: string): boolean => {
+    return file.endsWith(".ts") && !file.endsWith(".d.ts");
+  })
+  .sort();
+
+const DASHBOARD_SRC: string = path.join(DESCRIPTIONS_DIR, "..", "..");
+const SOURCE_FILE_PATTERN: RegExp = /\.(ts|tsx)$/;
+
+function listSources(directory: string): Array<string> {
+  const files: Array<string> = [];
+
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    const full: string = path.join(directory, entry.name);
+
+    if (entry.isDirectory()) {
+      files.push(...listSources(full));
+    } else if (SOURCE_FILE_PATTERN.test(entry.name)) {
+      files.push(full);
+    }
+  }
+
+  return files;
+}
+
+// Every dashboard source except the description modules themselves.
+const DASHBOARD_SOURCES: Array<string> = listSources(DASHBOARD_SRC)
+  .filter((file: string): boolean => {
+    return path.dirname(file) !== DESCRIPTIONS_DIR;
+  })
+  .map((file: string): string => {
+    return fs.readFileSync(file, "utf8");
+  });
+
+type DescriptionModule = Record<string, unknown>;
+
+function loadModule(file: string): DescriptionModule {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+  return require(path.join(DESCRIPTIONS_DIR, file)) as DescriptionModule;
+}
+
+function descriptionRecords(
+  module: DescriptionModule,
+): Array<[string, Record<string, unknown>]> {
+  return Object.entries(module).filter(
+    (entry: [string, unknown]): entry is [string, Record<string, unknown>] => {
+      const value: unknown = entry[1];
+
+      return (
+        Boolean(value) &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        Object.values(value as Record<string, unknown>).every(
+          (v: unknown): boolean => {
+            return typeof v === "string";
+          },
+        )
+      );
+    },
+  );
+}
+
+describe("metric description modules", () => {
+  test("the directory exists and holds modules", () => {
+    expect(MODULE_FILES.length).toBeGreaterThan(0);
+    expect(MODULE_FILES).toContain("RumMetricDescriptions.ts");
+  });
+
+  test.each(MODULE_FILES)(
+    "%s is plain data - no React, no API client",
+    (file: string) => {
+      const source: string = fs.readFileSync(
+        path.join(DESCRIPTIONS_DIR, file),
+        "utf8",
+      );
+
+      /*
+       * The App suite imports these from a node test; anything that reaches
+       * react or Common/UI/Config would break it.
+       */
+      expect(source).not.toMatch(/from\s+["']react["']/);
+      expect(source).not.toMatch(/Common\/UI\//);
+      expect(source).not.toMatch(/\.tsx["']/);
+    },
+  );
+
+  test.each(MODULE_FILES)(
+    "%s exports at least one description record",
+    (file: string) => {
+      expect(descriptionRecords(loadModule(file)).length).toBeGreaterThan(0);
+    },
+  );
+
+  test.each(MODULE_FILES)(
+    "%s: every description reads as a short, finished, jargon-explaining sentence",
+    (file: string) => {
+      for (const [exportName, record] of descriptionRecords(loadModule(file))) {
+        expectReadableDescriptionRecord(record, `${file}:${exportName}`);
+      }
+    },
+  );
+
+  /*
+   * A description nobody reads is either a tile that lost its tooltip or
+   * text for a metric that no longer exists. Every key has to be referenced
+   * from a page or component as RECORD.key.
+   */
+  test.each(MODULE_FILES)(
+    "%s: every description is shown somewhere in the dashboard",
+    (file: string) => {
+      const unused: Array<string> = [];
+
+      for (const [exportName, record] of descriptionRecords(loadModule(file))) {
+        for (const key of Object.keys(record)) {
+          const reference: RegExp = new RegExp(
+            `\\b${exportName}\\s*(\\.\\s*${key}\\b|\\[\\s*["']${key}["']\\s*\\])`,
+          );
+
+          if (
+            !DASHBOARD_SOURCES.some((source: string): boolean => {
+              return reference.test(source);
+            })
+          ) {
+            unused.push(`${exportName}.${key}`);
+          }
+        }
+      }
+
+      expect(unused).toEqual([]);
+    },
+  );
+});
+
+describe("the rules themselves", () => {
+  test("accept a good explanation", () => {
+    expect(
+      metricDescriptionProblems(
+        "p95 means 95% of requests finished faster than this, and the slowest 5% took longer.",
+      ),
+    ).toEqual([]);
+  });
+
+  test("reject a percentile that is named but not explained", () => {
+    expect(
+      metricDescriptionProblems("The p95 latency of requests in the range."),
+    ).toContain("names p95 without explaining it");
+    expect(
+      metricDescriptionProblems("The p99 latency of requests in the range."),
+    ).toContain("names p99 without explaining it");
+    expect(
+      metricDescriptionProblems("The p50 latency of requests in the range."),
+    ).toContain("names p50 without explaining it");
+  });
+
+  test("reject placeholders, leaked values and unfinished text", () => {
+    expect(
+      metricDescriptionProblems("TODO explain this metric properly."),
+    ).toContain("contains placeholder text");
+    expect(
+      metricDescriptionProblems("The value is undefined for this resource."),
+    ).toContain("contains a leaked programming value");
+    expect(
+      metricDescriptionProblems("How long requests took on this service"),
+    ).toContain("does not end like a sentence");
+    expect(metricDescriptionProblems("CPU.")).toContain(
+      "is too short to explain anything (4 chars)",
+    );
+    expect(
+      metricDescriptionProblems(`${"Long words. ".repeat(40)}`.trim()),
+    ).toEqual(expect.arrayContaining([expect.stringContaining("is too long")]));
+    expect(
+      metricDescriptionProblems("Share of  requests that failed in the range."),
+    ).toContain("contains a double space or a line break");
+    expect(metricDescriptionProblems(42)).toEqual(["is not a string (number)"]);
+  });
+});