@oneuptime/common 11.5.8 → 11.5.10

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

@@ -0,0 +1,247 @@
+import { describe, expect, test } from "@jest/globals";
+import SnmpAuthProtocol, {
+  SnmpAuthProtocolUtil,
+} from "../../../Types/Monitor/SnmpMonitor/SnmpAuthProtocol";
+import SnmpPrivProtocol, {
+  SnmpPrivProtocolUtil,
+} from "../../../Types/Monitor/SnmpMonitor/SnmpPrivProtocol";
+import SnmpSecurityLevel, {
+  SnmpSecurityLevelUtil,
+} from "../../../Types/Monitor/SnmpMonitor/SnmpSecurityLevel";
+
+/*
+ * These three columns are free text with no check constraint, so the parsers
+ * are the only thing standing between a hand-written row and a silent security
+ * downgrade. Two properties matter and are tested separately throughout:
+ *
+ *   - parse() recognizes every spelling a human or API caller plausibly writes,
+ *     so a legitimate value is never mistaken for garbage.
+ *   - parse() returns undefined for anything else, and isUnrecognized() tells
+ *     "unset" apart from "unreadable", so callers can refuse to guess.
+ */
+
+describe("SnmpSecurityLevelUtil.parse", () => {
+  test.each([
+    ["noAuthNoPriv", SnmpSecurityLevel.NoAuthNoPriv],
+    ["authNoPriv", SnmpSecurityLevel.AuthNoPriv],
+    ["authPriv", SnmpSecurityLevel.AuthPriv],
+  ])(
+    "reads the stored value %s",
+    (stored: string, expected: SnmpSecurityLevel) => {
+      expect(SnmpSecurityLevelUtil.parse(stored)).toBe(expected);
+    },
+  );
+
+  /*
+   * The enum KEYS differ from the values only in the first letter's case, and
+   * the API reference documents the level in prose, so "AuthPriv" is exactly
+   * what a hand-written row tends to contain. Reading it as unrecognized would
+   * be survivable; reading it as noAuthNoPriv — which the old bare cast did —
+   * strips the device's credentials and polls it in cleartext.
+   */
+  test.each([
+    ["NoAuthNoPriv", SnmpSecurityLevel.NoAuthNoPriv],
+    ["AuthNoPriv", SnmpSecurityLevel.AuthNoPriv],
+    ["AuthPriv", SnmpSecurityLevel.AuthPriv],
+  ])(
+    "reads the enum key spelling %s",
+    (stored: string, expected: SnmpSecurityLevel) => {
+      expect(SnmpSecurityLevelUtil.parse(stored)).toBe(expected);
+    },
+  );
+
+  test.each([
+    ["AUTHPRIV", SnmpSecurityLevel.AuthPriv],
+    ["authpriv", SnmpSecurityLevel.AuthPriv],
+    ["AuThPrIv", SnmpSecurityLevel.AuthPriv],
+    ["  authPriv  ", SnmpSecurityLevel.AuthPriv],
+    ["\tauthPriv\n", SnmpSecurityLevel.AuthPriv],
+  ])(
+    "tolerates case and surrounding whitespace in %j",
+    (stored: string, expected: SnmpSecurityLevel) => {
+      expect(SnmpSecurityLevelUtil.parse(stored)).toBe(expected);
+    },
+  );
+
+  test.each([[undefined], [null], [""], ["   "]])(
+    "returns undefined for the unset value %j",
+    (stored: string | undefined | null) => {
+      expect(SnmpSecurityLevelUtil.parse(stored)).toBeUndefined();
+    },
+  );
+
+  test.each([["nonsense"], ["auth"], ["priv"], ["authpriv2"], ["no"], ["0"]])(
+    "returns undefined for the unrecognized value %j",
+    (stored: string) => {
+      expect(SnmpSecurityLevelUtil.parse(stored)).toBeUndefined();
+    },
+  );
+});
+
+describe("SnmpAuthProtocolUtil.parse", () => {
+  test.each([
+    ["MD5", SnmpAuthProtocol.MD5],
+    ["SHA", SnmpAuthProtocol.SHA],
+    ["SHA256", SnmpAuthProtocol.SHA256],
+    ["SHA512", SnmpAuthProtocol.SHA512],
+  ])(
+    "reads the stored value %s",
+    (stored: string, expected: SnmpAuthProtocol) => {
+      expect(SnmpAuthProtocolUtil.parse(stored)).toBe(expected);
+    },
+  );
+
+  /*
+   * The form labels these "SHA-256" and "SHA-512" while storing them without
+   * the hyphen, so the label spelling is the most likely near-miss. SHA-1 is
+   * the same algorithm as the bare "SHA" of RFC 3414.
+   */
+  test.each([
+    ["SHA-256", SnmpAuthProtocol.SHA256],
+    ["sha-256", SnmpAuthProtocol.SHA256],
+    ["SHA-512", SnmpAuthProtocol.SHA512],
+    ["SHA1", SnmpAuthProtocol.SHA],
+    ["SHA-1", SnmpAuthProtocol.SHA],
+    ["  md5 ", SnmpAuthProtocol.MD5],
+    ["Sha256", SnmpAuthProtocol.SHA256],
+  ])(
+    "tolerates the near-miss spelling %j",
+    (stored: string, expected: SnmpAuthProtocol) => {
+      expect(SnmpAuthProtocolUtil.parse(stored)).toBe(expected);
+    },
+  );
+
+  test.each([[undefined], [null], [""], ["  "]])(
+    "returns undefined for the unset value %j",
+    (stored: string | undefined | null) => {
+      expect(SnmpAuthProtocolUtil.parse(stored)).toBeUndefined();
+    },
+  );
+
+  test.each([["sha3"], ["sha-384"], ["hmac"], ["none"], ["md4"], ["nonsense"]])(
+    "returns undefined for the unrecognized value %j",
+    (stored: string) => {
+      expect(SnmpAuthProtocolUtil.parse(stored)).toBeUndefined();
+    },
+  );
+});
+
+describe("SnmpPrivProtocolUtil.parse", () => {
+  test.each([
+    ["DES", SnmpPrivProtocol.DES],
+    ["AES", SnmpPrivProtocol.AES],
+    ["AES256", SnmpPrivProtocol.AES256],
+  ])(
+    "reads the stored value %s",
+    (stored: string, expected: SnmpPrivProtocol) => {
+      expect(SnmpPrivProtocolUtil.parse(stored)).toBe(expected);
+    },
+  );
+
+  /*
+   * "AES-256" is the label the form shows for the value it stores as
+   * "AES256". Under the old bare cast that near-miss encrypted with DES.
+   */
+  test.each([
+    ["AES-256", SnmpPrivProtocol.AES256],
+    ["aes-256", SnmpPrivProtocol.AES256],
+    ["aes256", SnmpPrivProtocol.AES256],
+    ["AES128", SnmpPrivProtocol.AES],
+    ["AES-128", SnmpPrivProtocol.AES],
+    ["des", SnmpPrivProtocol.DES],
+    ["  Des  ", SnmpPrivProtocol.DES],
+  ])(
+    "tolerates the near-miss spelling %j",
+    (stored: string, expected: SnmpPrivProtocol) => {
+      expect(SnmpPrivProtocolUtil.parse(stored)).toBe(expected);
+    },
+  );
+
+  test.each([[undefined], [null], [""], ["  "]])(
+    "returns undefined for the unset value %j",
+    (stored: string | undefined | null) => {
+      expect(SnmpPrivProtocolUtil.parse(stored)).toBeUndefined();
+    },
+  );
+
+  test.each([
+    ["3des"],
+    ["aes192"],
+    ["rc4"],
+    ["none"],
+    ["nonsense"],
+    ["AES512"],
+  ])("returns undefined for the unrecognized value %j", (stored: string) => {
+    expect(SnmpPrivProtocolUtil.parse(stored)).toBeUndefined();
+  });
+});
+
+describe("isUnrecognized — telling unset apart from unreadable", () => {
+  /*
+   * The distinction the probe depends on. An unset protocol keeps its historic
+   * default so devices configured before these columns were mandatory keep
+   * polling; an unreadable one is refused, because there is no safe guess and
+   * defaulting is what silently downgrades the cipher.
+   */
+  test.each([[undefined], [null], [""], ["   "], ["\t"]])(
+    "an unset value %j is not unrecognized",
+    (stored: string | undefined | null) => {
+      expect(SnmpSecurityLevelUtil.isUnrecognized(stored)).toBe(false);
+      expect(SnmpAuthProtocolUtil.isUnrecognized(stored)).toBe(false);
+      expect(SnmpPrivProtocolUtil.isUnrecognized(stored)).toBe(false);
+    },
+  );
+
+  test("a recognized value is not unrecognized", () => {
+    expect(SnmpSecurityLevelUtil.isUnrecognized("AuthPriv")).toBe(false);
+    expect(SnmpAuthProtocolUtil.isUnrecognized("SHA-256")).toBe(false);
+    expect(SnmpPrivProtocolUtil.isUnrecognized("AES-256")).toBe(false);
+  });
+
+  test("a value that matches nothing is unrecognized", () => {
+    expect(SnmpSecurityLevelUtil.isUnrecognized("nonsense")).toBe(true);
+    expect(SnmpAuthProtocolUtil.isUnrecognized("sha3")).toBe(true);
+    expect(SnmpPrivProtocolUtil.isUnrecognized("aes192")).toBe(true);
+  });
+});
+
+describe("every enum member survives a round trip", () => {
+  /*
+   * Exhaustive over the enums rather than a fixed list, so adding a member
+   * without teaching parse() about it fails here instead of silently becoming
+   * unrecognized in production.
+   */
+  test("SnmpSecurityLevel", () => {
+    for (const member of Object.values(SnmpSecurityLevel)) {
+      expect(SnmpSecurityLevelUtil.parse(member)).toBe(member);
+      expect(SnmpSecurityLevelUtil.isUnrecognized(member)).toBe(false);
+    }
+  });
+
+  test("SnmpAuthProtocol", () => {
+    for (const member of Object.values(SnmpAuthProtocol)) {
+      expect(SnmpAuthProtocolUtil.parse(member)).toBe(member);
+      expect(SnmpAuthProtocolUtil.isUnrecognized(member)).toBe(false);
+    }
+  });
+
+  test("SnmpPrivProtocol", () => {
+    for (const member of Object.values(SnmpPrivProtocol)) {
+      expect(SnmpPrivProtocolUtil.parse(member)).toBe(member);
+      expect(SnmpPrivProtocolUtil.isUnrecognized(member)).toBe(false);
+    }
+  });
+
+  // Every enum KEY must parse too - that is the spelling hand-written rows use.
+  test("every enum key spelling also parses", () => {
+    for (const key of Object.keys(SnmpSecurityLevel)) {
+      expect(SnmpSecurityLevelUtil.parse(key)).toBeDefined();
+    }
+    for (const key of Object.keys(SnmpAuthProtocol)) {
+      expect(SnmpAuthProtocolUtil.parse(key)).toBeDefined();
+    }
+    for (const key of Object.keys(SnmpPrivProtocol)) {
+      expect(SnmpPrivProtocolUtil.parse(key)).toBeDefined();
+    }
+  });
+});

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

@@ -0,0 +1,263 @@
+import { describe, expect, test } from "@jest/globals";
+import SnmpVendorTemplateUtil, {
+  SnmpVendorTemplate,
+  SnmpVendorTemplates,
+} from "../../../Types/Monitor/SnmpMonitor/SnmpVendorTemplate";
+import SnmpOid from "../../../Types/Monitor/SnmpMonitor/SnmpOid";
+
+/*
+ * SnmpVendorTemplateUtil is the device-fingerprinting brain for Network
+ * Device monitors: it parses sysObjectID into an IANA enterprise number,
+ * derives a vendor display name from it, routes to a vendor OID template,
+ * and merges template OIDs into a monitor without duplicating rows. These
+ * tests pin each of those behaviors against real-world sysObjectID values.
+ */
+
+// Real sysObjectID values as devices actually report them.
+const CISCO_SYS_OBJECT_ID: string = "1.3.6.1.4.1.9.1.1208"; // Catalyst 2960X
+const MIKROTIK_SYS_OBJECT_ID: string = "1.3.6.1.4.1.14988.1";
+const UBIQUITI_SYS_OBJECT_ID: string = "1.3.6.1.4.1.41112.1.4";
+const JUNIPER_SYS_OBJECT_ID: string = "1.3.6.1.4.1.2636.1.1.1.2.29"; // EX2200
+
+describe("SnmpVendorTemplateUtil.getEnterpriseNumber", () => {
+  test("extracts the enterprise number from a Cisco sysObjectID", () => {
+    expect(
+      SnmpVendorTemplateUtil.getEnterpriseNumber(CISCO_SYS_OBJECT_ID),
+    ).toBe(9);
+  });
+
+  test("accepts the leading-dot form some agents report", () => {
+    expect(
+      SnmpVendorTemplateUtil.getEnterpriseNumber(`.${CISCO_SYS_OBJECT_ID}`),
+    ).toBe(9);
+  });
+
+  test("tolerates surrounding whitespace", () => {
+    expect(
+      SnmpVendorTemplateUtil.getEnterpriseNumber(
+        `  ${MIKROTIK_SYS_OBJECT_ID}  `,
+      ),
+    ).toBe(14988);
+  });
+
+  test("parses a bare enterprise arc with no product suffix", () => {
+    expect(
+      SnmpVendorTemplateUtil.getEnterpriseNumber("1.3.6.1.4.1.41112"),
+    ).toBe(41112);
+  });
+
+  test("returns undefined for a mib-2 OID outside the enterprises arc", () => {
+    // Some appliances report sysObjectID values under 1.3.6.1.2.1 (mib-2).
+    expect(
+      SnmpVendorTemplateUtil.getEnterpriseNumber("1.3.6.1.2.1.1"),
+    ).toBeUndefined();
+  });
+
+  test("returns undefined for garbage that is not an OID", () => {
+    expect(
+      SnmpVendorTemplateUtil.getEnterpriseNumber("not-an-oid"),
+    ).toBeUndefined();
+  });
+
+  test("returns undefined for the enterprises prefix with nothing after it", () => {
+    expect(
+      SnmpVendorTemplateUtil.getEnterpriseNumber("1.3.6.1.4.1."),
+    ).toBeUndefined();
+  });
+
+  test("returns undefined for an empty string", () => {
+    expect(SnmpVendorTemplateUtil.getEnterpriseNumber("")).toBeUndefined();
+  });
+
+  test("returns undefined for undefined", () => {
+    expect(
+      SnmpVendorTemplateUtil.getEnterpriseNumber(undefined),
+    ).toBeUndefined();
+  });
+});
+
+describe("SnmpVendorTemplateUtil.getVendorNameBySysObjectId", () => {
+  test.each([
+    [CISCO_SYS_OBJECT_ID, "Cisco"],
+    [MIKROTIK_SYS_OBJECT_ID, "MikroTik"],
+    [UBIQUITI_SYS_OBJECT_ID, "Ubiquiti"],
+    [JUNIPER_SYS_OBJECT_ID, "Juniper"],
+  ])("%s resolves to vendor %s", (sysObjectId: string, vendor: string) => {
+    expect(SnmpVendorTemplateUtil.getVendorNameBySysObjectId(sysObjectId)).toBe(
+      vendor,
+    );
+  });
+
+  test("an enterprise number outside the map leaves the vendor blank", () => {
+    expect(
+      SnmpVendorTemplateUtil.getVendorNameBySysObjectId(
+        "1.3.6.1.4.1.424242.1.1",
+      ),
+    ).toBeUndefined();
+  });
+
+  test("a non-enterprise OID leaves the vendor blank", () => {
+    expect(
+      SnmpVendorTemplateUtil.getVendorNameBySysObjectId("1.3.6.1.2.1.1"),
+    ).toBeUndefined();
+  });
+
+  test("undefined input leaves the vendor blank", () => {
+    expect(
+      SnmpVendorTemplateUtil.getVendorNameBySysObjectId(undefined),
+    ).toBeUndefined();
+  });
+});
+
+describe("SnmpVendorTemplateUtil.matchBySysObjectId", () => {
+  test("a Cisco device is routed to the cisco-ios template", () => {
+    const template: SnmpVendorTemplate | undefined =
+      SnmpVendorTemplateUtil.matchBySysObjectId(CISCO_SYS_OBJECT_ID);
+
+    expect(template?.id).toBe("cisco-ios");
+    expect(template).toBe(SnmpVendorTemplateUtil.getById("cisco-ios"));
+  });
+
+  test("a MikroTik device is routed to the mikrotik-routeros template", () => {
+    expect(
+      SnmpVendorTemplateUtil.matchBySysObjectId(MIKROTIK_SYS_OBJECT_ID)?.id,
+    ).toBe("mikrotik-routeros");
+  });
+
+  test("a Ubiquiti device is routed to the ubiquiti-edgeos template", () => {
+    expect(
+      SnmpVendorTemplateUtil.matchBySysObjectId(UBIQUITI_SYS_OBJECT_ID)?.id,
+    ).toBe("ubiquiti-edgeos");
+  });
+
+  /*
+   * Juniper has a vendor name in the enterprise map but no vendor-specific
+   * template — the match must come back empty so callers fall back to the
+   * generic Host Resources template rather than mislabeling the device.
+   */
+  test("a Juniper device has a vendor name but no template", () => {
+    expect(
+      SnmpVendorTemplateUtil.getVendorNameBySysObjectId(JUNIPER_SYS_OBJECT_ID),
+    ).toBe("Juniper");
+    expect(
+      SnmpVendorTemplateUtil.matchBySysObjectId(JUNIPER_SYS_OBJECT_ID),
+    ).toBeUndefined();
+  });
+
+  test("an unknown enterprise matches no template", () => {
+    expect(
+      SnmpVendorTemplateUtil.matchBySysObjectId("1.3.6.1.4.1.424242.1"),
+    ).toBeUndefined();
+  });
+
+  test("undefined input matches no template", () => {
+    expect(
+      SnmpVendorTemplateUtil.matchBySysObjectId(undefined),
+    ).toBeUndefined();
+  });
+});
+
+describe("SnmpVendorTemplateUtil.getAll / getById", () => {
+  test("every shipped template is retrievable by its id", () => {
+    for (const template of SnmpVendorTemplates) {
+      expect(SnmpVendorTemplateUtil.getById(template.id)).toBe(template);
+    }
+  });
+
+  test("an unknown template id returns undefined", () => {
+    expect(SnmpVendorTemplateUtil.getById("no-such-template")).toBeUndefined();
+  });
+});
+
+describe("SnmpVendorTemplateUtil.mergeOids", () => {
+  function oidValues(oids: Array<SnmpOid>): Array<string> {
+    return oids.map((oid: SnmpOid) => {
+      return oid.oid;
+    });
+  }
+
+  test("merging into an empty list yields the template's OIDs", () => {
+    const merged: Array<SnmpOid> = SnmpVendorTemplateUtil.mergeOids(
+      [],
+      "cisco-ios",
+    );
+
+    expect(merged).toEqual(SnmpVendorTemplateUtil.getById("cisco-ios")!.oids);
+  });
+
+  test("applying the same template twice never duplicates rows", () => {
+    const once: Array<SnmpOid> = SnmpVendorTemplateUtil.mergeOids(
+      [],
+      "cisco-ios",
+    );
+    const twice: Array<SnmpOid> = SnmpVendorTemplateUtil.mergeOids(
+      once,
+      "cisco-ios",
+    );
+
+    expect(twice).toEqual(once);
+    expect(new Set(oidValues(twice)).size).toBe(twice.length);
+  });
+
+  /*
+   * MikroTik and Ubiquiti both start with hrProcessorLoad
+   * (1.3.6.1.2.1.25.3.3.1.2.1) — applying both templates must produce that
+   * OID exactly once.
+   */
+  test("overlapping templates share OIDs without duplicating them", () => {
+    const mikrotik: Array<SnmpOid> = SnmpVendorTemplateUtil.mergeOids(
+      [],
+      "mikrotik-routeros",
+    );
+    const both: Array<SnmpOid> = SnmpVendorTemplateUtil.mergeOids(
+      mikrotik,
+      "ubiquiti-edgeos",
+    );
+
+    const cpuLoadRows: Array<SnmpOid> = both.filter((oid: SnmpOid) => {
+      return oid.oid === "1.3.6.1.2.1.25.3.3.1.2.1";
+    });
+
+    expect(cpuLoadRows).toHaveLength(1);
+    expect(new Set(oidValues(both)).size).toBe(both.length);
+  });
+
+  test("a user's existing row wins over the template's copy of the same OID", () => {
+    const custom: SnmpOid = {
+      oid: "1.3.6.1.4.1.9.9.109.1.1.1.1.8.1",
+      name: "My Custom CPU Name",
+    };
+
+    const merged: Array<SnmpOid> = SnmpVendorTemplateUtil.mergeOids(
+      [custom],
+      "cisco-ios",
+    );
+
+    const cpuRows: Array<SnmpOid> = merged.filter((oid: SnmpOid) => {
+      return oid.oid === custom.oid;
+    });
+
+    expect(cpuRows).toHaveLength(1);
+    expect(cpuRows[0]?.name).toBe("My Custom CPU Name");
+  });
+
+  test("an unknown template id returns the existing list unchanged", () => {
+    const existing: Array<SnmpOid> = [
+      { oid: "1.3.6.1.2.1.1.1.0", name: "sysDescr" },
+    ];
+
+    expect(
+      SnmpVendorTemplateUtil.mergeOids(existing, "no-such-template"),
+    ).toEqual(existing);
+  });
+
+  test("merging does not mutate the caller's array", () => {
+    const existing: Array<SnmpOid> = [
+      { oid: "1.3.6.1.2.1.1.1.0", name: "sysDescr" },
+    ];
+
+    SnmpVendorTemplateUtil.mergeOids(existing, "cisco-ios");
+
+    expect(existing).toHaveLength(1);
+  });
+});

package/Tests/UI/Components/BasicFormDropdownNormalization.test.tsx

@@ -0,0 +1,167 @@
+import BasicForm from "../../../UI/Components/Forms/BasicForm";
+import Fields from "../../../UI/Components/Forms/Types/Fields";
+import FormFieldSchemaType from "../../../UI/Components/Forms/Types/FormFieldSchemaType";
+import FormValues from "../../../UI/Components/Forms/Types/FormValues";
+import { DropdownOption } from "../../../UI/Components/Dropdown/Dropdown";
+import ObjectID from "../../../Types/ObjectID";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import * as React from "react";
+import { describe, expect, test } from "@jest/globals";
+import getJestMockFunction, { MockFunction } from "../../MockType";
+
+/*
+ * BasicForm's initial-values effect canonicalizes each Dropdown field's stored
+ * value onto the matching option. It used to finish with
+ *
+ *   values[fieldName] = dropdownOption?.value || null;
+ *
+ * which silently replaced any value that matched no option with null. That is
+ * data loss, not cosmetics: ModelForm submits every selected field, so an
+ * untouched field whose value was wiped here is PUT back as null and clears
+ * the column.
+ *
+ * Options legitimately fail to contain a valid stored value — a
+ * permission-scoped or truncated entity list, an options fetch that failed, or
+ * a free-text column holding a spelling the options don't list verbatim
+ * (NetworkDevice.snmpVersion stores either "V3" or the raw enum "3", and the
+ * SNMP form's showIf tolerates both via SnmpVersionUtil — but only if the
+ * value survives long enough to be read).
+ *
+ * These tests drive the real component and assert on the values it actually
+ * submits, because the normalization lives in a useEffect and re-implementing
+ * it in a test would pin nothing.
+ *
+ * Note: jest-dom matchers (toBeInTheDocument etc.) fail typecheck repo-wide,
+ * so assertions here stay on submitted values and plain DOM text.
+ */
+
+describe("BasicForm dropdown initial-value normalization", () => {
+  const OPTIONS: Array<DropdownOption> = [
+    { label: "V1", value: "V1" },
+    { label: "V2c", value: "V2c" },
+    { label: "V3", value: "V3" },
+  ];
+
+  type BuildFieldsFunction = (
+    options: Array<DropdownOption>,
+  ) => Fields<FormValues<any>>;
+
+  const buildFields: BuildFieldsFunction = (
+    options: Array<DropdownOption>,
+  ): Fields<FormValues<any>> => {
+    return [
+      {
+        field: { snmpVersion: true },
+        title: "SNMP Version",
+        fieldType: FormFieldSchemaType.Dropdown,
+        dropdownOptions: options,
+        required: false,
+      },
+    ];
+  };
+
+  type SubmitFormFunction = (
+    initialValues: FormValues<any>,
+    fields: Fields<FormValues<any>>,
+  ) => Promise<FormValues<any>>;
+
+  /*
+   * Renders the form, clicks Save, and hands back the values BasicForm
+   * submitted — i.e. what would be written to the database.
+   */
+  const submitForm: SubmitFormFunction = async (
+    initialValues: FormValues<any>,
+    fields: Fields<FormValues<any>>,
+  ): Promise<FormValues<any>> => {
+    const onSubmit: MockFunction = getJestMockFunction();
+
+    render(
+      <BasicForm
+        fields={fields}
+        id="dropdown-normalization"
+        initialValues={initialValues}
+        onSubmit={onSubmit}
+        submitButtonText="Save"
+      />,
+    );
+
+    await userEvent.setup().click(screen.getByTestId("Save"));
+
+    return onSubmit.mock.calls[0]?.[0] as FormValues<any>;
+  };
+
+  test("keeps a stored value that matches no option instead of nulling it", async () => {
+    /*
+     * The reported case: a device whose snmpVersion column holds the raw enum
+     * spelling "3" while the dropdown lists "V1"/"V2c"/"V3".
+     */
+    const submitted: FormValues<any> = await submitForm(
+      { snmpVersion: "3" } as FormValues<any>,
+      buildFields(OPTIONS),
+    );
+
+    expect(submitted).toEqual({ snmpVersion: "3" });
+  });
+
+  test("keeps stored values when the options failed to load", async () => {
+    /*
+     * ModelForm sets dropdownOptions to [] when an entity list comes back
+     * empty or its fetch throws. Nulling on no-match wiped every dropdown on
+     * such a form.
+     */
+    const submitted: FormValues<any> = await submitForm(
+      { snmpVersion: "V3" } as FormValues<any>,
+      buildFields([]),
+    );
+
+    expect(submitted).toEqual({ snmpVersion: "V3" });
+  });
+
+  test("still canonicalizes a value that does match an option", async () => {
+    const submitted: FormValues<any> = await submitForm(
+      { snmpVersion: "V3" } as FormValues<any>,
+      buildFields(OPTIONS),
+    );
+
+    expect(submitted).toEqual({ snmpVersion: "V3" });
+  });
+
+  test("converts a matching ObjectID initial value to its string form", async () => {
+    const id: ObjectID = new ObjectID("3f1b6b0e-0000-4000-8000-000000000001");
+
+    const submitted: FormValues<any> = await submitForm(
+      { snmpVersion: id } as unknown as FormValues<any>,
+      buildFields([{ label: "Probe A", value: id.toString() }]),
+    );
+
+    expect(submitted).toEqual({ snmpVersion: id.toString() });
+  });
+
+  test("preserves an unmatched ObjectID as a string, not as an ObjectID", async () => {
+    /*
+     * An entity dropdown whose referenced row is missing from the (possibly
+     * permission-scoped) option list must still submit the canonical string
+     * the API expects — preserving the raw ObjectID instance would send an
+     * object.
+     */
+    const id: ObjectID = new ObjectID("3f1b6b0e-0000-4000-8000-000000000002");
+
+    const submitted: FormValues<any> = await submitForm(
+      { snmpVersion: id } as unknown as FormValues<any>,
+      buildFields([{ label: "Someone else", value: "a-different-id" }]),
+    );
+
+    expect(submitted).toEqual({ snmpVersion: id.toString() });
+    expect(typeof submitted["snmpVersion"]).toBe("string");
+  });
+
+  test("leaves an absent value alone", async () => {
+    const submitted: FormValues<any> = await submitForm(
+      {} as FormValues<any>,
+      buildFields(OPTIONS),
+    );
+
+    expect(submitted["snmpVersion"]).toBeUndefined();
+  });
+});