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.

11.9 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";

import type { ProviderReply, ProviderRequest } from "./provider-server";
import { expectFailure, expectRelease, mockedFetch, resetProviderState, serveProvider } from "./provider-server";

vi.mock("@homarr/core/infrastructure/http", () => ({ fetchWithTrustedCertificatesAsync: vi.fn() }));
vi.mock("@homarr/core/infrastructure/logs", () => ({ createLogger: () => ({ warn: vi.fn() }) }));

interface GithubRelease {
  tag_name: string;
  published_at: string | null;
  html_url: string;
  body: string | null;
  prerelease: boolean;
}

interface FakeGithub {
  origin?: string;
  releases: GithubRelease[];
  repositoryReply?: ProviderReply;
  failPage?: { page: number; reply: ProviderReply };
  releasesReply?: ProviderReply;
}

const hour = (value: number) => new Date(Date.UTC(2026, 0, 1) - value * 3_600_000).toISOString();

const release = (tag: string, publishedHoursAgo: number, details: Partial<GithubRelease> = {}): GithubRelease => ({
  tag_name: tag,
  published_at: hour(publishedHoursAgo),
  html_url: `https://github.com/owner/repo/releases/tag/${tag}`,
  body: `Notes for ${tag}`,
  prerelease: false,
  ...details,
});

const repository = {
  html_url: "https://github.com/owner/repo",
  description: "A project",
  fork: false,
  archived: false,
  created_at: "2020-01-01T00:00:00Z",
  stargazers_count: 42,
  open_issues_count: 3,
  forks_count: 7,
};

const listReleases = (github: FakeGithub, request: ProviderRequest): ProviderReply => {
  const page = Number(request.url.searchParams.get("page") ?? 1);
  if (github.failPage?.page === page) return github.failPage.reply;
  const perPage = Number(request.url.searchParams.get("per_page"));
  const start = (page - 1) * perPage;
  if (start + perPage >= github.releases.length) return { body: github.releases.slice(start) };

  const next = new URL(request.url);
  next.searchParams.set("page", String(page + 1));
  return { body: github.releases.slice(start, start + perPage), headers: { link: `<${next.toString()}>; rel="next"` } };
};

const serveGithub = (github: FakeGithub) =>
  serveProvider((request) => {
    const origin = github.origin ?? "https://api.github.com";
    const path = `${request.url.origin}${request.url.pathname}`;
    if (path === `${origin}/repos/owner/repo`) return github.repositoryReply ?? { body: repository };
    if (path !== `${origin}/repos/owner/repo/releases`) return undefined;
    return github.releasesReply ?? listReleases(github, request);
  });

const releasePages = (requests: ProviderRequest[]) =>
  requests
    .filter((request) => request.url.pathname.endsWith("/releases"))
    .map((request) => Number(request.url.searchParams.get("page") ?? 1));

const detailRequests = (requests: ProviderRequest[]) =>
  requests.filter((request) => request.url.pathname === "/repos/owner/repo").length;

const hourMs = 3_600_000;

const numberedReleases = (count: number) =>
  Array.from({ length: count }, (_, index) => release(`v${count - index}`, index + 100));

const capMessage = "Only the first 1000 results are available";

describe("GitHub releases", () => {
  beforeEach(() => {
    resetProviderState();
  });

  afterEach(() => {
    vi.useRealTimers();
  });

  test("returns the newest published release with repository details from one page", async () => {
    const requests = serveGithub({
      releases: [
        release("v2.0.0", 30),
        release("v2.1.0", 2, { body: "Fixes" }),
        release("v1.9.9", 50),
        ...numberedReleases(20),
      ],
    });

    const result = await expectRelease({ provider: "github", identifier: "owner/repo" });

    expect(result).toEqual({
      latestRelease: "v2.1.0",
      latestReleaseAt: new Date(hour(2)),
      releaseUrl: "https://github.com/owner/repo/releases/tag/v2.1.0",
      releaseDescription: "Fixes",
      isPreRelease: false,
      projectUrl: "https://github.com/owner/repo",
      projectDescription: "A project",
      isFork: false,
      isArchived: false,
      createdAt: new Date("2020-01-01T00:00:00Z"),
      starsCount: 42,
      openIssues: 3,
      forksCount: 7,
    });
    expect(releasePages(requests)).toEqual([1]);
    expect(requests[0]?.url.searchParams.get("per_page")).toBe("10");
  });

  test("keeps the pre-release flag of the newest release", async () => {
    serveGithub({ releases: [release("v3.0.0-beta.1", 1, { prerelease: true }), release("v2.9.0", 5)] });

    const result = await expectRelease({ provider: "github", identifier: "owner/repo" });

    expect(result).toMatchObject({ latestRelease: "v3.0.0-beta.1", isPreRelease: true });
  });

  test("skips draft releases without a publication date", async () => {
    serveGithub({ releases: [release("v9.0.0", 0, { published_at: null }), release("v8.0.0", 3)] });

    const result = await expectRelease({ provider: "github", identifier: "owner/repo" });

    expect(result.latestRelease).toBe("v8.0.0");
  });

  test("reports noReleasesFound for a repository without releases", async () => {
    serveGithub({ releases: [] });

    const error = await expectFailure({ provider: "github", identifier: "owner/repo" });

    expect(error.code).toBe("noReleasesFound");
  });

  test("still returns the release when repository details fail", async () => {
    serveGithub({ releases: [release("v1.0.0", 1)], repositoryReply: { status: 500, body: { message: "boom" } } });

    const result = await expectRelease({ provider: "github", identifier: "owner/repo" });

    expect(result.latestRelease).toBe("v1.0.0");
    expect(result.projectUrl).toBeUndefined();
  });

  test("reuses repository details for a day while checking releases on every lookup", async () => {
    vi.useFakeTimers({ toFake: ["Date"] });
    const start = Date.now();
    const requests = serveGithub({ releases: [release("v1.0.0", 1)] });

    await expectRelease({ provider: "github", identifier: "owner/repo" });
    vi.setSystemTime(start + 23 * hourMs);
    const cached = await expectRelease({ provider: "github", identifier: "owner/repo" });
    vi.setSystemTime(start + 25 * hourMs);
    await expectRelease({ provider: "github", identifier: "owner/repo" });

    expect(cached.starsCount).toBe(42);
    expect(releasePages(requests)).toEqual([1, 1, 1]);
    expect(detailRequests(requests)).toBe(2);
  });

  test("retries repository details on the next lookup after they failed", async () => {
    const github: FakeGithub = {
      releases: [release("v1.0.0", 1)],
      repositoryReply: { status: 500, body: { message: "boom" } },
    };
    serveGithub(github);

    const failed = await expectRelease({ provider: "github", identifier: "owner/repo" });
    github.repositoryReply = undefined;
    const recovered = await expectRelease({ provider: "github", identifier: "owner/repo" });

    expect(failed.starsCount).toBeUndefined();
    expect(recovered.starsCount).toBe(42);
  });

  test("does not share repository details between tokens", async () => {
    const requests = serveGithub({ releases: [release("v1.0.0", 1)] });

    await expectRelease({ provider: "github", identifier: "owner/repo", token: "ghp_first" });
    await expectRelease({ provider: "github", identifier: "owner/repo", token: "ghp_second" });

    expect(detailRequests(requests)).toBe(2);
  });

  test("uses a GitHub Enterprise API URL", async () => {
    const requests = serveGithub({ origin: "https://github.example.com", releases: [release("v1.0.0", 1)] });

    await expectRelease({ provider: "github", identifier: "owner/repo", providerUrl: "https://github.example.com/" });

    expect(requests.every((request) => request.url.origin === "https://github.example.com")).toBe(true);
  });

  test("sends a configured token", async () => {
    const requests = serveGithub({ releases: [release("v1.0.0", 1)] });

    await expectRelease({ provider: "github", identifier: "owner/repo", token: "ghp_secret" });

    expect(requests[0]?.headers.authorization).toBe("token ghp_secret");
  });

  test("ignores path segments after the repository name", async () => {
    serveGithub({ releases: [release("v1.0.0", 1)] });

    const result = await expectRelease({ provider: "github", identifier: "owner/repo/releases" });

    expect(result.latestRelease).toBe("v1.0.0");
  });

  test("rejects an identifier without a repository name before any request", async () => {
    const error = await expectFailure({ provider: "github", identifier: "owner" });

    expect(error.code).toBe("invalidIdentifier");
    expect(mockedFetch).not.toHaveBeenCalled();
  });

  describe("version filters", () => {
    test.each([
      { versionRegex: undefined, expected: "v1001", pageCount: 1 },
      { versionRegex: "^v2$", expected: "v2", pageCount: 10 },
    ])("stops paging at the first page containing $expected", async ({ versionRegex, expected, pageCount }) => {
      const requests = serveGithub({
        releases: numberedReleases(1001),
        failPage: { page: 11, reply: { status: 422, body: { message: capMessage } } },
      });

      const result = await expectRelease({ provider: "github", identifier: "owner/repo", versionRegex });

      expect(result.latestRelease).toBe(expected);
      expect(releasePages(requests)).toEqual(Array.from({ length: pageCount }, (_, index) => index + 1));
    });

    test("reads 100 releases per page while filtering", async () => {
      const requests = serveGithub({ releases: numberedReleases(5) });

      await expectRelease({ provider: "github", identifier: "owner/repo", versionRegex: "^v" });

      expect(requests[0]?.url.searchParams.get("per_page")).toBe("100");
    });

    test("returns the newest matching release instead of the highest version", async () => {
      serveGithub({ releases: [release("v2.0.0", 1), release("v1.10.1", 2), release("v1.11.0", 40)] });

      const result = await expectRelease({ provider: "github", identifier: "owner/repo", versionRegex: "^v1\\." });

      expect(result.latestRelease).toBe("v1.10.1");
    });

    test("reports noMatchingVersion when the history reaches GitHub's cap", async () => {
      const requests = serveGithub({
        releases: numberedReleases(1001),
        failPage: { page: 11, reply: { status: 422, body: { message: capMessage } } },
      });

      const error = await expectFailure({ provider: "github", identifier: "owner/repo", versionRegex: "^v0$" });

      expect(error.code).toBe("noMatchingVersion");
      expect(releasePages(requests)).toEqual(Array.from({ length: 11 }, (_, index) => index + 1));
    });

    test.each([
      { page: 2, status: 422, message: "Validation Failed" },
      { page: 2, status: 401, message: "Bad credentials" },
      { page: 1, status: 422, message: capMessage },
    ])("does not hide an API error on page $page: $message", async ({ page, status, message }) => {
      serveGithub({ releases: numberedReleases(300), failPage: { page, reply: { status, body: { message } } } });

      const error = await expectFailure({ provider: "github", identifier: "owner/repo", versionRegex: "^v2$" });

      expect(error.code).toBe("unexpected");
      expect(error.message).toContain(message);
    });
  });

  describe("errors", () => {
    test.each([
      { reply: { status: 404, body: { message: "Not Found" } }, code: "notFound" },
      { reply: { status: 429, body: { message: "Too Many Requests" } }, code: "rateLimited" },
      {
        reply: { status: 403, body: { message: "Forbidden" }, headers: { "x-ratelimit-remaining": "0" } },
        code: "rateLimited",
      },
      { reply: { status: 403, body: { message: "API rate limit exceeded for 1.2.3.4" } }, code: "rateLimited" },
      { reply: { status: 403, body: { message: "Resource not accessible" } }, code: "unexpected" },
      { reply: { status: 500, body: { message: "Server Error" } }, code: "unexpected" },
    ])("maps $reply.status $reply.body.message to $code", async ({ reply, code }) => {
      serveGithub({ releases: [], releasesReply: reply });

      const error = await expectFailure({ provider: "github", identifier: "owner/repo" });

      expect(error.code).toBe(code);
    });
  });
});