Skip to content

A modern and easy to use dashboard. 80+ integrations. 20K+ icons built in. Authentication out of the box. No YAML, drag and drop configuration.

12.9 KB
Raw Blame
// @vitest-environment node
import { Response } from "undici";
import { beforeEach, describe, expect, test, vi } from "vitest";

import { fetchWithTrustedCertificatesAsync } from "@homarr/core/infrastructure/http";

import type { IntegrationSecret } from "../../base/types";
import { PlexIntegration } from "../plex-integration";

const imageProxyMocks = vi.hoisted(() => ({
  createImageAsync: vi.fn((url: string) => Promise.resolve(`proxied:${url}`)),
}));

const dispatcherMocks = vi.hoisted(() => ({ close: vi.fn(() => Promise.resolve()) }));

vi.mock("@homarr/core/infrastructure/http", () => ({
  fetchWithTrustedCertificatesAsync: vi.fn(),
  createCertificateAgentAsync: vi.fn(() => Promise.resolve(dispatcherMocks)),
}));

vi.mock("@homarr/image-proxy", () => ({
  ImageProxy: class {
    createImageAsync = imageProxyMocks.createImageAsync;
  },
}));

const TEST_URL = "https://plex.example.com";
const mockFetch = vi.mocked(fetchWithTrustedCertificatesAsync);

const secrets: IntegrationSecret[] = [{ kind: "apiKey", value: "plex-token" }];

const createIntegration = () =>
  new PlexIntegration({
    id: "test-plex",
    name: "Test Plex",
    url: TEST_URL,
    externalUrl: null,
    decryptedSecrets: secrets,
  });

const createMetadataItem = (key: string, overrides: Record<string, unknown>) => ({
  key: `/library/metadata/${key}`,
  type: "movie",
  title: "Movie",
  addedAt: 1_735_689_600,
  Image: [
    {
      type: "coverPoster",
      url: `/library/metadata/${key}/thumb`,
    },
  ],
  ...overrides,
});

const createEpisode = (key: string, overrides: Record<string, unknown>) => ({
  key: `/library/metadata/${key}`,
  type: "episode",
  title: "Episode",
  addedAt: 1_735_689_600,
  ...overrides,
});

const respond = (body: unknown, status = 200) =>
  Promise.resolve(new Response(JSON.stringify(body), { status })) as unknown as ReturnType<
    typeof fetchWithTrustedCertificatesAsync
  >;

beforeEach(() => {
  mockFetch.mockReset();
  imageProxyMocks.createImageAsync.mockClear();
});

describe("PlexIntegration.getMediaReleasesAsync", () => {
  test.each([
    ["album", "music"],
    ["artist", "music"],
    ["track", "music"],
    ["movie", "movie"],
    ["show", "tv"],
    ["unsupported", "unknown"],
  ])("classifies %s releases as %s", async (type, expectedType) => {
    mockFetch.mockImplementation((url) => {
      const urlString = String(url);
      if (urlString.endsWith("/identity")) {
        return respond({ MediaContainer: { machineIdentifier: "server-id" } });
      }
      if (urlString.endsWith("/library/recentlyAdded")) {
        return respond({ MediaContainer: { Metadata: [createMetadataItem(type, { type })] } });
      }
      if (urlString.endsWith("/library/sections")) {
        return respond({ MediaContainer: { Directory: [] } });
      }
      throw new Error(`Unexpected Plex request: ${urlString}`);
    });

    const releases = await createIntegration().getMediaReleasesAsync();

    expect(releases).toHaveLength(1);
    expect(releases[0]).toMatchObject({ title: "Movie", type: expectedType });
  });

  test("uses the series title for TV seasons and episodes", async () => {
    mockFetch.mockImplementation((url) => {
      const urlString = String(url);

      if (urlString.endsWith("/identity")) {
        return Promise.resolve(
          new Response(JSON.stringify({ MediaContainer: { machineIdentifier: "server-id" } }), { status: 200 }),
        ) as unknown as ReturnType<typeof fetchWithTrustedCertificatesAsync>;
      }

      if (urlString.endsWith("/library/recentlyAdded")) {
        return Promise.resolve(
          new Response(
            JSON.stringify({
              MediaContainer: {
                Metadata: [
                  createMetadataItem("season", {
                    type: "season",
                    title: "Season 1",
                    parentTitle: "Breaking Bad",
                  }),
                  createMetadataItem("episode", {
                    type: "episode",
                    title: "Review",
                    parentTitle: "Season 1",
                    grandparentTitle: "The Bear",
                  }),
                  createMetadataItem("movie", {
                    type: "movie",
                    title: "Inception",
                    tagline: "Dreams feel real",
                  }),
                  createMetadataItem("show", {
                    type: "show",
                    title: "The Last of Us",
                    tagline: "A series tagline",
                  }),
                  createMetadataItem("missing-parent", {
                    type: "season",
                    title: "Season 3",
                  }),
                ],
              },
            }),
            { status: 200 },
          ),
        ) as unknown as ReturnType<typeof fetchWithTrustedCertificatesAsync>;
      }

      throw new Error(`Unexpected Plex request: ${urlString}`);
    });

    const releases = await createIntegration().getMediaReleasesAsync();

    expect(releases).toMatchObject([
      {
        title: "Breaking Bad",
        subtitle: "Season 1",
        type: "tv",
      },
      {
        title: "The Bear",
        subtitle: "Review",
        type: "tv",
      },
      {
        title: "Inception",
        subtitle: "Dreams feel real",
        type: "movie",
      },
      {
        title: "The Last of Us",
        subtitle: "A series tagline",
        type: "tv",
      },
      {
        title: "Season 3",
        subtitle: undefined,
        type: "tv",
      },
    ]);
  });
});

describe("PlexIntegration.getMediaReleasesAsync with recently added episodes", () => {
  const mockPlex = (
    recentlyAdded: Record<string, unknown>[],
    episodesBySection: Record<string, Record<string, unknown>[] | "error">,
  ) => {
    mockFetch.mockImplementation((url) => {
      const urlString = String(url);

      if (urlString.endsWith("/identity")) {
        return respond({ MediaContainer: { machineIdentifier: "server-id" } });
      }

      if (urlString.endsWith("/library/recentlyAdded")) {
        return respond({ MediaContainer: { Metadata: recentlyAdded } });
      }

      if (urlString.endsWith("/library/sections")) {
        return respond({
          MediaContainer: {
            Directory: [
              { key: "2", type: "movie" },
              ...Object.keys(episodesBySection).map((key) => ({ key, type: "show" })),
            ],
          },
        });
      }

      const sectionMatch = /\/library\/sections\/(\d+)\/all\?type=4&sort=addedAt:desc/.exec(urlString);
      if (sectionMatch?.[1] && sectionMatch[1] in episodesBySection) {
        const episodes = episodesBySection[sectionMatch[1]];
        return episodes === "error"
          ? respond({ error: "boom" }, 500)
          : respond({ MediaContainer: { Metadata: episodes } });
      }

      throw new Error(`Unexpected Plex request: ${urlString}`);
    });
  };

  test("bumps seasons that received new episodes and re-creates seasons missing from recentlyAdded", async () => {
    mockPlex(
      [
        createMetadataItem("movie", { type: "movie", title: "Inception", addedAt: 300 }),
        createMetadataItem("season-1/children", {
          type: "season",
          title: "Season 1",
          parentTitle: "Breaking Bad",
          addedAt: 200,
          originallyAvailableAt: "2008-01-20",
        }),
        createMetadataItem("season-2/children", {
          type: "season",
          title: "Season 2",
          parentTitle: "Breaking Bad",
          addedAt: 100,
        }),
      ],
      {
        "1": [
          createEpisode("ep-new", {
            parentKey: "/library/metadata/season-1",
            addedAt: 500,
            originallyAvailableAt: "2026-09-14",
          }),
          createEpisode("ep-old", { parentKey: "/library/metadata/season-1", addedAt: 50 }),
        ],
        "7": [
          createEpisode("ep-missing", {
            parentKey: "/library/metadata/season-99",
            parentTitle: "Season 11",
            grandparentTitle: "Futurama",
            grandparentThumb: "/library/metadata/show-99/thumb",
            art: "/library/metadata/ep-missing/art",
            addedAt: 400,
            originallyAvailableAt: "2026-09-13",
          }),
        ],
      },
    );

    const releases = await createIntegration().getMediaReleasesAsync();

    expect(releases.map((release) => [release.title, release.subtitle])).toEqual([
      ["Breaking Bad", "Season 1"],
      ["Futurama", "Season 11"],
      ["Inception", undefined],
      ["Breaking Bad", "Season 2"],
    ]);
    // Plex air dates are represented as UTC dates and rendered as calendar dates by the widget
    expect(releases[0]?.releaseDate).toEqual(new Date("2026-09-14"));
    expect(releases[0]?.releaseDateIsDateOnly).toBe(true);
    expect(releases[1]).toMatchObject({
      type: "tv",
      releaseDate: new Date("2026-09-13"),
      releaseDateIsDateOnly: true,
      imageUrls: {
        poster: `proxied:${TEST_URL}/library/metadata/show-99/thumb`,
        backdrop: `proxied:${TEST_URL}/library/metadata/ep-missing/art`,
      },
      href: `${TEST_URL}/web/index.html#!/server/server-id/details?key=${encodeURIComponent("/library/metadata/season-99")}`,
    });
  });

  test("falls back to recentlyAdded when episodes cannot be fetched", async () => {
    mockFetch.mockImplementation((url) => {
      const urlString = String(url);

      if (urlString.endsWith("/identity")) {
        return Promise.resolve(
          new Response(JSON.stringify({ MediaContainer: { machineIdentifier: "server-id" } }), { status: 200 }),
        ) as unknown as ReturnType<typeof fetchWithTrustedCertificatesAsync>;
      }

      if (urlString.endsWith("/library/recentlyAdded")) {
        return Promise.resolve(
          new Response(
            JSON.stringify({
              MediaContainer: {
                Metadata: [
                  createMetadataItem("season/children", {
                    type: "season",
                    title: "Season 1",
                    parentTitle: "Breaking Bad",
                  }),
                ],
              },
            }),
            { status: 200 },
          ),
        ) as unknown as ReturnType<typeof fetchWithTrustedCertificatesAsync>;
      }

      return Promise.resolve(new Response("Not found", { status: 404 })) as unknown as ReturnType<
        typeof fetchWithTrustedCertificatesAsync
      >;
    });

    const releases = await createIntegration().getMediaReleasesAsync();

    expect(releases).toMatchObject([{ title: "Breaking Bad", subtitle: "Season 1" }]);
  });

  test("does not duplicate content that recentlyAdded already lists as an episode or a show", async () => {
    mockPlex(
      [
        createMetadataItem("episode", {
          type: "episode",
          title: "Older episode",
          parentKey: "/library/metadata/season-11",
          grandparentTitle: "Futurama",
          addedAt: 100,
        }),
        createMetadataItem("show-42", { type: "show", title: "Severance", addedAt: 90 }),
      ],
      {
        "1": [
          createEpisode("ep-futurama", {
            title: "Oceans Three",
            index: 5,
            parentIndex: 11,
            parentKey: "/library/metadata/season-11",
            grandparentKey: "/library/metadata/show-futurama",
            grandparentTitle: "Futurama",
            addedAt: 500,
          }),
          createEpisode("ep-severance", {
            title: "Cold Harbor",
            index: 10,
            parentIndex: 2,
            parentKey: "/library/metadata/season-sev-2",
            grandparentKey: "/library/metadata/show-42",
            grandparentTitle: "Severance",
            addedAt: 400,
          }),
        ],
      },
    );

    const releases = await createIntegration().getMediaReleasesAsync();

    // one card per show: the episode and show entries are both labelled with their newest episodes
    expect(releases.map((release) => [release.title, release.subtitle])).toEqual([
      ["Futurama", "S11E05 \u2013 Oceans Three"],
      ["Severance", "S02E10 \u2013 Cold Harbor"],
    ]);
    expect(releases[0]?.href).toContain(encodeURIComponent("/library/metadata/ep-futurama"));
  });

  test("keeps the episodes of the libraries that answered when one library fails", async () => {
    mockPlex([createMetadataItem("movie", { type: "movie", title: "Inception", addedAt: 100 })], {
      "1": "error",
      "7": [
        createEpisode("ep-ok", {
          parentKey: "/library/metadata/season-7",
          parentTitle: "Season 3",
          grandparentTitle: "Andor",
          grandparentThumb: "/library/metadata/show-andor/thumb",
          addedAt: 400,
        }),
      ],
    });

    const releases = await createIntegration().getMediaReleasesAsync();

    expect(releases.map((release) => release.title)).toEqual(["Andor", "Inception"]);
  });

  test("throws a response error instead of a parse error when Plex rejects the request", async () => {
    mockFetch.mockImplementation(() => respond({ error: "unauthorized" }, 401));

    await expect(createIntegration().getMediaReleasesAsync()).rejects.toThrow();
  });
});