test: de-duplicate attachment and bash tool tests

extensions/msteams/src/attachments.test.ts

@@ -1,5 +1,12 @@
 import type { PluginRuntime } from "openclaw/plugin-sdk";
 import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  buildMSTeamsAttachmentPlaceholder,
+  buildMSTeamsGraphMessageUrls,
+  buildMSTeamsMediaPayload,
+  downloadMSTeamsAttachments,
+  downloadMSTeamsGraphMedia,
+} from "./attachments.js";
 import { setMSTeamsRuntime } from "./runtime.js";
 
 vi.mock("openclaw/plugin-sdk", () => ({
@@ -52,13 +59,47 @@ const runtimeStub = {
   },
 } as unknown as PluginRuntime;
 
-type AttachmentsModule = typeof import("./attachments.js");
-type DownloadAttachmentsParams = Parameters<AttachmentsModule["downloadMSTeamsAttachments"]>[0];
-type DownloadGraphMediaParams = Parameters<AttachmentsModule["downloadMSTeamsGraphMedia"]>[0];
+type DownloadAttachmentsParams = Parameters<typeof downloadMSTeamsAttachments>[0];
+type DownloadGraphMediaParams = Parameters<typeof downloadMSTeamsGraphMedia>[0];
+type DownloadedMedia = Awaited<ReturnType<typeof downloadMSTeamsAttachments>>;
+type DownloadAttachmentsBuildOverrides = Partial<
+  Omit<DownloadAttachmentsParams, "attachments" | "maxBytes" | "allowHosts" | "resolveFn">
+> &
+  Pick<DownloadAttachmentsParams, "allowHosts" | "resolveFn">;
+type DownloadAttachmentsNoFetchOverrides = Partial<
+  Omit<
+    DownloadAttachmentsParams,
+    "attachments" | "maxBytes" | "allowHosts" | "resolveFn" | "fetchFn"
+  >
+> &
+  Pick<DownloadAttachmentsParams, "allowHosts" | "resolveFn">;
 
 const DEFAULT_MESSAGE_URL = "https://graph.microsoft.com/v1.0/chats/19%3Achat/messages/123";
 const DEFAULT_MAX_BYTES = 1024 * 1024;
 const DEFAULT_ALLOW_HOSTS = ["x"];
+const IMAGE_ATTACHMENT = { contentType: "image/png", contentUrl: "https://x/img" };
+const PNG_BUFFER = Buffer.from("png");
+const PNG_BASE64 = PNG_BUFFER.toString("base64");
+const PDF_BUFFER = Buffer.from("pdf");
+const createTokenProvider = () => ({ getAccessToken: vi.fn(async () => "token") });
+const buildAttachment = <T extends Record<string, unknown>>(contentType: string, props: T) => ({
+  contentType,
+  ...props,
+});
+const createHtmlAttachment = (content: string) => buildAttachment("text/html", { content });
+const createImageAttachment = (contentUrl: string) => buildAttachment("image/png", { contentUrl });
+const createPdfAttachment = (contentUrl: string) =>
+  buildAttachment("application/pdf", { contentUrl });
+const createTeamsFileDownloadInfoAttachment = (downloadUrl = "https://x/dl", fileType = "png") =>
+  buildAttachment("application/vnd.microsoft.teams.file.download.info", {
+    content: { downloadUrl, fileType },
+  });
+const createImageMediaEntry = (path: string) => ({ path, contentType: "image/png" });
+const createHostedImageContent = (id: string) => ({
+  id,
+  contentType: "image/png",
+  contentBytes: PNG_BASE64,
+});
 
 const createOkFetchMock = (contentType: string, payload = "png") =>
   vi.fn(async () => {
@@ -70,10 +111,7 @@ const createOkFetchMock = (contentType: string, payload = "png") =>
 
 const buildDownloadParams = (
   attachments: DownloadAttachmentsParams["attachments"],
-  overrides: Partial<
-    Omit<DownloadAttachmentsParams, "attachments" | "maxBytes" | "allowHosts" | "resolveFn">
-  > &
-    Pick<DownloadAttachmentsParams, "allowHosts" | "resolveFn"> = {},
+  overrides: DownloadAttachmentsBuildOverrides = {},
 ): DownloadAttachmentsParams => {
   return {
     attachments,
@@ -84,26 +122,188 @@ const buildDownloadParams = (
   };
 };
 
+const buildDownloadParamsWithFetch = (
+  attachments: DownloadAttachmentsParams["attachments"],
+  fetchFn: unknown,
+  overrides: DownloadAttachmentsNoFetchOverrides = {},
+): DownloadAttachmentsParams => {
+  return buildDownloadParams(attachments, {
+    ...overrides,
+    fetchFn: fetchFn as unknown as typeof fetch,
+  });
+};
+
+const downloadAttachmentsWithFetch = async (
+  attachments: DownloadAttachmentsParams["attachments"],
+  fetchFn: unknown,
+  overrides: DownloadAttachmentsNoFetchOverrides = {},
+  options: { expectFetchCalled?: boolean } = {},
+) => {
+  const media = await downloadMSTeamsAttachments(
+    buildDownloadParamsWithFetch(attachments, fetchFn, overrides),
+  );
+  if (options.expectFetchCalled ?? true) {
+    expect(fetchFn).toHaveBeenCalled();
+  } else {
+    expect(fetchFn).not.toHaveBeenCalled();
+  }
+  return media;
+};
+const downloadAttachmentsWithOkImageFetch = (
+  attachments: DownloadAttachmentsParams["attachments"],
+  overrides: DownloadAttachmentsNoFetchOverrides = {},
+  options: { expectFetchCalled?: boolean } = {},
+) => {
+  return downloadAttachmentsWithFetch(
+    attachments,
+    createOkFetchMock("image/png"),
+    overrides,
+    options,
+  );
+};
+
+const createAuthAwareImageFetchMock = (params: { unauthStatus: number; unauthBody: string }) =>
+  vi.fn(async (_url: string, opts?: RequestInit) => {
+    const headers = new Headers(opts?.headers);
+    const hasAuth = Boolean(headers.get("Authorization"));
+    if (!hasAuth) {
+      return new Response(params.unauthBody, { status: params.unauthStatus });
+    }
+    return new Response(PNG_BUFFER, {
+      status: 200,
+      headers: { "content-type": "image/png" },
+    });
+  });
+
 const buildDownloadGraphParams = (
-  fetchFn: typeof fetch,
+  fetchFn: unknown,
   overrides: Partial<
     Omit<DownloadGraphMediaParams, "messageUrl" | "tokenProvider" | "maxBytes">
   > = {},
 ): DownloadGraphMediaParams => {
   return {
     messageUrl: DEFAULT_MESSAGE_URL,
-    tokenProvider: { getAccessToken: vi.fn(async () => "token") },
+    tokenProvider: createTokenProvider(),
     maxBytes: DEFAULT_MAX_BYTES,
-    fetchFn,
+    fetchFn: fetchFn as unknown as typeof fetch,
     ...overrides,
   };
 };
 
-describe("msteams attachments", () => {
-  const load = async () => {
-    return await import("./attachments.js");
-  };
+const downloadGraphMediaWithFetch = (
+  fetchFn: unknown,
+  overrides: Partial<
+    Omit<DownloadGraphMediaParams, "messageUrl" | "tokenProvider" | "maxBytes">
+  > = {},
+) => {
+  return downloadMSTeamsGraphMedia(buildDownloadGraphParams(fetchFn, overrides));
+};
+const expectFirstGraphUrlContains = (
+  params: Parameters<typeof buildMSTeamsGraphMessageUrls>[0],
+  expectedPath: string,
+) => {
+  const urls = buildMSTeamsGraphMessageUrls(params);
+  expect(urls[0]).toContain(expectedPath);
+};
+const expectAttachmentPlaceholder = (
+  attachments: Parameters<typeof buildMSTeamsAttachmentPlaceholder>[0],
+  expected: string,
+) => {
+  expect(buildMSTeamsAttachmentPlaceholder(attachments)).toBe(expected);
+};
+type AttachmentPlaceholderCase = {
+  label: string;
+  attachments: Parameters<typeof buildMSTeamsAttachmentPlaceholder>[0];
+  expected: string;
+};
+type AttachmentDownloadSuccessCase = {
+  label: string;
+  attachments: DownloadAttachmentsParams["attachments"];
+  assert?: (media: DownloadedMedia) => void;
+};
+type AttachmentAuthRetryScenario = {
+  attachmentUrl: string;
+  unauthStatus: number;
+  unauthBody: string;
+  overrides?: Omit<DownloadAttachmentsNoFetchOverrides, "tokenProvider">;
+};
+type AttachmentAuthRetryCase = {
+  label: string;
+  scenario: AttachmentAuthRetryScenario;
+  expectedMediaLength: number;
+  expectTokenFetch: boolean;
+};
+type GraphUrlExpectationCase = {
+  label: string;
+  params: Parameters<typeof buildMSTeamsGraphMessageUrls>[0];
+  expectedPath: string;
+};
 
+type GraphFetchMockOptions = {
+  hostedContents?: unknown[];
+  attachments?: unknown[];
+  messageAttachments?: unknown[];
+  onShareRequest?: (url: string) => Response | Promise<Response>;
+  onUnhandled?: (url: string) => Response | Promise<Response> | undefined;
+};
+
+const createReferenceAttachment = (shareUrl: string) => ({
+  id: "ref-1",
+  contentType: "reference",
+  contentUrl: shareUrl,
+  name: "report.pdf",
+});
+const createShareReferenceFixture = (shareUrl = "https://contoso.sharepoint.com/site/file") => ({
+  shareUrl,
+  referenceAttachment: createReferenceAttachment(shareUrl),
+});
+
+const createGraphFetchMock = (options: GraphFetchMockOptions = {}) => {
+  const hostedContents = options.hostedContents ?? [];
+  const attachments = options.attachments ?? [];
+  const messageAttachments = options.messageAttachments ?? [];
+  return vi.fn(async (url: string) => {
+    if (url.endsWith("/hostedContents")) {
+      return new Response(JSON.stringify({ value: hostedContents }), { status: 200 });
+    }
+    if (url.endsWith("/attachments")) {
+      return new Response(JSON.stringify({ value: attachments }), { status: 200 });
+    }
+    if (url.endsWith("/messages/123")) {
+      return new Response(JSON.stringify({ attachments: messageAttachments }), { status: 200 });
+    }
+    if (url.startsWith("https://graph.microsoft.com/v1.0/shares/") && options.onShareRequest) {
+      return options.onShareRequest(url);
+    }
+    const unhandled = options.onUnhandled ? await options.onUnhandled(url) : undefined;
+    return unhandled ?? new Response("not found", { status: 404 });
+  });
+};
+const downloadGraphMediaWithMockOptions = async (
+  options: GraphFetchMockOptions = {},
+  overrides: Partial<
+    Omit<DownloadGraphMediaParams, "messageUrl" | "tokenProvider" | "maxBytes">
+  > = {},
+) => {
+  const fetchMock = createGraphFetchMock(options);
+  const media = await downloadGraphMediaWithFetch(fetchMock, overrides);
+  return { fetchMock, media };
+};
+const runAttachmentAuthRetryScenario = async (scenario: AttachmentAuthRetryScenario) => {
+  const tokenProvider = createTokenProvider();
+  const fetchMock = createAuthAwareImageFetchMock({
+    unauthStatus: scenario.unauthStatus,
+    unauthBody: scenario.unauthBody,
+  });
+  const media = await downloadAttachmentsWithFetch(
+    [createImageAttachment(scenario.attachmentUrl)],
+    fetchMock,
+    { tokenProvider, ...scenario.overrides },
+  );
+  return { tokenProvider, media };
+};
+
+describe("msteams attachments", () => {
   beforeEach(() => {
     detectMimeMock.mockClear();
     saveMediaBufferMock.mockClear();
@@ -112,112 +312,82 @@ describe("msteams attachments", () => {
   });
 
   describe("buildMSTeamsAttachmentPlaceholder", () => {
-    it("returns empty string when no attachments", async () => {
-      const { buildMSTeamsAttachmentPlaceholder } = await load();
-      expect(buildMSTeamsAttachmentPlaceholder(undefined)).toBe("");
-      expect(buildMSTeamsAttachmentPlaceholder([])).toBe("");
-    });
-
-    it("returns image placeholder for image attachments", async () => {
-      const { buildMSTeamsAttachmentPlaceholder } = await load();
-      expect(
-        buildMSTeamsAttachmentPlaceholder([
-          { contentType: "image/png", contentUrl: "https://x/img.png" },
-        ]),
-      ).toBe("<media:image>");
-      expect(
-        buildMSTeamsAttachmentPlaceholder([
-          { contentType: "image/png", contentUrl: "https://x/1.png" },
+    it.each<AttachmentPlaceholderCase>([
+      { label: "returns empty string when no attachments", attachments: undefined, expected: "" },
+      { label: "returns empty string when attachments are empty", attachments: [], expected: "" },
+      {
+        label: "returns image placeholder for one image attachment",
+        attachments: [createImageAttachment("https://x/img.png")],
+        expected: "<media:image>",
+      },
+      {
+        label: "returns image placeholder with count for many image attachments",
+        attachments: [
+          createImageAttachment("https://x/1.png"),
           { contentType: "image/jpeg", contentUrl: "https://x/2.jpg" },
-        ]),
-      ).toBe("<media:image> (2 images)");
-    });
-
-    it("treats Teams file.download.info image attachments as images", async () => {
-      const { buildMSTeamsAttachmentPlaceholder } = await load();
-      expect(
-        buildMSTeamsAttachmentPlaceholder([
-          {
-            contentType: "application/vnd.microsoft.teams.file.download.info",
-            content: { downloadUrl: "https://x/dl", fileType: "png" },
-          },
-        ]),
-      ).toBe("<media:image>");
-    });
-
-    it("returns document placeholder for non-image attachments", async () => {
-      const { buildMSTeamsAttachmentPlaceholder } = await load();
-      expect(
-        buildMSTeamsAttachmentPlaceholder([
-          { contentType: "application/pdf", contentUrl: "https://x/x.pdf" },
-        ]),
-      ).toBe("<media:document>");
-      expect(
-        buildMSTeamsAttachmentPlaceholder([
-          { contentType: "application/pdf", contentUrl: "https://x/1.pdf" },
-          { contentType: "application/pdf", contentUrl: "https://x/2.pdf" },
-        ]),
-      ).toBe("<media:document> (2 files)");
-    });
-
-    it("counts inline images in text/html attachments", async () => {
-      const { buildMSTeamsAttachmentPlaceholder } = await load();
-      expect(
-        buildMSTeamsAttachmentPlaceholder([
-          {
-            contentType: "text/html",
-            content: '<p>hi</p><img src="https://x/a.png" />',
-          },
-        ]),
-      ).toBe("<media:image>");
-      expect(
-        buildMSTeamsAttachmentPlaceholder([
-          {
-            contentType: "text/html",
-            content: '<img src="https://x/a.png" /><img src="https://x/b.png" />',
-          },
-        ]),
-      ).toBe("<media:image> (2 images)");
+        ],
+        expected: "<media:image> (2 images)",
+      },
+      {
+        label: "treats Teams file.download.info image attachments as images",
+        attachments: [createTeamsFileDownloadInfoAttachment()],
+        expected: "<media:image>",
+      },
+      {
+        label: "returns document placeholder for non-image attachments",
+        attachments: [createPdfAttachment("https://x/x.pdf")],
+        expected: "<media:document>",
+      },
+      {
+        label: "returns document placeholder with count for many non-image attachments",
+        attachments: [
+          createPdfAttachment("https://x/1.pdf"),
+          createPdfAttachment("https://x/2.pdf"),
+        ],
+        expected: "<media:document> (2 files)",
+      },
+      {
+        label: "counts one inline image in html attachments",
+        attachments: [createHtmlAttachment('<p>hi</p><img src="https://x/a.png" />')],
+        expected: "<media:image>",
+      },
+      {
+        label: "counts many inline images in html attachments",
+        attachments: [
+          createHtmlAttachment('<img src="https://x/a.png" /><img src="https://x/b.png" />'),
+        ],
+        expected: "<media:image> (2 images)",
+      },
+    ])("$label", ({ attachments, expected }) => {
+      expectAttachmentPlaceholder(attachments, expected);
     });
   });
 
   describe("downloadMSTeamsAttachments", () => {
-    it("downloads and stores image contentUrl attachments", async () => {
-      const { downloadMSTeamsAttachments } = await load();
-      const fetchMock = createOkFetchMock("image/png");
-      const media = await downloadMSTeamsAttachments(
-        buildDownloadParams([{ contentType: "image/png", contentUrl: "https://x/img" }], {
-          fetchFn: fetchMock as unknown as typeof fetch,
-        }),
-      );
-
-      expect(fetchMock).toHaveBeenCalled();
-      expect(saveMediaBufferMock).toHaveBeenCalled();
-      expect(media).toHaveLength(1);
-      expect(media[0]?.path).toBe("/tmp/saved.png");
-    });
-
-    it("supports Teams file.download.info downloadUrl attachments", async () => {
-      const { downloadMSTeamsAttachments } = await load();
-      const fetchMock = createOkFetchMock("image/png");
-      const media = await downloadMSTeamsAttachments(
-        buildDownloadParams(
-          [
-            {
-              contentType: "application/vnd.microsoft.teams.file.download.info",
-              content: { downloadUrl: "https://x/dl", fileType: "png" },
-            },
-          ],
-          { fetchFn: fetchMock as unknown as typeof fetch },
-        ),
-      );
-
-      expect(fetchMock).toHaveBeenCalled();
+    it.each<AttachmentDownloadSuccessCase>([
+      {
+        label: "downloads and stores image contentUrl attachments",
+        attachments: [IMAGE_ATTACHMENT],
+        assert: (media) => {
+          expect(saveMediaBufferMock).toHaveBeenCalled();
+          expect(media[0]?.path).toBe("/tmp/saved.png");
+        },
+      },
+      {
+        label: "supports Teams file.download.info downloadUrl attachments",
+        attachments: [createTeamsFileDownloadInfoAttachment()],
+      },
+      {
+        label: "downloads inline image URLs from html attachments",
+        attachments: [createHtmlAttachment('<img src="https://x/inline.png" />')],
+      },
+    ])("$label", async ({ attachments, assert }) => {
+      const media = await downloadAttachmentsWithOkImageFetch(attachments);
       expect(media).toHaveLength(1);
+      assert?.(media);
     });
 
     it("downloads non-image file attachments (PDF)", async () => {
-      const { downloadMSTeamsAttachments } = await load();
       const fetchMock = createOkFetchMock("application/pdf", "pdf");
       detectMimeMock.mockResolvedValueOnce("application/pdf");
       saveMediaBufferMock.mockResolvedValueOnce({
@@ -225,46 +395,20 @@ describe("msteams attachments", () => {
         contentType: "application/pdf",
       });
 
-      const media = await downloadMSTeamsAttachments(
-        buildDownloadParams([{ contentType: "application/pdf", contentUrl: "https://x/doc.pdf" }], {
-          fetchFn: fetchMock as unknown as typeof fetch,
-        }),
+      const media = await downloadAttachmentsWithFetch(
+        [createPdfAttachment("https://x/doc.pdf")],
+        fetchMock,
       );
 
-      expect(fetchMock).toHaveBeenCalled();
       expect(media).toHaveLength(1);
       expect(media[0]?.path).toBe("/tmp/saved.pdf");
       expect(media[0]?.placeholder).toBe("<media:document>");
     });
 
-    it("downloads inline image URLs from html attachments", async () => {
-      const { downloadMSTeamsAttachments } = await load();
-      const fetchMock = createOkFetchMock("image/png");
-      const media = await downloadMSTeamsAttachments(
-        buildDownloadParams(
-          [
-            {
-              contentType: "text/html",
-              content: '<img src="https://x/inline.png" />',
-            },
-          ],
-          { fetchFn: fetchMock as unknown as typeof fetch },
-        ),
-      );
-
-      expect(media).toHaveLength(1);
-      expect(fetchMock).toHaveBeenCalled();
-    });
-
     it("stores inline data:image base64 payloads", async () => {
-      const { downloadMSTeamsAttachments } = await load();
-      const base64 = Buffer.from("png").toString("base64");
       const media = await downloadMSTeamsAttachments(
         buildDownloadParams([
-          {
-            contentType: "text/html",
-            content: `<img src="data:image/png;base64,${base64}" />`,
-          },
+          createHtmlAttachment(`<img src="data:image/png;base64,${PNG_BASE64}" />`),
         ]),
       );
 
@@ -272,218 +416,125 @@ describe("msteams attachments", () => {
       expect(saveMediaBufferMock).toHaveBeenCalled();
     });
 
-    it("retries with auth when the first request is unauthorized", async () => {
-      const { downloadMSTeamsAttachments } = await load();
-      const fetchMock = vi.fn(async (_url: string, opts?: RequestInit) => {
-        const headers = new Headers(opts?.headers);
-        const hasAuth = Boolean(headers.get("Authorization"));
-        if (!hasAuth) {
-          return new Response("unauthorized", { status: 401 });
-        }
-        return new Response(Buffer.from("png"), {
-          status: 200,
-          headers: { "content-type": "image/png" },
-        });
-      });
-
-      const media = await downloadMSTeamsAttachments(
-        buildDownloadParams([{ contentType: "image/png", contentUrl: "https://x/img" }], {
-          tokenProvider: { getAccessToken: vi.fn(async () => "token") },
-          authAllowHosts: ["x"],
-          fetchFn: fetchMock as unknown as typeof fetch,
-        }),
-      );
-
-      expect(fetchMock).toHaveBeenCalled();
-      expect(media).toHaveLength(1);
-    });
-
-    it("skips auth retries when the host is not in auth allowlist", async () => {
-      const { downloadMSTeamsAttachments } = await load();
-      const tokenProvider = { getAccessToken: vi.fn(async () => "token") };
-      const fetchMock = vi.fn(async (_url: string, opts?: RequestInit) => {
-        const headers = new Headers(opts?.headers);
-        const hasAuth = Boolean(headers.get("Authorization"));
-        if (!hasAuth) {
-          return new Response("forbidden", { status: 403 });
-        }
-        return new Response(Buffer.from("png"), {
-          status: 200,
-          headers: { "content-type": "image/png" },
-        });
-      });
-
-      const media = await downloadMSTeamsAttachments(
-        buildDownloadParams(
-          [{ contentType: "image/png", contentUrl: "https://attacker.azureedge.net/img" }],
-          {
-            tokenProvider,
+    it.each<AttachmentAuthRetryCase>([
+      {
+        label: "retries with auth when the first request is unauthorized",
+        scenario: {
+          attachmentUrl: IMAGE_ATTACHMENT.contentUrl,
+          unauthStatus: 401,
+          unauthBody: "unauthorized",
+          overrides: { authAllowHosts: ["x"] },
+        },
+        expectedMediaLength: 1,
+        expectTokenFetch: true,
+      },
+      {
+        label: "skips auth retries when the host is not in auth allowlist",
+        scenario: {
+          attachmentUrl: "https://attacker.azureedge.net/img",
+          unauthStatus: 403,
+          unauthBody: "forbidden",
+          overrides: {
             allowHosts: ["azureedge.net"],
             authAllowHosts: ["graph.microsoft.com"],
-            fetchFn: fetchMock as unknown as typeof fetch,
           },
-        ),
-      );
-
-      expect(media).toHaveLength(0);
-      expect(fetchMock).toHaveBeenCalled();
-      expect(tokenProvider.getAccessToken).not.toHaveBeenCalled();
+        },
+        expectedMediaLength: 0,
+        expectTokenFetch: false,
+      },
+    ])("$label", async ({ scenario, expectedMediaLength, expectTokenFetch }) => {
+      const { tokenProvider, media } = await runAttachmentAuthRetryScenario(scenario);
+      expect(media).toHaveLength(expectedMediaLength);
+      if (expectTokenFetch) {
+        expect(tokenProvider.getAccessToken).toHaveBeenCalled();
+      } else {
+        expect(tokenProvider.getAccessToken).not.toHaveBeenCalled();
+      }
     });
 
     it("skips urls outside the allowlist", async () => {
-      const { downloadMSTeamsAttachments } = await load();
       const fetchMock = vi.fn();
-      const media = await downloadMSTeamsAttachments(
-        buildDownloadParams([{ contentType: "image/png", contentUrl: "https://evil.test/img" }], {
+      const media = await downloadAttachmentsWithFetch(
+        [createImageAttachment("https://evil.test/img")],
+        fetchMock,
+        {
           allowHosts: ["graph.microsoft.com"],
           resolveFn: undefined,
-          fetchFn: fetchMock as unknown as typeof fetch,
-        }),
+        },
+        { expectFetchCalled: false },
       );
 
       expect(media).toHaveLength(0);
-      expect(fetchMock).not.toHaveBeenCalled();
     });
   });
 
   describe("buildMSTeamsGraphMessageUrls", () => {
-    it("builds channel message urls", async () => {
-      const { buildMSTeamsGraphMessageUrls } = await load();
-      const urls = buildMSTeamsGraphMessageUrls({
-        conversationType: "channel",
-        conversationId: "19:thread@thread.tacv2",
-        messageId: "123",
-        channelData: { team: { id: "team-id" }, channel: { id: "chan-id" } },
-      });
-      expect(urls[0]).toContain("/teams/team-id/channels/chan-id/messages/123");
-    });
+    const cases: GraphUrlExpectationCase[] = [
+      {
+        label: "builds channel message urls",
+        params: {
+          conversationType: "channel" as const,
+          conversationId: "19:thread@thread.tacv2",
+          messageId: "123",
+          channelData: { team: { id: "team-id" }, channel: { id: "chan-id" } },
+        },
+        expectedPath: "/teams/team-id/channels/chan-id/messages/123",
+      },
+      {
+        label: "builds channel reply urls when replyToId is present",
+        params: {
+          conversationType: "channel" as const,
+          messageId: "reply-id",
+          replyToId: "root-id",
+          channelData: { team: { id: "team-id" }, channel: { id: "chan-id" } },
+        },
+        expectedPath: "/teams/team-id/channels/chan-id/messages/root-id/replies/reply-id",
+      },
+      {
+        label: "builds chat message urls",
+        params: {
+          conversationType: "groupChat" as const,
+          conversationId: "19:chat@thread.v2",
+          messageId: "456",
+        },
+        expectedPath: "/chats/19%3Achat%40thread.v2/messages/456",
+      },
+    ];
 
-    it("builds channel reply urls when replyToId is present", async () => {
-      const { buildMSTeamsGraphMessageUrls } = await load();
-      const urls = buildMSTeamsGraphMessageUrls({
-        conversationType: "channel",
-        messageId: "reply-id",
-        replyToId: "root-id",
-        channelData: { team: { id: "team-id" }, channel: { id: "chan-id" } },
-      });
-      expect(urls[0]).toContain(
-        "/teams/team-id/channels/chan-id/messages/root-id/replies/reply-id",
-      );
-    });
-
-    it("builds chat message urls", async () => {
-      const { buildMSTeamsGraphMessageUrls } = await load();
-      const urls = buildMSTeamsGraphMessageUrls({
-        conversationType: "groupChat",
-        conversationId: "19:chat@thread.v2",
-        messageId: "456",
-      });
-      expect(urls[0]).toContain("/chats/19%3Achat%40thread.v2/messages/456");
+    it.each(cases)("$label", ({ params, expectedPath }) => {
+      expectFirstGraphUrlContains(params, expectedPath);
     });
   });
 
   describe("downloadMSTeamsGraphMedia", () => {
     it("downloads hostedContents images", async () => {
-      const { downloadMSTeamsGraphMedia } = await load();
-      const base64 = Buffer.from("png").toString("base64");
-      const fetchMock = vi.fn(async (url: string) => {
-        if (url.endsWith("/hostedContents")) {
-          return new Response(
-            JSON.stringify({
-              value: [
-                {
-                  id: "1",
-                  contentType: "image/png",
-                  contentBytes: base64,
-                },
-              ],
-            }),
-            { status: 200 },
-          );
-        }
-        if (url.endsWith("/attachments")) {
-          return new Response(JSON.stringify({ value: [] }), { status: 200 });
-        }
-        return new Response("not found", { status: 404 });
+      const { fetchMock, media } = await downloadGraphMediaWithMockOptions({
+        hostedContents: [createHostedImageContent("1")],
       });
 
-      const media = await downloadMSTeamsGraphMedia(
-        buildDownloadGraphParams(fetchMock as unknown as typeof fetch),
-      );
-
       expect(media.media).toHaveLength(1);
       expect(fetchMock).toHaveBeenCalled();
       expect(saveMediaBufferMock).toHaveBeenCalled();
     });
 
     it("merges SharePoint reference attachments with hosted content", async () => {
-      const { downloadMSTeamsGraphMedia } = await load();
-      const hostedBase64 = Buffer.from("png").toString("base64");
-      const shareUrl = "https://contoso.sharepoint.com/site/file";
-      const fetchMock = vi.fn(async (url: string) => {
-        if (url.endsWith("/hostedContents")) {
-          return new Response(
-            JSON.stringify({
-              value: [
-                {
-                  id: "hosted-1",
-                  contentType: "image/png",
-                  contentBytes: hostedBase64,
-                },
-              ],
-            }),
-            { status: 200 },
-          );
-        }
-        if (url.endsWith("/attachments")) {
-          return new Response(
-            JSON.stringify({
-              value: [
-                {
-                  id: "ref-1",
-                  contentType: "reference",
-                  contentUrl: shareUrl,
-                  name: "report.pdf",
-                },
-              ],
-            }),
-            { status: 200 },
-          );
-        }
-        if (url.startsWith("https://graph.microsoft.com/v1.0/shares/")) {
-          return new Response(Buffer.from("pdf"), {
+      const { referenceAttachment } = createShareReferenceFixture();
+      const { media } = await downloadGraphMediaWithMockOptions({
+        hostedContents: [createHostedImageContent("hosted-1")],
+        attachments: [referenceAttachment],
+        messageAttachments: [referenceAttachment],
+        onShareRequest: () =>
+          new Response(PDF_BUFFER, {
             status: 200,
             headers: { "content-type": "application/pdf" },
-          });
-        }
-        if (url.endsWith("/messages/123")) {
-          return new Response(
-            JSON.stringify({
-              attachments: [
-                {
-                  id: "ref-1",
-                  contentType: "reference",
-                  contentUrl: shareUrl,
-                  name: "report.pdf",
-                },
-              ],
-            }),
-            { status: 200 },
-          );
-        }
-        return new Response("not found", { status: 404 });
+          }),
       });
 
-      const media = await downloadMSTeamsGraphMedia(
-        buildDownloadGraphParams(fetchMock as unknown as typeof fetch),
-      );
-
       expect(media.media).toHaveLength(2);
     });
 
     it("blocks SharePoint redirects to hosts outside allowHosts", async () => {
-      const { downloadMSTeamsGraphMedia } = await load();
-      const shareUrl = "https://contoso.sharepoint.com/site/file";
+      const { referenceAttachment } = createShareReferenceFixture();
       const escapedUrl = "https://evil.example/internal.pdf";
       fetchRemoteMediaMock.mockImplementationOnce(async (params) => {
         const fetchFn = params.fetchImpl ?? fetch;
@@ -510,47 +561,27 @@ describe("msteams attachments", () => {
         throw new Error("too many redirects");
       });
 
-      const fetchMock = vi.fn(async (url: string) => {
-        if (url.endsWith("/hostedContents")) {
-          return new Response(JSON.stringify({ value: [] }), { status: 200 });
-        }
-        if (url.endsWith("/attachments")) {
-          return new Response(JSON.stringify({ value: [] }), { status: 200 });
-        }
-        if (url.endsWith("/messages/123")) {
-          return new Response(
-            JSON.stringify({
-              attachments: [
-                {
-                  id: "ref-1",
-                  contentType: "reference",
-                  contentUrl: shareUrl,
-                  name: "report.pdf",
-                },
-              ],
+      const { fetchMock, media } = await downloadGraphMediaWithMockOptions(
+        {
+          messageAttachments: [referenceAttachment],
+          onShareRequest: () =>
+            new Response(null, {
+              status: 302,
+              headers: { location: escapedUrl },
             }),
-            { status: 200 },
-          );
-        }
-        if (url.startsWith("https://graph.microsoft.com/v1.0/shares/")) {
-          return new Response(null, {
-            status: 302,
-            headers: { location: escapedUrl },
-          });
-        }
-        if (url === escapedUrl) {
-          return new Response(Buffer.from("should-not-be-fetched"), {
-            status: 200,
-            headers: { "content-type": "application/pdf" },
-          });
-        }
-        return new Response("not found", { status: 404 });
-      });
-
-      const media = await downloadMSTeamsGraphMedia(
-        buildDownloadGraphParams(fetchMock as unknown as typeof fetch, {
+          onUnhandled: (url) => {
+            if (url === escapedUrl) {
+              return new Response(Buffer.from("should-not-be-fetched"), {
+                status: 200,
+                headers: { "content-type": "application/pdf" },
+              });
+            }
+            return undefined;
+          },
+        },
+        {
           allowHosts: ["graph.microsoft.com", "contoso.sharepoint.com"],
-        }),
+        },
       );
 
       expect(media.media).toHaveLength(0);
@@ -564,10 +595,9 @@ describe("msteams attachments", () => {
 
   describe("buildMSTeamsMediaPayload", () => {
     it("returns single and multi-file fields", async () => {
-      const { buildMSTeamsMediaPayload } = await load();
       const payload = buildMSTeamsMediaPayload([
-        { path: "/tmp/a.png", contentType: "image/png" },
-        { path: "/tmp/b.png", contentType: "image/png" },
+        createImageMediaEntry("/tmp/a.png"),
+        createImageMediaEntry("/tmp/b.png"),
       ]);
       expect(payload.MediaPath).toBe("/tmp/a.png");
       expect(payload.MediaUrl).toBe("/tmp/a.png");