Skip to content

Write HTML. Render video. Built for agents.

12.2 KB
Raw Blame
import { afterEach, describe, expect, it, vi } from "vitest";
import {
  lstatSync,
  mkdirSync,
  mkdtempSync,
  readFileSync,
  rmSync,
  symlinkSync,
  writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { CliRuntimeError, registerRootExitRequester } from "../utils/commandResult.js";
import { CAPTURE_PHASE_SCHEMA } from "../capture/types.js";

const { captureWebsiteMock } = vi.hoisted(() => ({
  captureWebsiteMock: vi.fn(async (options: unknown) => {
    if (typeof options === "object" && options !== null) {
      const onPhase = Reflect.get(options, "onPhase");
      if (typeof onPhase === "function") {
        onPhase({
          schema: CAPTURE_PHASE_SCHEMA,
          phase: "vision",
          status: "degraded",
          remainingMs: 0,
          reason: "budget-exhausted",
        });
      }
    }
    return {
      ok: true,
      projectDir: "/tmp/capture",
      url: "https://example.com",
      title: "Example",
      extracted: {},
      screenshots: [],
      tokens: { sections: [], fonts: [] },
      assets: [],
      warnings: [] as string[],
    };
  }),
}));

vi.mock("../capture/index.js", () => ({ captureWebsite: captureWebsiteMock }));

import captureCommand from "./capture.js";

describe("capture command — vision control", () => {
  afterEach(() => {
    captureWebsiteMock.mockClear();
    vi.restoreAllMocks();
  });

  it("declares --skip-vision as an opt-in boolean", () => {
    const skipVisionArg = captureCommand.args
      ? Reflect.get(captureCommand.args, "skip-vision")
      : undefined;
    expect(skipVisionArg).toMatchObject({
      type: "boolean",
      default: false,
    });
  });

  it("declares --capture-budget separately from navigation --timeout", () => {
    const captureBudgetArg = captureCommand.args
      ? Reflect.get(captureCommand.args, "capture-budget")
      : undefined;
    expect(captureBudgetArg).toMatchObject({ type: "string" });
    const description = captureBudgetArg?.description.toLowerCase();
    expect(description).toContain("post-navigation");
    expect(description).toContain("cooperative");
    expect(description).toContain("not a hard wall-clock timeout");
    expect(description).toContain("already-started native/core work");
    expect(captureBudgetArg?.description).toContain("--timeout");
  });

  it("plumbs --skip-vision into capture options", async () => {
    vi.spyOn(console, "log").mockImplementation(() => {});
    vi.spyOn(console, "error").mockImplementation(() => {});

    await captureCommand.run!({
      args: {
        url: "https://example.com",
        output: "/tmp/hf-skip-vision-test",
        "skip-assets": false,
        "skip-vision": true,
        json: true,
      },
    } as never);

    expect(captureWebsiteMock).toHaveBeenCalledWith(
      expect.objectContaining({ skipVision: true }),
      undefined,
    );
  });

  it("plumbs the optional whole-capture deadline from the environment", async () => {
    vi.spyOn(console, "log").mockImplementation(() => {});
    vi.spyOn(console, "error").mockImplementation(() => {});
    process.env.HYPERFRAMES_CAPTURE_DEADLINE_MS = "240000";

    try {
      await captureCommand.run!({
        args: {
          url: "https://example.com",
          output: "/tmp/hf-capture-deadline-test",
          "skip-assets": false,
          "skip-vision": false,
          json: true,
        },
      } as never);

      expect(captureWebsiteMock).toHaveBeenCalledWith(
        expect.objectContaining({ captureDeadlineMs: 240_000 }),
        undefined,
      );
    } finally {
      delete process.env.HYPERFRAMES_CAPTURE_DEADLINE_MS;
    }
  });

  it.each([
    ["1", 1],
    ["45000", 45_000],
  ])(
    "plumbs positive integer --capture-budget %s into the post-navigation budget",
    async (captureBudget, expectedBudget) => {
      vi.spyOn(console, "log").mockImplementation(() => {});
      vi.spyOn(console, "error").mockImplementation(() => {});

      await captureCommand.run!({
        args: {
          url: "https://example.com",
          output: "/tmp/hf-capture-budget-test",
          "skip-assets": false,
          "skip-vision": false,
          "capture-budget": captureBudget,
          json: true,
        },
      } as never);

      expect(captureWebsiteMock).toHaveBeenCalledWith(
        expect.objectContaining({ postNavigationBudgetMs: expectedBudget }),
        undefined,
      );
    },
  );

  it.each(["0", "-1", "0.5", "Infinity", "not-a-number"])(
    "rejects invalid --capture-budget %s before capture starts",
    async (captureBudget) => {
      vi.spyOn(console, "log").mockImplementation(() => {});
      vi.spyOn(console, "error").mockImplementation(() => {});

      await expect(
        captureCommand.run!({
          args: {
            url: "https://example.com",
            output: "/tmp/hf-invalid-capture-budget-test",
            "skip-assets": false,
            "skip-vision": false,
            "capture-budget": captureBudget,
            json: true,
          },
        } as never),
      ).rejects.toBeInstanceOf(CliRuntimeError);

      expect(captureWebsiteMock).not.toHaveBeenCalled();
    },
  );

  it.each(["0", "-1", "1.5", "3junk", "", "Infinity"])(
    "rejects invalid --max-screenshots %s before capture starts",
    async (value) => {
      vi.spyOn(console, "log").mockImplementation(() => {});
      const error = vi.spyOn(console, "error").mockImplementation(() => {});
      await expect(
        captureCommand.run!({
          args: {
            url: "https://example.com",
            output: "/tmp/hf-invalid-count",
            "max-screenshots": value,
            json: true,
          },
        } as never),
      ).rejects.toBeInstanceOf(CliRuntimeError);
      expect(error).toHaveBeenCalledWith("--max-screenshots must be a positive integer.");
      expect(captureWebsiteMock).not.toHaveBeenCalled();
    },
  );

  it("passes a validated screenshot limit into capture", async () => {
    vi.spyOn(console, "log").mockImplementation(() => {});
    await captureCommand.run!({
      args: {
        url: "https://example.com",
        output: "/tmp/hf-count",
        "max-screenshots": "3",
        json: true,
      },
    } as never);
    expect(captureWebsiteMock).toHaveBeenCalledWith(
      expect.objectContaining({ maxScreenshots: 3 }),
      undefined,
    );
  });

  it.each([
    [true, 0],
    [false, 1],
  ])("asks to end the process once its result is out (ok %s)", async (ok, exitCode) => {
    vi.useFakeTimers();
    const exit = vi.fn();
    registerRootExitRequester(exit);
    try {
      vi.spyOn(console, "log").mockImplementation(() => {});
      vi.spyOn(console, "error").mockImplementation(() => {});
      captureWebsiteMock.mockResolvedValueOnce({
        ok,
        projectDir: "/tmp/capture",
        url: "https://example.com",
        title: "Example",
        extracted: {},
        screenshots: [],
        tokens: { sections: [], fonts: [] },
        assets: [],
        warnings: [],
      });
      await captureCommand.run!({
        args: { url: "https://example.com", output: "/tmp/hf-exit", json: true },
      } as never).catch(() => {});
      expect(exit).not.toHaveBeenCalled();
      vi.advanceTimersByTime(100);
      expect(exit).toHaveBeenCalledWith(exitCode);
    } finally {
      registerRootExitRequester(() => {});
      vi.useRealTimers();
    }
  });

  it("asks to end the process with 1 after a capture that threw", async () => {
    vi.useFakeTimers();
    const exit = vi.fn();
    registerRootExitRequester(exit);
    try {
      vi.spyOn(console, "log").mockImplementation(() => {});
      vi.spyOn(console, "error").mockImplementation(() => {});
      captureWebsiteMock.mockRejectedValueOnce(new Error("browser crashed"));
      await captureCommand.run!({
        args: { url: "https://example.com", output: "/tmp/hf-exit-threw", json: true },
      } as never).catch(() => {});
      vi.advanceTimersByTime(100);
      expect(exit).toHaveBeenCalledWith(1);
    } finally {
      registerRootExitRequester(() => {});
      vi.useRealTimers();
    }
  });

  it("returns a nonzero command result after presenting failed capture JSON once", async () => {
    const log = vi.spyOn(console, "log").mockImplementation(() => {});
    vi.spyOn(console, "error").mockImplementation(() => {});
    captureWebsiteMock.mockResolvedValueOnce({
      ok: false,
      projectDir: "/tmp/capture",
      url: "https://example.com",
      title: "Example",
      extracted: {},
      screenshots: [],
      tokens: { sections: [], fonts: [] },
      assets: [],
      warnings: [
        "0/3 requested screenshot files captured: --capture-budget exhausted during lazy scrolling",
      ],
    });
    await expect(
      captureCommand.run!({
        args: {
          url: "https://example.com",
          output: "/tmp/hf-failed-capture",
          json: true,
        },
      } as never),
    ).rejects.toMatchObject({ result: { exitCode: 1 } });
    expect(log).toHaveBeenCalledTimes(1);
    expect(JSON.parse(String(log.mock.calls[0]?.[0]))).toMatchObject({ ok: false, screenshots: 0 });
  });

  it("emits a versioned phase record without the captured URL", async () => {
    vi.spyOn(console, "log").mockImplementation(() => {});
    const error = vi.spyOn(console, "error").mockImplementation(() => {});

    await captureCommand.run!({
      args: {
        url: "https://user:[email protected]/private",
        output: "/tmp/hf-phase-progress-test",
        "skip-assets": false,
        "skip-vision": false,
        json: true,
      },
    } as never);

    const line = error.mock.calls.find(
      ([value]) => typeof value === "string" && value.startsWith("HYPERFRAMES_CAPTURE_PHASE "),
    )?.[0];
    expect(typeof line).toBe("string");
    if (typeof line !== "string") throw new Error("Expected capture phase diagnostic");
    const event = JSON.parse(line.slice("HYPERFRAMES_CAPTURE_PHASE ".length));
    expect(event).toEqual({
      schema: CAPTURE_PHASE_SCHEMA,
      phase: "vision",
      status: "degraded",
      remainingMs: 0,
      reason: "budget-exhausted",
    });
    expect(line).not.toContain("secret");
    expect(line).not.toContain("/private");
  });

  it("keeps required capture failures nonzero", async () => {
    const dir = mkdtempSync(join(tmpdir(), "hf-capture-failure-"));
    const log = vi.spyOn(console, "log").mockImplementation(() => {});
    vi.spyOn(console, "error").mockImplementation(() => {});
    captureWebsiteMock.mockRejectedValueOnce(new Error("required extraction failed"));

    try {
      await expect(
        captureCommand.run!({
          args: {
            url: "https://example.com",
            output: dir,
            "skip-assets": false,
            "skip-vision": false,
            json: true,
          },
        } as never),
      ).rejects.toBeInstanceOf(CliRuntimeError);
      const payload = log.mock.calls.at(-1)?.[0];
      expect(typeof payload).toBe("string");
      if (typeof payload !== "string") throw new Error("Expected JSON failure payload");
      expect(JSON.parse(payload)).toMatchObject({ ok: false, error: "required extraction failed" });
    } finally {
      rmSync(dir, { recursive: true, force: true });
    }
  });

  it.skipIf(process.platform === "win32")(
    "writes BLOCKED.md without following a pre-planted symlink",
    async () => {
      const root = mkdtempSync(join(tmpdir(), "hf-capture-blocked-"));
      const dir = join(root, "capture");
      const victim = join(root, "victim.txt");
      mkdirSync(dir);
      writeFileSync(victim, "do not touch");
      symlinkSync(victim, join(dir, "BLOCKED.md"));
      vi.spyOn(console, "log").mockImplementation(() => {});
      vi.spyOn(console, "error").mockImplementation(() => {});
      captureWebsiteMock.mockRejectedValueOnce(new Error("blocked by the site"));

      try {
        await expect(
          captureCommand.run!({
            args: { url: "https://example.com", output: dir, json: true },
          } as never),
        ).rejects.toBeInstanceOf(CliRuntimeError);

        expect(readFileSync(victim, "utf8")).toBe("do not touch");
        expect(readFileSync(join(dir, "BLOCKED.md"), "utf8")).toContain("# Capture Failed");
        expect(lstatSync(join(dir, "BLOCKED.md")).isSymbolicLink()).toBe(false);
      } finally {
        rmSync(root, { recursive: true, force: true });
      }
    },
  );
});