mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
* feat(producer): report browser-computed reference backgrounds Preserve one initial root/page reference across local, streamed and distributed render results without guessing from film pixels. — Jerrai * fix(producer): preserve plan compatibility and optional inspection Keep reference metadata outside the v2 manifest hash and read it from the verified execution-plan artifact. Static planning uses a non-gating page inspection instead of requiring render-worker capabilities. — Jerrai * fix(producer): poll readiness independently of animation frames Use timed polling while the render clock parks animation frames. Cover readiness that changes after the first check with a short real-browser regression. — Jerrai * fix(producer): budget measured reference metadata runtime growth Producer adds 2,228 compressed bytes over current main. Tests, fixtures and source maps are already absent from its dist-only tarball. Allow 7,766 bytes of headroom above the verified 837,234-byte payload while retaining the unpacked limit. — Jerrai
2390 lines
88 KiB
TypeScript
2390 lines
88 KiB
TypeScript
// fallow-ignore-file code-duplication
|
||
import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
||
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
|
||
import { tmpdir } from "node:os";
|
||
import { join } from "node:path";
|
||
import { spawn } from "node:child_process";
|
||
import { VERSION } from "../version.js";
|
||
|
||
const producerState = vi.hoisted(() => ({
|
||
createdJobs: [] as Array<Record<string, unknown>>,
|
||
resolveConfigCalls: [] as Array<Record<string, unknown>>,
|
||
loggerLevels: [] as string[],
|
||
// Overridable per-test hook so the DE-parallel-router-trial tests can
|
||
// mutate the job (perfSummary/errorDetails) or throw, without perturbing
|
||
// every other test in this file that expects a plain no-op resolve.
|
||
executeImpl: async (
|
||
_job: Record<string, unknown>,
|
||
_abortSignal?: AbortSignal,
|
||
_assertRenderActive?: () => void,
|
||
): Promise<void> => undefined,
|
||
}));
|
||
|
||
// Defaults to "trial already fired" so the pre-existing renderLocal tests
|
||
// below (which predate the DE-parallel-router trial and don't expect
|
||
// HF_DE_PARALLEL_ROUTER to be touched) keep their exact prior behavior.
|
||
//
|
||
// `disk` is the authoritative "file"; `cache` models config.ts's real
|
||
// process-lifetime cachedConfig. Modeling them SEPARATELY matters: a mock
|
||
// where readConfig/readConfigFresh both read one live object hides exactly
|
||
// the class of bug where production code reads the stale cache when it
|
||
// needed a fresh disk read (review finding). `failWrites` simulates the
|
||
// real writeConfig's silent fs-error swallowing (unwritable ~/.hyperframes):
|
||
// the next N writes are recorded but never reach `disk`.
|
||
const configState = vi.hoisted(
|
||
(): {
|
||
disk: Record<string, unknown>;
|
||
cache: Record<string, unknown> | null;
|
||
writeConfigCalls: Array<Record<string, unknown>>;
|
||
failWrites: number;
|
||
/** Config write lands but the install-state mirror does not. */
|
||
failMirrors: number;
|
||
} => ({
|
||
disk: { telemetryEnabled: true, deParallelRouterTrialFired: true },
|
||
cache: null,
|
||
writeConfigCalls: [],
|
||
failWrites: 0,
|
||
failMirrors: 0,
|
||
}),
|
||
);
|
||
|
||
const trackingState = vi.hoisted(() => ({
|
||
// maybeEnableDeParallelRouterTrial gates on the real shouldTrack(), which
|
||
// (via isDevMode()) always returns false when this file itself runs as
|
||
// `.ts` source under vitest — mocked here so the CLI-trial tests can
|
||
// control it directly instead of inheriting that environment quirk.
|
||
shouldTrack: true,
|
||
renderObservations: [] as Array<Record<string, unknown>>,
|
||
}));
|
||
|
||
const preflightState = vi.hoisted(() => ({
|
||
onRun: undefined as (() => void) | undefined,
|
||
result: {
|
||
outcomes: [
|
||
{ name: "FFmpeg", ok: true, level: "ok", detail: "/usr/bin/ffmpeg", path: "/usr/bin/ffmpeg" },
|
||
{
|
||
name: "FFprobe",
|
||
ok: true,
|
||
level: "ok",
|
||
detail: "/usr/bin/ffprobe",
|
||
path: "/usr/bin/ffprobe",
|
||
},
|
||
{
|
||
name: "Chrome",
|
||
ok: true,
|
||
level: "ok",
|
||
detail: "cache: /mock/chrome",
|
||
path: "/mock/chrome",
|
||
},
|
||
],
|
||
ffmpegPath: "/usr/bin/ffmpeg",
|
||
ffprobePath: "/usr/bin/ffprobe",
|
||
browser: { executablePath: "/mock/chrome", source: "cache" },
|
||
},
|
||
}));
|
||
|
||
const ffmpegEncoderState = vi.hoisted(() => ({
|
||
mode: "software" as "software" | "gpu",
|
||
error: null as Error | null,
|
||
encoders: null as string | null,
|
||
usableGpu: false,
|
||
}));
|
||
const orphanCleanupState = vi.hoisted(() => ({
|
||
calls: 0,
|
||
killed: 0,
|
||
parentPid: (_pid: number): number | null => null,
|
||
identity: (_pid: number): string | null => null,
|
||
}));
|
||
const browserManagerState = vi.hoisted(() => ({
|
||
onEnsure: undefined as ((signal?: AbortSignal) => Promise<void> | void) | undefined,
|
||
}));
|
||
|
||
vi.mock("../utils/producer.js", () => ({
|
||
loadProducer: vi.fn(async () => ({
|
||
...(await import("../../../engine/src/services/referenceBackground.js")),
|
||
createConsoleLogger: vi.fn((level: string) => {
|
||
producerState.loggerLevels.push(level);
|
||
return { error: vi.fn(), warn: vi.fn(), info: vi.fn(), debug: vi.fn() };
|
||
}),
|
||
resolveConfig: vi.fn((overrides: Record<string, unknown>) => {
|
||
producerState.resolveConfigCalls.push(overrides);
|
||
return { ...overrides, resolved: true };
|
||
}),
|
||
createRenderRequest: vi.fn(
|
||
(input: {
|
||
projectDir: string;
|
||
outputPath: string;
|
||
engineConfig: unknown;
|
||
options: object;
|
||
}) => ({
|
||
version: 1,
|
||
projectDir: input.projectDir,
|
||
outputPath: input.outputPath,
|
||
options: { ...input.options, engineConfig: input.engineConfig },
|
||
}),
|
||
),
|
||
renderConfigFromRequest: vi.fn(
|
||
(request: { options: Record<string, unknown> }, runtime: { logger?: unknown }) => {
|
||
const { engineConfig, ...options } = request.options;
|
||
return { ...options, producerConfig: engineConfig, logger: runtime.logger };
|
||
},
|
||
),
|
||
createRenderJob: vi.fn((config: Record<string, unknown>) => {
|
||
producerState.createdJobs.push(config);
|
||
return { config, progress: 100, outcome: "completed", warnings: [] };
|
||
}),
|
||
executeRenderJob: vi.fn(
|
||
async (
|
||
job: Record<string, unknown>,
|
||
_projectDir: string,
|
||
_outputPath: string,
|
||
_onProgress: unknown,
|
||
abortSignal?: AbortSignal,
|
||
assertRenderActive?: () => void,
|
||
) => producerState.executeImpl(job, abortSignal, assertRenderActive),
|
||
),
|
||
})),
|
||
}));
|
||
|
||
vi.mock("../telemetry/config.js", () => ({
|
||
readConfig: vi.fn(() => {
|
||
if (!configState.cache) configState.cache = { ...configState.disk };
|
||
return { ...configState.cache };
|
||
}),
|
||
readConfigFresh: vi.fn(() => {
|
||
configState.cache = { ...configState.disk };
|
||
return { ...configState.disk };
|
||
}),
|
||
recordRecentRender: vi.fn((id: string, ok: boolean) => {
|
||
// Mirrors the real ring update (readConfigFresh → append, cap 5 → write)
|
||
// against the mock's disk state, so a render's recent-renders write is
|
||
// modeled like every other config mutation here. Fixed timestamp keeps it
|
||
// deterministic (tests never assert on `at`).
|
||
const disk = configState.disk as Record<string, unknown>;
|
||
const ring = [
|
||
...((disk.recentRenders as unknown[]) ?? []),
|
||
{ id, at: "2026-01-01T00:00:00Z", ok },
|
||
];
|
||
const next = { ...disk, recentRenders: ring.slice(-5) };
|
||
configState.disk = next;
|
||
configState.cache = { ...next };
|
||
}),
|
||
writeConfig: vi.fn((config: Record<string, unknown>) => {
|
||
configState.writeConfigCalls.push({ ...config });
|
||
if (configState.failWrites > 0) {
|
||
configState.failWrites--;
|
||
return false; // swallowed silently, like the real writeConfig's catch {}
|
||
}
|
||
configState.disk = { ...config };
|
||
configState.cache = { ...config };
|
||
return true;
|
||
}),
|
||
releaseDeParallelRouterLatch: vi.fn(() => {
|
||
configState.disk = { ...configState.disk, deParallelRouterTrialFired: undefined };
|
||
configState.cache = { ...configState.disk };
|
||
}),
|
||
// The breaker's safety path uses this rather than writeConfig, so it can
|
||
// see a mirror failure instead of having it collapsed into `true`.
|
||
writeConfigWithResult: vi.fn((config: Record<string, unknown>) => {
|
||
configState.writeConfigCalls.push({ ...config });
|
||
if (configState.failWrites > 0) {
|
||
configState.failWrites--;
|
||
return { ok: false, error: "mock write failure" };
|
||
}
|
||
configState.disk = { ...config };
|
||
configState.cache = { ...config };
|
||
if (configState.failMirrors > 0) {
|
||
configState.failMirrors--;
|
||
return { ok: true, mirrored: false };
|
||
}
|
||
return { ok: true };
|
||
}),
|
||
}));
|
||
|
||
vi.mock("../telemetry/client.js", () => ({
|
||
shouldTrack: vi.fn(() => trackingState.shouldTrack),
|
||
}));
|
||
|
||
vi.mock("../telemetry/events.js", () => ({
|
||
trackRenderComplete: vi.fn(),
|
||
trackRenderError: vi.fn(),
|
||
trackRenderObservation: vi.fn((props: Record<string, unknown>) => {
|
||
trackingState.renderObservations.push(props);
|
||
}),
|
||
}));
|
||
|
||
vi.mock("../browser/ffmpeg.js", async (importOriginal) => {
|
||
const actual = await importOriginal<typeof import("../browser/ffmpeg.js")>();
|
||
return {
|
||
...actual,
|
||
detectH264EncoderModeForRender: vi.fn(async (_path: string, gpuRequested: boolean) => {
|
||
if (ffmpegEncoderState.error) throw ffmpegEncoderState.error;
|
||
if (ffmpegEncoderState.encoders !== null)
|
||
return actual.resolveH264EncoderMode(
|
||
ffmpegEncoderState.encoders,
|
||
gpuRequested,
|
||
ffmpegEncoderState.usableGpu,
|
||
);
|
||
return ffmpegEncoderState.mode;
|
||
}),
|
||
findFFmpeg: vi.fn(() => "/usr/bin/ffmpeg"),
|
||
getFFmpegInstallHint: vi.fn(() => "brew install ffmpeg"),
|
||
};
|
||
});
|
||
|
||
vi.mock("../browser/preflight.js", () => ({
|
||
checkDisk: vi.fn(() => ({ name: "Disk", ok: true, level: "ok", detail: "mock" })),
|
||
runEnvironmentChecks: vi.fn(async () => {
|
||
preflightState.onRun?.();
|
||
return preflightState.result;
|
||
}),
|
||
}));
|
||
|
||
// The "render command explicit composition" test below drives the real
|
||
// `render.js` command handler, which takes the plan-based `execute.ts` path
|
||
// (not the `renderLocal` unit under test above) — that path calls
|
||
// `ensureBrowser` directly instead of going through the mocked preflight.
|
||
// Unmocked, it performs a real network download of chrome-headless-shell into
|
||
// the shared `~/.cache/hyperframes/chrome`, racing other packages' browser
|
||
// tests in CI.
|
||
vi.mock("../browser/manager.js", () => ({
|
||
sweepKilledInstalls: vi.fn(async () => {}),
|
||
ensureBrowser: vi.fn(async (options?: { signal?: AbortSignal }) => {
|
||
await browserManagerState.onEnsure?.(options?.signal);
|
||
return { executablePath: "/mock/chrome", source: "cache" };
|
||
}),
|
||
}));
|
||
|
||
vi.mock("../utils/orphanCleanup.js", () => ({
|
||
killOrphanedProcesses: vi.fn(() => {
|
||
orphanCleanupState.calls += 1;
|
||
return orphanCleanupState.killed;
|
||
}),
|
||
killOrphanedProcessesForRender: vi.fn(async () => {
|
||
orphanCleanupState.calls += 1;
|
||
return orphanCleanupState.killed;
|
||
}),
|
||
processIdentity: vi.fn((pid: number) => orphanCleanupState.identity(pid)),
|
||
processAncestorSnapshot: vi.fn((pid: number) => {
|
||
const parent = orphanCleanupState.parentPid(pid);
|
||
if (parent === null) return [];
|
||
const identity = orphanCleanupState.identity(parent);
|
||
return identity === null ? [] : [{ pid: parent, identity }];
|
||
}),
|
||
processParentPid: vi.fn((pid: number) => orphanCleanupState.parentPid(pid)),
|
||
}));
|
||
|
||
const cpuSamplerState = vi.hoisted(() => ({
|
||
samplers: [] as { requesterOptedIn: boolean; stopped: boolean }[],
|
||
}));
|
||
vi.mock("../telemetry/renderCpu.js", () => ({
|
||
startRenderCpuSampler: (requesterOptedIn = true) => {
|
||
const sampler = { requesterOptedIn, stopped: false };
|
||
cpuSamplerState.samplers.push(sampler);
|
||
return {
|
||
stop: () => {
|
||
sampler.stopped = true;
|
||
return { cpuBusyAvgPct: 57, cpuBusyPeakPct: 90 };
|
||
},
|
||
};
|
||
},
|
||
}));
|
||
|
||
// Collect the heavy render module once, after Vitest has hoisted the mocks
|
||
// above. Keeping this import out of a hook means parallel monorepo contention
|
||
// cannot turn module collection into a `beforeAll` timeout.
|
||
const renderModule = await import("./render.js");
|
||
|
||
// A private folder, never a fixed /tmp path: a render writes history into its project.
|
||
const PROJECT_DIR = mkdtempSync(join(tmpdir(), "hf-render-project-"));
|
||
afterAll(() => rmSync(PROJECT_DIR, { recursive: true, force: true }));
|
||
|
||
describe("renderLocal browser GPU config", () => {
|
||
const savedEnv = new Map<string, string | undefined>();
|
||
const {
|
||
renderLocal,
|
||
resolveBrowserGpuForCli,
|
||
renderLintContinuationHint,
|
||
runRenderLint,
|
||
__resetDeParallelRouterTrialStateForTests: resetTrialState,
|
||
} = renderModule;
|
||
|
||
it("points strict warning-only renders to --strict-all", () => {
|
||
expect(renderLintContinuationHint(true)).toContain("--strict-all");
|
||
expect(renderLintContinuationHint(true)).not.toContain("Use --strict to block");
|
||
});
|
||
|
||
it("points non-strict renders to --strict for lint errors", () => {
|
||
expect(renderLintContinuationHint(false)).toContain("Use --strict to block errors");
|
||
});
|
||
|
||
it("aborts the real render lint preflight on a default-entry mismatch without --strict", async () => {
|
||
const lintResult = {
|
||
results: [
|
||
{
|
||
file: "index.html",
|
||
contentHash: "abc",
|
||
result: {
|
||
ok: false,
|
||
errorCount: 1,
|
||
warningCount: 0,
|
||
infoCount: 0,
|
||
findings: [
|
||
{
|
||
code: "blank_root_with_standalone_composition",
|
||
severity: "error" as const,
|
||
message: "wrong entry",
|
||
},
|
||
],
|
||
},
|
||
},
|
||
],
|
||
totalErrors: 1,
|
||
totalWarnings: 0,
|
||
totalInfos: 0,
|
||
};
|
||
|
||
await expect(
|
||
runRenderLint(
|
||
{
|
||
project: { dir: PROJECT_DIR },
|
||
entryFile: undefined,
|
||
renderTarget: join(PROJECT_DIR, "index.html"),
|
||
strictErrors: false,
|
||
strictAll: false,
|
||
effectiveQuiet: true,
|
||
} as never,
|
||
async () => lintResult,
|
||
),
|
||
).rejects.toMatchObject({ name: "CliRuntimeError" });
|
||
});
|
||
|
||
it("prints the full finding on a default-entry-mismatch abort even without --lint-verbose", async () => {
|
||
const lintResult = {
|
||
results: [
|
||
{
|
||
file: "index.html",
|
||
contentHash: "abc",
|
||
result: {
|
||
ok: false,
|
||
errorCount: 1,
|
||
warningCount: 0,
|
||
infoCount: 0,
|
||
findings: [
|
||
{
|
||
code: "blank_root_with_standalone_composition",
|
||
severity: "error" as const,
|
||
message: "The default index.html composition has no renderable content",
|
||
fixHint: "Move the authored composition into index.html",
|
||
},
|
||
],
|
||
},
|
||
},
|
||
],
|
||
totalErrors: 1,
|
||
totalWarnings: 0,
|
||
totalInfos: 0,
|
||
};
|
||
const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
|
||
|
||
await expect(
|
||
runRenderLint(
|
||
{
|
||
project: { dir: PROJECT_DIR },
|
||
entryFile: undefined,
|
||
renderTarget: join(PROJECT_DIR, "index.html"),
|
||
strictErrors: false,
|
||
strictAll: false,
|
||
effectiveQuiet: false,
|
||
lintVerbose: false,
|
||
} as never,
|
||
async () => lintResult,
|
||
),
|
||
).rejects.toMatchObject({ name: "CliRuntimeError" });
|
||
|
||
const output = logSpy.mock.calls.map((c) => c[0]).join("\n");
|
||
expect(output).toContain("blank_root_with_standalone_composition");
|
||
expect(output).toContain("The default index.html composition has no renderable content");
|
||
logSpy.mockRestore();
|
||
});
|
||
|
||
it("prints a one-line summary by default, and full findings when lintVerbose is set", async () => {
|
||
const lintResult = {
|
||
results: [
|
||
{
|
||
file: "index.html",
|
||
contentHash: "abc",
|
||
result: {
|
||
ok: true,
|
||
errorCount: 0,
|
||
warningCount: 1,
|
||
infoCount: 0,
|
||
findings: [
|
||
{ code: "some_warning", severity: "warning" as const, message: "a warning" },
|
||
],
|
||
},
|
||
},
|
||
],
|
||
totalErrors: 0,
|
||
totalWarnings: 1,
|
||
totalInfos: 0,
|
||
};
|
||
const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
|
||
|
||
await runRenderLint(
|
||
{
|
||
project: { dir: PROJECT_DIR },
|
||
entryFile: undefined,
|
||
renderTarget: join(PROJECT_DIR, "index.html"),
|
||
strictErrors: false,
|
||
strictAll: false,
|
||
effectiveQuiet: false,
|
||
lintVerbose: false,
|
||
} as never,
|
||
async () => lintResult,
|
||
);
|
||
const summaryOutput = logSpy.mock.calls.map((c) => c[0]).join("\n");
|
||
expect(summaryOutput).toContain("1 warning(s)");
|
||
expect(summaryOutput).not.toContain("some_warning");
|
||
|
||
logSpy.mockClear();
|
||
await runRenderLint(
|
||
{
|
||
project: { dir: PROJECT_DIR },
|
||
entryFile: undefined,
|
||
renderTarget: join(PROJECT_DIR, "index.html"),
|
||
strictErrors: false,
|
||
strictAll: false,
|
||
effectiveQuiet: false,
|
||
lintVerbose: true,
|
||
} as never,
|
||
async () => lintResult,
|
||
);
|
||
const verboseOutput = logSpy.mock.calls.map((c) => c[0]).join("\n");
|
||
expect(verboseOutput).toContain("some_warning");
|
||
|
||
logSpy.mockRestore();
|
||
});
|
||
|
||
function setEnv(key: string, value: string) {
|
||
if (!savedEnv.has(key)) savedEnv.set(key, process.env[key]);
|
||
process.env[key] = value;
|
||
}
|
||
|
||
beforeEach(() => {
|
||
producerState.createdJobs = [];
|
||
producerState.resolveConfigCalls = [];
|
||
producerState.loggerLevels = [];
|
||
producerState.executeImpl = async () => undefined;
|
||
preflightState.onRun = undefined;
|
||
configState.disk = { telemetryEnabled: true, deParallelRouterTrialFired: true };
|
||
configState.cache = null;
|
||
configState.failWrites = 0;
|
||
configState.failMirrors = 0;
|
||
configState.writeConfigCalls = [];
|
||
trackingState.shouldTrack = true;
|
||
trackingState.renderObservations = [];
|
||
ffmpegEncoderState.mode = "software";
|
||
ffmpegEncoderState.error = null;
|
||
ffmpegEncoderState.encoders = null;
|
||
ffmpegEncoderState.usableGpu = false;
|
||
orphanCleanupState.calls = 0;
|
||
orphanCleanupState.killed = 0;
|
||
orphanCleanupState.parentPid = () => null;
|
||
orphanCleanupState.identity = () => null;
|
||
browserManagerState.onEnsure = undefined;
|
||
resetTrialState();
|
||
savedEnv.clear();
|
||
savedEnv.set("HYPERFRAMES_FFMPEG_PATH", process.env.HYPERFRAMES_FFMPEG_PATH);
|
||
savedEnv.set("HYPERFRAMES_FFPROBE_PATH", process.env.HYPERFRAMES_FFPROBE_PATH);
|
||
savedEnv.set("PRODUCER_HEADLESS_SHELL_PATH", process.env.PRODUCER_HEADLESS_SHELL_PATH);
|
||
savedEnv.set("HF_DE_PARALLEL_ROUTER", process.env.HF_DE_PARALLEL_ROUTER);
|
||
delete process.env.HYPERFRAMES_FFMPEG_PATH;
|
||
delete process.env.HYPERFRAMES_FFPROBE_PATH;
|
||
delete process.env.PRODUCER_HEADLESS_SHELL_PATH;
|
||
delete process.env.HF_DE_PARALLEL_ROUTER;
|
||
});
|
||
|
||
it("reports the render's CPU use on render_complete and render_error and stops measuring", async () => {
|
||
const { trackRenderComplete, trackRenderError } = await import("../telemetry/events.js");
|
||
vi.mocked(trackRenderComplete).mockClear();
|
||
vi.mocked(trackRenderError).mockClear();
|
||
cpuSamplerState.samplers = [];
|
||
const options = {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
throwOnError: true,
|
||
} as const;
|
||
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", options);
|
||
producerState.executeImpl = async () => {
|
||
throw new Error("capture failed");
|
||
};
|
||
await expect(renderLocal(PROJECT_DIR, "/tmp/out.mp4", options)).rejects.toThrow(
|
||
"capture failed",
|
||
);
|
||
|
||
const cpu = { cpuBusyAvgPct: 57, cpuBusyPeakPct: 90 };
|
||
expect(vi.mocked(trackRenderComplete).mock.calls[0]?.[0]).toMatchObject(cpu);
|
||
expect(vi.mocked(trackRenderError).mock.calls[0]?.[0]).toMatchObject(cpu);
|
||
expect(cpuSamplerState.samplers.map((s) => s.stopped)).toEqual([true, true]);
|
||
});
|
||
|
||
it.each([
|
||
{ kind: "solid", rgb: [10, 46, 138] },
|
||
{ kind: "none" },
|
||
{ kind: "unsupported_non_solid" },
|
||
{ kind: "unknown" },
|
||
])("returns the same $kind background object as the remote receipt", async (background) => {
|
||
producerState.executeImpl = async (job) => {
|
||
job.reference_background = background;
|
||
};
|
||
const result = await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
throwOnError: true,
|
||
});
|
||
expect(result?.reference_background).toEqual(background);
|
||
});
|
||
|
||
it("warns that the whole mix was lowered, and the render still completes", async () => {
|
||
const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
|
||
producerState.executeImpl = async (job: { audioLoweredDb?: number }) => {
|
||
job.audioLoweredDb = 7.3;
|
||
};
|
||
|
||
const result = await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
throwOnError: true,
|
||
});
|
||
|
||
expect(warn).toHaveBeenCalledWith(expect.stringContaining("[audio_lowered] Audio lowered 7.3"));
|
||
expect(result?.outcome).toBe("completed");
|
||
expect(result?.warnings?.map((warning) => warning.code)).toEqual(["audio_lowered"]);
|
||
warn.mockRestore();
|
||
});
|
||
|
||
it("cleans orphaned browser trees before starting a local render", async () => {
|
||
orphanCleanupState.killed = 1;
|
||
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
});
|
||
|
||
expect(orphanCleanupState.calls).toBe(1);
|
||
});
|
||
|
||
it("owns cancellation before preflight so an early wrapper loss cannot start rendering", async () => {
|
||
const priorListeners = new Set(process.listeners("SIGTERM"));
|
||
let rendererStarted = false;
|
||
preflightState.onRun = () => {
|
||
const cancellationListener = process
|
||
.listeners("SIGTERM")
|
||
.find((listener) => !priorListeners.has(listener));
|
||
expect(cancellationListener).toBeDefined();
|
||
cancellationListener?.("SIGTERM");
|
||
};
|
||
producerState.executeImpl = async (_job, abortSignal) => {
|
||
if (!abortSignal?.aborted) rendererStarted = true;
|
||
throw abortSignal?.reason;
|
||
};
|
||
|
||
await expect(
|
||
renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
throwOnError: true,
|
||
}),
|
||
).rejects.toThrow("render_cancelled_by_sigterm");
|
||
|
||
expect(rendererStarted).toBe(false);
|
||
expect(
|
||
process.listeners("SIGTERM").filter((listener) => !priorListeners.has(listener)),
|
||
).toEqual([]);
|
||
});
|
||
|
||
it.each(["SIGINT", "SIGTERM", "SIGHUP"] as const)(
|
||
"wires %s to the producer AbortSignal and removes render-scoped listeners",
|
||
async (signal) => {
|
||
let markExecutionStarted!: () => void;
|
||
const executionStarted = new Promise<void>((resolve) => {
|
||
markExecutionStarted = resolve;
|
||
});
|
||
let producerSignal: AbortSignal | undefined;
|
||
producerState.executeImpl = async (_job, abortSignal) => {
|
||
producerSignal = abortSignal;
|
||
markExecutionStarted();
|
||
await new Promise<void>((_resolve, reject) => {
|
||
abortSignal?.addEventListener("abort", () => reject(abortSignal.reason), { once: true });
|
||
});
|
||
};
|
||
const priorListeners = new Set(process.listeners(signal));
|
||
|
||
const render = renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
throwOnError: true,
|
||
});
|
||
await executionStarted;
|
||
|
||
const cancellationListener = process
|
||
.listeners(signal)
|
||
.find((listener) => !priorListeners.has(listener));
|
||
expect(cancellationListener).toBeDefined();
|
||
cancellationListener?.(signal);
|
||
expect(process.listeners(signal)).toContain(cancellationListener);
|
||
cancellationListener?.(signal);
|
||
|
||
await expect(render).rejects.toThrow(`render_cancelled_by_${signal.toLowerCase()}`);
|
||
expect(producerSignal).toBeInstanceOf(AbortSignal);
|
||
expect(producerSignal?.aborted).toBe(true);
|
||
expect(process.listeners(signal).filter((listener) => !priorListeners.has(listener))).toEqual(
|
||
[],
|
||
);
|
||
},
|
||
);
|
||
|
||
it("checks ancestors again at producer artifact finalization", async () => {
|
||
const controller = new AbortController();
|
||
let parentExited = false;
|
||
const cancellation = {
|
||
signal: controller.signal,
|
||
checkAncestors: vi.fn(() => {
|
||
if (parentExited) controller.abort(new Error("render_cancelled_parent_exited"));
|
||
}),
|
||
dispose: vi.fn(),
|
||
};
|
||
producerState.executeImpl = async (_job, abortSignal, assertRenderActive) => {
|
||
parentExited = true;
|
||
assertRenderActive?.();
|
||
abortSignal?.throwIfAborted();
|
||
};
|
||
|
||
await expect(
|
||
renderLocal(
|
||
PROJECT_DIR,
|
||
"/tmp/out.mp4",
|
||
{
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
throwOnError: true,
|
||
},
|
||
cancellation,
|
||
),
|
||
).rejects.toThrow("render_cancelled_parent_exited");
|
||
|
||
expect(cancellation.checkAncestors).toHaveBeenLastCalledWith();
|
||
});
|
||
|
||
afterEach(() => {
|
||
for (const [key, value] of savedEnv) {
|
||
if (value === undefined) {
|
||
delete process.env[key];
|
||
} else {
|
||
process.env[key] = value;
|
||
}
|
||
}
|
||
vi.clearAllMocks();
|
||
vi.useRealTimers();
|
||
vi.restoreAllMocks();
|
||
});
|
||
|
||
it.each([
|
||
{ quiet: false, interrupted: false, emits: true },
|
||
{ quiet: false, interrupted: true, emits: true },
|
||
{ quiet: true, interrupted: false, emits: false },
|
||
])("writes the failure diagnostic only for piped non-JSON output: %j", async (mode) => {
|
||
const projectDir = mkdtempSync(join(tmpdir(), "hf-render-diagnostic-"));
|
||
const failures = [
|
||
{
|
||
stage: "prepare",
|
||
reason: "ffmpeg_failed",
|
||
owner: "system",
|
||
retryable: false,
|
||
subprocess: { exitCode: 7, terminationReason: "exit" },
|
||
detail: "private-detail",
|
||
elementId: "private-id",
|
||
},
|
||
];
|
||
producerState.executeImpl = async (job) => {
|
||
if (mode.interrupted) throw Object.assign(new Error("failed"), { audioFailures: failures });
|
||
job.warnings = [
|
||
{
|
||
code: "audio_processing_failed",
|
||
message: "private-warning",
|
||
details: { audioFailures: failures },
|
||
},
|
||
];
|
||
throw new Error("failed");
|
||
};
|
||
const originalIsTTY = process.stdout.isTTY;
|
||
Object.defineProperty(process.stdout, "isTTY", { value: false, configurable: true });
|
||
let output = "";
|
||
vi.spyOn(process.stdout, "write").mockImplementation((chunk) => {
|
||
output += String(chunk);
|
||
return true;
|
||
});
|
||
try {
|
||
await expect(
|
||
renderLocal(projectDir, join(projectDir, "out.mp4"), {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
quiet: mode.quiet,
|
||
throwOnError: true,
|
||
}),
|
||
).rejects.toThrow("failed");
|
||
const lines = output.split("\n").filter((line) => line.startsWith("@hf-diagnostic "));
|
||
expect(lines).toHaveLength(mode.emits ? 1 : 0);
|
||
if (mode.emits) {
|
||
expect(
|
||
JSON.parse((lines[0] ?? "").slice("@hf-diagnostic ".length)).audioFailures[0].subprocess
|
||
.exitCode,
|
||
).toBe(7);
|
||
expect(lines[0] ?? "").not.toMatch(/private-/);
|
||
}
|
||
} finally {
|
||
Object.defineProperty(process.stdout, "isTTY", { value: originalIsTTY, configurable: true });
|
||
rmSync(projectDir, { recursive: true, force: true });
|
||
}
|
||
});
|
||
|
||
it("logs only warnings and errors from the producer under --quiet", async () => {
|
||
const options = {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
} as const;
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", { ...options, quiet: true });
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", { ...options, quiet: false });
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", { ...options, quiet: true, debug: true });
|
||
|
||
expect(producerState.loggerLevels).toEqual(["warn", "info", "debug"]);
|
||
});
|
||
|
||
it("passes an explicit software override for --no-browser-gpu even when env requests hardware", async () => {
|
||
setEnv("PRODUCER_BROWSER_GPU_MODE", "hardware");
|
||
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
});
|
||
|
||
expect(producerState.resolveConfigCalls).toContainEqual({ browserGpuMode: "software" });
|
||
expect(producerState.createdJobs[0]?.producerConfig).toMatchObject({
|
||
browserGpuMode: "software",
|
||
resolved: true,
|
||
});
|
||
}, 15_000);
|
||
|
||
it("forwards render stage start and end lifecycle events to telemetry", async () => {
|
||
producerState.executeImpl = async (job) => {
|
||
const logger = (job.config as { logger: { info: (message: string, meta: object) => void } })
|
||
.logger;
|
||
logger.info("[Render:trace]", {
|
||
renderJobId: "render-lifecycle",
|
||
phase: "capture_streaming",
|
||
status: "start",
|
||
elapsedMs: 100,
|
||
workerCount: 1,
|
||
captureMode: "screenshot",
|
||
captureOperation: "captureScreenshot",
|
||
framesCompleted: 12,
|
||
totalFrames: 900,
|
||
});
|
||
logger.info("[Render:trace]", {
|
||
renderJobId: "render-lifecycle",
|
||
phase: "capture_streaming",
|
||
status: "end",
|
||
elapsedMs: 250,
|
||
durationMs: 150,
|
||
});
|
||
};
|
||
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
skipFeedback: true,
|
||
});
|
||
|
||
expect(trackingState.renderObservations).toEqual([
|
||
expect.objectContaining({
|
||
renderJobId: "render-lifecycle",
|
||
phase: "capture_streaming",
|
||
status: "start",
|
||
captureOperation: "captureScreenshot",
|
||
framesCompleted: 12,
|
||
totalFrames: 900,
|
||
}),
|
||
expect.objectContaining({
|
||
renderJobId: "render-lifecycle",
|
||
phase: "capture_streaming",
|
||
status: "end",
|
||
durationMs: 150,
|
||
}),
|
||
]);
|
||
});
|
||
|
||
it("forwards browserGpuMode='auto' into producer config (probe-then-choose)", async () => {
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "auto",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
});
|
||
|
||
expect(producerState.resolveConfigCalls).toContainEqual({
|
||
browserGpuMode: "auto",
|
||
forceScreenshot: false,
|
||
beginFrameFirstFrameDeadlineMs: 20_000,
|
||
});
|
||
expect(producerState.createdJobs[0]?.producerConfig).toMatchObject({
|
||
browserGpuMode: "auto",
|
||
resolved: true,
|
||
});
|
||
});
|
||
|
||
it("honors PRODUCER_FORCE_SCREENSHOT=true even on local auto GPU", async () => {
|
||
const prev = process.env.PRODUCER_FORCE_SCREENSHOT;
|
||
process.env.PRODUCER_FORCE_SCREENSHOT = "true";
|
||
try {
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "auto",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
});
|
||
expect(producerState.resolveConfigCalls).toContainEqual({ browserGpuMode: "auto" });
|
||
expect(producerState.resolveConfigCalls[0]).not.toHaveProperty("forceScreenshot");
|
||
} finally {
|
||
if (prev === undefined) delete process.env.PRODUCER_FORCE_SCREENSHOT;
|
||
else process.env.PRODUCER_FORCE_SCREENSHOT = prev;
|
||
}
|
||
});
|
||
|
||
it("keeps the screenshot clamp when --resolution supersamples", async () => {
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "auto",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
outputResolution: "landscape",
|
||
});
|
||
|
||
expect(producerState.resolveConfigCalls).toContainEqual({ browserGpuMode: "auto" });
|
||
expect(producerState.resolveConfigCalls[0]).not.toHaveProperty("forceScreenshot");
|
||
expect(producerState.resolveConfigCalls[0]).not.toHaveProperty(
|
||
"beginFrameFirstFrameDeadlineMs",
|
||
);
|
||
});
|
||
|
||
it("passes an explicit hardware override for default local browser GPU", async () => {
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "hardware",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
});
|
||
|
||
expect(producerState.resolveConfigCalls).toContainEqual({ browserGpuMode: "hardware" });
|
||
expect(producerState.createdJobs[0]?.producerConfig).toMatchObject({
|
||
browserGpuMode: "hardware",
|
||
resolved: true,
|
||
});
|
||
});
|
||
|
||
it("passes preflight-resolved FFmpeg, FFprobe, and browser paths through env", async () => {
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
});
|
||
|
||
expect(process.env.HYPERFRAMES_FFMPEG_PATH).toBe("/usr/bin/ffmpeg");
|
||
expect(process.env.HYPERFRAMES_FFPROBE_PATH).toBe("/usr/bin/ffprobe");
|
||
expect(process.env.PRODUCER_HEADLESS_SHELL_PATH).toBe("/mock/chrome");
|
||
});
|
||
|
||
it("falls back to hardware encoding when FFmpeg omits libx264", async () => {
|
||
ffmpegEncoderState.mode = "gpu";
|
||
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "high",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "force-sdr",
|
||
quiet: true,
|
||
});
|
||
|
||
expect(producerState.createdJobs[0]?.useGpu).toBe(true);
|
||
});
|
||
|
||
it("rejects confirmed unsupported SDR MP4 before loading the producer", async () => {
|
||
ffmpegEncoderState.encoders = " V....D h264_vaapi H.264/AVC (VAAPI)\n";
|
||
const { loadProducer } = await import("../utils/producer.js");
|
||
vi.mocked(loadProducer).mockClear();
|
||
const stderr = vi.spyOn(console, "error").mockImplementation(() => undefined);
|
||
|
||
await expect(
|
||
renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "high",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "force-sdr",
|
||
quiet: true,
|
||
}),
|
||
).rejects.toMatchObject({ name: "CliRuntimeError" });
|
||
|
||
expect(loadProducer).not.toHaveBeenCalled();
|
||
expect(producerState.createdJobs).toHaveLength(0);
|
||
expect(stderr.mock.calls.flat().join(" ")).toContain("libx264");
|
||
});
|
||
|
||
it("refuses a --gpu MP4 before capture when no GPU encoder works and FFmpeg lacks libx264", async () => {
|
||
ffmpegEncoderState.encoders = " V....D libopenh264 OpenH264\n V....D h264_videotoolbox H.264\n";
|
||
const stderr = vi.spyOn(console, "error").mockImplementation(() => undefined);
|
||
|
||
await expect(
|
||
renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "high",
|
||
format: "mp4",
|
||
gpu: true,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
}),
|
||
).rejects.toMatchObject({ name: "CliRuntimeError" });
|
||
|
||
expect(producerState.createdJobs).toHaveLength(0);
|
||
expect(stderr.mock.calls.flat().join(" ")).toContain("libx264");
|
||
});
|
||
|
||
it.each(["webm", "mov", "png-sequence"] as const)(
|
||
"does not require H.264 for %s",
|
||
async (format) => {
|
||
ffmpegEncoderState.encoders = " V....D libvpx-vp9 VP9\n";
|
||
await renderLocal(PROJECT_DIR, `/tmp/out.${format}`, {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "high",
|
||
format,
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "force-sdr",
|
||
quiet: true,
|
||
});
|
||
expect(producerState.createdJobs).toHaveLength(1);
|
||
},
|
||
);
|
||
|
||
it.each(["auto", "force-hdr"] as const)(
|
||
"does not reject potential HEVC output in %s mode",
|
||
async (hdrMode) => {
|
||
ffmpegEncoderState.encoders = " V....D libx265 HEVC\n";
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "high",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode,
|
||
quiet: true,
|
||
});
|
||
expect(producerState.createdJobs).toHaveLength(1);
|
||
},
|
||
);
|
||
|
||
it("lets the encoder surface its own error when capability detection fails", async () => {
|
||
ffmpegEncoderState.error = new Error("encoder probe timed out");
|
||
const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
|
||
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "high",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "force-sdr",
|
||
quiet: true,
|
||
});
|
||
|
||
expect(producerState.createdJobs[0]?.useGpu).toBe(false);
|
||
expect(warn).not.toHaveBeenCalledWith(expect.stringContaining("encoder probe timed out"));
|
||
});
|
||
|
||
it("diagnoses advisory encoder probe failures unless quiet", async () => {
|
||
ffmpegEncoderState.error = new Error("encoder probe timed out");
|
||
const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
|
||
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "high",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "force-sdr",
|
||
quiet: false,
|
||
});
|
||
|
||
expect(producerState.createdJobs[0]?.useGpu).toBe(false);
|
||
expect(warn).toHaveBeenCalledWith(expect.stringContaining("encoder probe timed out"));
|
||
});
|
||
|
||
it("resolves browser GPU from CLI flags, Docker mode, and env fallback", () => {
|
||
// Default (no flag, no env): auto — engine probes and chooses.
|
||
expect(resolveBrowserGpuForCli(false, undefined, undefined)).toBe("auto");
|
||
// Env override
|
||
expect(resolveBrowserGpuForCli(false, undefined, "hardware")).toBe("hardware");
|
||
expect(resolveBrowserGpuForCli(false, undefined, "software")).toBe("software");
|
||
expect(resolveBrowserGpuForCli(false, undefined, "auto")).toBe("auto");
|
||
// Explicit CLI flag wins over env
|
||
expect(resolveBrowserGpuForCli(false, true, "software")).toBe("hardware");
|
||
expect(resolveBrowserGpuForCli(false, false, "hardware")).toBe("software");
|
||
// Docker forces software regardless of flags/env
|
||
expect(resolveBrowserGpuForCli(true, undefined, "hardware")).toBe("software");
|
||
expect(resolveBrowserGpuForCli(true, undefined, "auto")).toBe("software");
|
||
});
|
||
|
||
it("forwards parsed --variables payload to createRenderJob", async () => {
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
variables: { title: "Hello", count: 3 },
|
||
});
|
||
|
||
expect(producerState.createdJobs[0]?.variables).toEqual({ title: "Hello", count: 3 });
|
||
});
|
||
|
||
it("forwards format: png-sequence through to createRenderJob", async () => {
|
||
await renderLocal(PROJECT_DIR, "/tmp/frames", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "png-sequence",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
});
|
||
|
||
expect(producerState.createdJobs[0]?.format).toBe("png-sequence");
|
||
});
|
||
|
||
it("forwards format: hls and hlsSegmentSeconds through to createRenderJob", async () => {
|
||
await renderLocal(PROJECT_DIR, "/tmp/stream", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "hls",
|
||
hlsSegmentSeconds: 6,
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
});
|
||
|
||
expect(producerState.createdJobs[0]?.format).toBe("hls");
|
||
expect(producerState.createdJobs[0]?.hlsSegmentSeconds).toBe(6);
|
||
});
|
||
|
||
// HLS refuses the VideoToolbox fallback MP4 takes: fixed-length segments need
|
||
// the software encoder's forced-keyframe lock.
|
||
it("fails an HLS render instead of falling back to GPU H.264", async () => {
|
||
ffmpegEncoderState.encoders = " V....D h264_videotoolbox H.264 (VideoToolbox)\n";
|
||
ffmpegEncoderState.usableGpu = true;
|
||
const stderr = vi.spyOn(console, "error").mockImplementation(() => undefined);
|
||
|
||
await expect(
|
||
renderLocal(PROJECT_DIR, "/tmp/stream", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "hls",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
}),
|
||
).rejects.toMatchObject({ name: "CliRuntimeError" });
|
||
|
||
expect(producerState.createdJobs).toHaveLength(0);
|
||
expect(stderr.mock.calls.flat().join(" ")).toContain("libx264");
|
||
});
|
||
|
||
it("forwards format: gif and gifLoop through to createRenderJob", async () => {
|
||
await renderLocal(PROJECT_DIR, "/tmp/demo.gif", {
|
||
fps: { num: 15, den: 1 },
|
||
quality: "standard",
|
||
format: "gif",
|
||
gifLoop: 3,
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
});
|
||
|
||
expect(producerState.createdJobs[0]?.format).toBe("gif");
|
||
expect(producerState.createdJobs[0]?.gifLoop).toBe(3);
|
||
});
|
||
|
||
it("forwards videoFrameFormat to createRenderJob", async () => {
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
videoFrameFormat: "png",
|
||
});
|
||
|
||
expect(producerState.createdJobs[0]?.videoFrameFormat).toBe("png");
|
||
});
|
||
|
||
it("forwards debug mode to createRenderJob", async () => {
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
debug: true,
|
||
});
|
||
|
||
expect(producerState.createdJobs[0]?.debug).toBe(true);
|
||
});
|
||
|
||
it("defaults to best-effort readiness", async () => {
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
});
|
||
|
||
expect(producerState.createdJobs[0]?.strictness).toBe("best-effort");
|
||
});
|
||
|
||
it("forwards an explicit strict readiness opt-in", async () => {
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
bestEffort: false,
|
||
});
|
||
|
||
expect(producerState.createdJobs[0]?.strictness).toBe("strict");
|
||
});
|
||
|
||
it("omits variables from createRenderJob when not provided", async () => {
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
});
|
||
|
||
expect(producerState.createdJobs[0]?.variables).toBeUndefined();
|
||
});
|
||
|
||
it.each([undefined, "off"] as const)(
|
||
"preserves page motion blur %s in the producer request",
|
||
async (pageMotionBlur) => {
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
pageMotionBlur,
|
||
});
|
||
expect(producerState.createdJobs[0]?.pageMotionBlur).toBe(pageMotionBlur);
|
||
},
|
||
);
|
||
|
||
it("forwards entryFile to createRenderJob when --composition is set", async () => {
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
entryFile: "compositions/intro.html",
|
||
});
|
||
|
||
expect(producerState.createdJobs[0]?.entryFile).toBe("compositions/intro.html");
|
||
});
|
||
|
||
it("omits entryFile from createRenderJob when --composition is not set", async () => {
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
});
|
||
|
||
expect(producerState.createdJobs[0]?.entryFile).toBeUndefined();
|
||
});
|
||
|
||
it("forwards --browser-timeout into resolveConfig as pageNavigationTimeout (ms)", async () => {
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
pageNavigationTimeoutMs: 180_000,
|
||
});
|
||
|
||
expect(producerState.resolveConfigCalls[0]).toMatchObject({
|
||
pageNavigationTimeout: 180_000,
|
||
});
|
||
});
|
||
|
||
it("forwards vp9CpuUsed into resolveConfig when set", async () => {
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.webm", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "webm",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
vp9CpuUsed: 2,
|
||
});
|
||
|
||
expect(producerState.resolveConfigCalls[0]).toMatchObject({
|
||
vp9CpuUsed: 2,
|
||
});
|
||
});
|
||
|
||
it("omits pageNavigationTimeout from resolveConfig when --browser-timeout is not set", async () => {
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
});
|
||
|
||
// Issue #1199: when the flag is omitted, the engine's DEFAULT_CONFIG must
|
||
// own the navigation timeout. Forwarding `undefined` would override
|
||
// `pageNavigationTimeout: 60_000` to `undefined` and re-introduce the
|
||
// bug in a different shape.
|
||
expect(producerState.resolveConfigCalls[0]).not.toHaveProperty("pageNavigationTimeout");
|
||
});
|
||
|
||
it("forwards outputResolution to createRenderJob when --resolution is set", async () => {
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
outputResolution: "landscape-4k",
|
||
});
|
||
|
||
expect(producerState.createdJobs[0]?.outputResolution).toBe("landscape-4k");
|
||
});
|
||
|
||
it("omits outputResolution from createRenderJob by default", async () => {
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "software",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
});
|
||
|
||
expect(producerState.createdJobs[0]?.outputResolution).toBeUndefined();
|
||
});
|
||
|
||
it("requests a root-owned CLI exit after a successful local render", async () => {
|
||
vi.useFakeTimers();
|
||
const { consumeCommandResult } = await import("../utils/commandResult.js");
|
||
consumeCommandResult();
|
||
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "hardware",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
exitAfterComplete: true,
|
||
});
|
||
|
||
vi.advanceTimersByTime(100);
|
||
expect(consumeCommandResult().exitCode).toBe(0);
|
||
});
|
||
|
||
it("still completes the render when the output registry cannot be written", async () => {
|
||
const project = mkdtempSync(join(tmpdir(), "hf-render-unrecorded-"));
|
||
mkdirSync(join(project, ".hyperframes"));
|
||
writeFileSync(join(project, ".hyperframes", "render-outputs.json"), "{");
|
||
const warn = vi.spyOn(console, "warn").mockImplementation(() => undefined);
|
||
try {
|
||
await renderLocal(project, join(project, "out.mp4"), {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard",
|
||
format: "mp4",
|
||
gpu: false,
|
||
browserGpuMode: "hardware",
|
||
hdrMode: "auto",
|
||
quiet: true,
|
||
});
|
||
expect(
|
||
warn.mock.calls.some((call) =>
|
||
String(call[0]).includes("Render output was not registered"),
|
||
),
|
||
).toBe(true);
|
||
} finally {
|
||
warn.mockRestore();
|
||
rmSync(project, { recursive: true, force: true });
|
||
}
|
||
});
|
||
});
|
||
|
||
// Suite renamed with the breaker work: this is no longer an opt-in trial. The
|
||
// bindings come from main's shared top-level `renderModule` import rather than
|
||
// this suite's own beforeAll — same module instance every other suite uses, so
|
||
// module-scope arm/consume state resets through the one `resetTrialState()`.
|
||
describe("renderLocal — DE parallel-router circuit breaker", () => {
|
||
const { renderLocal, __resetDeParallelRouterTrialStateForTests: resetTrialState } = renderModule;
|
||
const savedEnv = new Map<string, string | undefined>();
|
||
|
||
beforeEach(() => {
|
||
producerState.createdJobs = [];
|
||
producerState.executeImpl = async () => undefined;
|
||
configState.cache = null;
|
||
configState.failWrites = 0;
|
||
configState.writeConfigCalls = [];
|
||
trackingState.shouldTrack = true;
|
||
// The "managed by us" flag lives at module scope in render.ts (real CLI
|
||
// processes only ever run one --batch sequence, so it never needs
|
||
// resetting there) — reset explicitly here so tests don't leak arm/
|
||
// consume state into each other via shared module instance + test order.
|
||
resetTrialState();
|
||
savedEnv.clear();
|
||
savedEnv.set("HF_DE_PARALLEL_ROUTER", process.env.HF_DE_PARALLEL_ROUTER);
|
||
savedEnv.set("HYPERFRAMES_FFMPEG_PATH", process.env.HYPERFRAMES_FFMPEG_PATH);
|
||
savedEnv.set("HYPERFRAMES_FFPROBE_PATH", process.env.HYPERFRAMES_FFPROBE_PATH);
|
||
savedEnv.set("PRODUCER_HEADLESS_SHELL_PATH", process.env.PRODUCER_HEADLESS_SHELL_PATH);
|
||
delete process.env.HF_DE_PARALLEL_ROUTER;
|
||
delete process.env.HYPERFRAMES_FFMPEG_PATH;
|
||
delete process.env.HYPERFRAMES_FFPROBE_PATH;
|
||
delete process.env.PRODUCER_HEADLESS_SHELL_PATH;
|
||
});
|
||
|
||
afterEach(() => {
|
||
for (const [key, value] of savedEnv) {
|
||
if (value === undefined) delete process.env[key];
|
||
else process.env[key] = value;
|
||
}
|
||
vi.clearAllMocks();
|
||
});
|
||
|
||
const strike = (over: Record<string, unknown> = {}) => ({
|
||
reason: "psnr",
|
||
at: "2026-10-01T00:00:00.000Z",
|
||
version: VERSION,
|
||
atRender: 0,
|
||
...over,
|
||
});
|
||
/** One earlier revert on record: the next one trips the breaker. */
|
||
const afterOneStrike = () => ({
|
||
telemetryEnabled: true,
|
||
deParallelRouterTrialFired: false,
|
||
telemetryNoticeShown: true,
|
||
deParallelRouterBreaker: { strike: strike() },
|
||
deParallelRouterTrialRenderCount: 1,
|
||
});
|
||
const tripped = (over: Record<string, unknown> = {}) => ({
|
||
telemetryEnabled: true,
|
||
deParallelRouterTrialFired: true,
|
||
telemetryNoticeShown: true,
|
||
deParallelRouterBreaker: { trip: { ...strike(), cleanRenders: 0, ...over } },
|
||
});
|
||
const revertedRender = async (job: { perfSummary?: unknown }) => {
|
||
job.perfSummary = {
|
||
resolution: { width: 100, height: 100 },
|
||
drawElement: { parallelRouter: "reverted" },
|
||
};
|
||
};
|
||
|
||
const baseOptions = {
|
||
fps: { num: 30, den: 1 },
|
||
quality: "standard" as const,
|
||
format: "mp4" as const,
|
||
gpu: false,
|
||
browserGpuMode: "software" as const,
|
||
hdrMode: "auto" as const,
|
||
quiet: true,
|
||
// Breaker management is OPT-IN (review): only the CLI's own sequential
|
||
// call sites set it. These tests simulate those call sites.
|
||
manageDeParallelRouterBreaker: true,
|
||
};
|
||
|
||
// The canary that used to gate this is gone (registry entry + guard removed
|
||
// together). The router is now a shipped default for every install, so the
|
||
// guarantee worth pinning is the inverse of the old one: an ordinary install
|
||
// must come out of the breaker with the var UNSET, so the producer's
|
||
// default-ON applies. Writing "false" here would silently disarm the fleet —
|
||
// that is exactly what gating at 5% did.
|
||
it("leaves the var unset for an ordinary install so the producer default applies", async () => {
|
||
configState.disk = {
|
||
telemetryEnabled: true,
|
||
deParallelRouterTrialFired: false,
|
||
telemetryNoticeShown: true,
|
||
};
|
||
delete process.env.HF_DE_PARALLEL_ROUTER;
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
|
||
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
|
||
});
|
||
|
||
// An explicit user choice outranks enrolment in both directions — the
|
||
// documented escalation path for anyone who wants the router regardless.
|
||
it("never overrides an explicit user value", async () => {
|
||
configState.disk = {
|
||
telemetryEnabled: true,
|
||
deParallelRouterTrialFired: false,
|
||
telemetryNoticeShown: true,
|
||
};
|
||
process.env.HF_DE_PARALLEL_ROUTER = "true";
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
|
||
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("true");
|
||
});
|
||
|
||
it("leaves the env var untouched on a fresh install — the router is default-ON", async () => {
|
||
// Under the old opt-in trial this armed HF_DE_PARALLEL_ROUTER="true".
|
||
// The router now ships on, so the breaker's job is to stay out of the
|
||
// way until something actually fails.
|
||
configState.disk = {
|
||
telemetryEnabled: true,
|
||
deParallelRouterTrialFired: false,
|
||
telemetryNoticeShown: true,
|
||
};
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
|
||
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
|
||
});
|
||
|
||
it("does not override an env var the user already set themselves", async () => {
|
||
configState.disk = {
|
||
telemetryEnabled: true,
|
||
deParallelRouterTrialFired: false,
|
||
telemetryNoticeShown: true,
|
||
};
|
||
process.env.HF_DE_PARALLEL_ROUTER = "false";
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
|
||
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
|
||
});
|
||
|
||
it("writes an explicit false once the breaker has tripped for this install", async () => {
|
||
// THE regression this rework exists for: the old code disabled the
|
||
// router by DELETING the var. With a default-ON router, absent means ON,
|
||
// so deleting would silently re-enable it on the very host that just
|
||
// failed. Only an explicit "false" is a real off-switch.
|
||
configState.disk = tripped();
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
|
||
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
|
||
});
|
||
|
||
for (const emptyish of ["", " "]) {
|
||
it(`treats a set-but-empty env var (${JSON.stringify(emptyish)}) as default, not a user choice`, async () => {
|
||
// Both parsers read empty/whitespace as "unset → default ON", so the
|
||
// producer routes. If ownership instead treated any defined value as a
|
||
// user choice, the breaker would no-op and this install would keep
|
||
// retrying a failing router forever — losing the first-fallback
|
||
// protection that is the point of the breaker.
|
||
configState.disk = afterOneStrike();
|
||
process.env.HF_DE_PARALLEL_ROUTER = emptyish;
|
||
producerState.executeImpl = async (job) => {
|
||
job.perfSummary = {
|
||
resolution: { width: 100, height: 100 },
|
||
drawElement: { parallelRouter: "reverted" },
|
||
};
|
||
};
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
|
||
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
|
||
expect(configState.writeConfigCalls).toContainEqual(
|
||
expect.objectContaining({ deParallelRouterTrialFired: true }),
|
||
);
|
||
});
|
||
}
|
||
|
||
it("does not override an explicit user opt-in even after a fallback", async () => {
|
||
// "Explicit user choice wins in both directions" — the opt-in half.
|
||
configState.disk = {
|
||
telemetryEnabled: true,
|
||
deParallelRouterTrialFired: false,
|
||
telemetryNoticeShown: true,
|
||
};
|
||
process.env.HF_DE_PARALLEL_ROUTER = "true";
|
||
producerState.executeImpl = async (job) => {
|
||
job.perfSummary = {
|
||
resolution: { width: 100, height: 100 },
|
||
drawElement: { parallelRouter: "reverted" },
|
||
};
|
||
};
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
|
||
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("true");
|
||
});
|
||
|
||
it("keeps the router on for a telemetry opt-out — analytics choice must not cost performance", async () => {
|
||
// The old trial refused to arm without recordable telemetry (no point
|
||
// running an experiment you can't measure). Now that the router is a
|
||
// shipped default, gating it on telemetry would punish a privacy choice
|
||
// with a slower renderer.
|
||
configState.disk = {
|
||
telemetryEnabled: false,
|
||
deParallelRouterTrialFired: false,
|
||
telemetryNoticeShown: true,
|
||
};
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
|
||
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
|
||
});
|
||
|
||
it("does NOT persist the trial as fired on a clean 'routed' success — keeps trying on future renders", async () => {
|
||
configState.disk = {
|
||
telemetryEnabled: true,
|
||
deParallelRouterTrialFired: false,
|
||
telemetryNoticeShown: true,
|
||
};
|
||
producerState.executeImpl = async (job) => {
|
||
job.perfSummary = {
|
||
resolution: { width: 100, height: 100 },
|
||
drawElement: { parallelRouter: "routed" },
|
||
};
|
||
};
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
|
||
// A write DOES happen — the render-count backstop is tracked on every
|
||
// engaged render — but it must not flip deParallelRouterTrialFired.
|
||
expect(configState.writeConfigCalls).toContainEqual(
|
||
expect.objectContaining({
|
||
deParallelRouterTrialFired: false,
|
||
deParallelRouterTrialRenderCount: 1,
|
||
}),
|
||
);
|
||
});
|
||
|
||
it("persists the trial as fired when the router's own safety net actually reverted", async () => {
|
||
configState.disk = afterOneStrike();
|
||
producerState.executeImpl = async (job) => {
|
||
job.perfSummary = {
|
||
resolution: { width: 100, height: 100 },
|
||
drawElement: {
|
||
parallelRouter: "reverted",
|
||
fallbackReason: "psnr",
|
||
fallbackFrameIndex: 812,
|
||
fallbackFailedDb: 24.5,
|
||
fallbackThresholdDb: 32,
|
||
},
|
||
};
|
||
};
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
|
||
expect(configState.writeConfigCalls).toContainEqual(
|
||
expect.objectContaining({
|
||
deParallelRouterTrialFired: true,
|
||
deParallelRouterBreaker: {
|
||
trip: expect.objectContaining({
|
||
reason: "psnr",
|
||
frameIndex: 812,
|
||
failedDb: 24.5,
|
||
thresholdDb: 32,
|
||
version: VERSION,
|
||
cleanRenders: 0,
|
||
}),
|
||
},
|
||
}),
|
||
);
|
||
});
|
||
|
||
it("does not persist the trial as fired or increment the render count when the router never became eligible for this render", async () => {
|
||
configState.disk = {
|
||
telemetryEnabled: true,
|
||
deParallelRouterTrialFired: false,
|
||
telemetryNoticeShown: true,
|
||
};
|
||
producerState.executeImpl = async (job) => {
|
||
// aggregateDrawElement (perfSummary.ts) ALWAYS defaults parallelRouter
|
||
// to the string "none" for every render, whether or not drawElement
|
||
// ever ran — never undefined. This fixture must match that shape, not
|
||
// an unrealistic empty object, or the test doesn't actually exercise
|
||
// the "none"-vs-undefined distinction (review finding).
|
||
job.perfSummary = {
|
||
resolution: { width: 100, height: 100 },
|
||
drawElement: { parallelRouter: "none" },
|
||
};
|
||
};
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
|
||
expect(configState.writeConfigCalls).toHaveLength(0);
|
||
});
|
||
|
||
it("does NOT persist the trial as fired when a render merely 'routed' crashes for an unrelated reason (e.g. cancellation) — not a router failure", async () => {
|
||
configState.disk = {
|
||
telemetryEnabled: true,
|
||
deParallelRouterTrialFired: false,
|
||
telemetryNoticeShown: true,
|
||
};
|
||
producerState.executeImpl = async (job) => {
|
||
job.errorDetails = { observability: { capture: { deParallelRouter: "routed" } } };
|
||
throw new Error("render cancelled");
|
||
};
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", { ...baseOptions, throwOnError: true }).catch(
|
||
() => {},
|
||
);
|
||
// Still counts toward the render-count backstop (the router DID engage),
|
||
// but must not flip deParallelRouterTrialFired — the crash wasn't the
|
||
// router's own safety net firing.
|
||
expect(configState.writeConfigCalls).toContainEqual(
|
||
expect.objectContaining({
|
||
deParallelRouterTrialFired: false,
|
||
deParallelRouterTrialRenderCount: 1,
|
||
}),
|
||
);
|
||
});
|
||
|
||
it("persists the trial as fired from the failure path when the router's safety net reverted but the retry still failed", async () => {
|
||
configState.disk = afterOneStrike();
|
||
producerState.executeImpl = async (job) => {
|
||
job.errorDetails = { observability: { capture: { deParallelRouter: "reverted" } } };
|
||
throw new Error("worker crashed even after fallback");
|
||
};
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", { ...baseOptions, throwOnError: true }).catch(
|
||
() => {},
|
||
);
|
||
expect(configState.writeConfigCalls).toContainEqual(
|
||
expect.objectContaining({ deParallelRouterTrialFired: true }),
|
||
);
|
||
});
|
||
|
||
it("trips on the second revert of a --batch, not the first", async () => {
|
||
configState.disk = {
|
||
telemetryEnabled: true,
|
||
deParallelRouterTrialFired: false,
|
||
telemetryNoticeShown: true,
|
||
};
|
||
producerState.executeImpl = revertedRender;
|
||
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
|
||
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
|
||
expect(configState.disk.deParallelRouterTrialFired).toBe(false);
|
||
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
|
||
expect(configState.disk.deParallelRouterTrialFired).toBe(true);
|
||
// Explicit "false", not deleted: with a default-ON router, unsetting the
|
||
// var would re-enable it on the host that just reverted.
|
||
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
|
||
});
|
||
|
||
it("keeps the router on after a single revert and remembers the strike", async () => {
|
||
configState.disk = { telemetryEnabled: true, telemetryNoticeShown: true };
|
||
producerState.executeImpl = revertedRender;
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
|
||
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
|
||
expect(configState.disk.deParallelRouterTrialFired).toBeFalsy();
|
||
expect(configState.disk.deParallelRouterBreaker).toEqual({
|
||
strike: expect.objectContaining({ reason: "reverted", atRender: 1, version: VERSION }),
|
||
});
|
||
});
|
||
|
||
it("forgets a strike that is 20 or more router renders old", async () => {
|
||
configState.disk = { ...afterOneStrike(), deParallelRouterTrialRenderCount: 20 };
|
||
producerState.executeImpl = revertedRender;
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
|
||
expect(configState.disk.deParallelRouterTrialFired).toBeFalsy();
|
||
expect(configState.disk.deParallelRouterBreaker).toEqual({
|
||
strike: expect.objectContaining({ atRender: 21 }),
|
||
});
|
||
});
|
||
|
||
it("brings the router back for a new CLI version", async () => {
|
||
configState.disk = tripped({ version: "0.0.1-older" });
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
|
||
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
|
||
expect(configState.disk.deParallelRouterTrialFired).toBeFalsy();
|
||
expect(configState.disk.deParallelRouterBreaker).toBeUndefined();
|
||
});
|
||
|
||
it("brings the router back when the latch has no record (set by an older CLI)", async () => {
|
||
configState.disk = {
|
||
telemetryEnabled: true,
|
||
deParallelRouterTrialFired: true,
|
||
telemetryNoticeShown: true,
|
||
};
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
|
||
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
|
||
expect(configState.disk.deParallelRouterTrialFired).toBeFalsy();
|
||
});
|
||
|
||
it("brings the router back after 20 clean renders, not before", async () => {
|
||
configState.disk = tripped({ cleanRenders: 17 });
|
||
for (const expected of [18, 19]) {
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
|
||
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
|
||
expect(configState.disk.deParallelRouterBreaker).toEqual({
|
||
trip: expect.objectContaining({ cleanRenders: expected }),
|
||
});
|
||
}
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
|
||
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
|
||
expect(configState.disk.deParallelRouterTrialFired).toBeFalsy();
|
||
expect(configState.disk.deParallelRouterBreaker).toBeUndefined();
|
||
});
|
||
|
||
it("does not count a failed render toward bringing the router back", async () => {
|
||
configState.disk = tripped({ cleanRenders: 5 });
|
||
producerState.executeImpl = async () => {
|
||
throw new Error("render failed");
|
||
};
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", { ...baseOptions, throwOnError: true }).catch(
|
||
() => {},
|
||
);
|
||
expect(configState.disk.deParallelRouterBreaker).toEqual({
|
||
trip: expect.objectContaining({ cleanRenders: 5 }),
|
||
});
|
||
});
|
||
|
||
it("does not arm the trial for programmatic callers that never opted in (opt-in polarity — also covers --batch-concurrency N>=2, which leaves it unset)", async () => {
|
||
// The trial's process-wide env var and module-level flags are only safe
|
||
// under sequential invocation, so manageDeParallelRouterBreaker is OPT-IN
|
||
// (review): a programmatic renderLocal consumer that doesn't know about
|
||
// the trial must get no trial. The CLI's concurrent-batch path relies on
|
||
// the same default by leaving the option unset.
|
||
configState.disk = {
|
||
telemetryEnabled: true,
|
||
deParallelRouterTrialFired: false,
|
||
telemetryNoticeShown: true,
|
||
};
|
||
const { manageDeParallelRouterBreaker: _omitted, ...programmaticOptions } = baseOptions;
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", programmaticOptions);
|
||
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
|
||
expect(configState.writeConfigCalls).toHaveLength(0);
|
||
});
|
||
|
||
it("does not override an env var the user set between two renders in the same process", async () => {
|
||
configState.disk = {
|
||
telemetryEnabled: true,
|
||
deParallelRouterTrialFired: false,
|
||
telemetryNoticeShown: true,
|
||
};
|
||
producerState.executeImpl = async (job) => {
|
||
job.perfSummary = {
|
||
resolution: { width: 100, height: 100 },
|
||
drawElement: { parallelRouter: "routed" },
|
||
};
|
||
};
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
|
||
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
|
||
|
||
// A real interactive user can't do this mid-batch, but a wrapper script
|
||
// invoking the CLI programmatically in the same process could — the
|
||
// explicit override must still win on the next call.
|
||
process.env.HF_DE_PARALLEL_ROUTER = "false";
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
|
||
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
|
||
});
|
||
|
||
it("never trips on healthy renders, however many — the old 25-render cap is gone", async () => {
|
||
// The cap was sampling logic for an opt-in experiment. Under a shipped
|
||
// default it would switch the feature off behind the user's back after
|
||
// 25 good renders.
|
||
configState.disk = {
|
||
telemetryEnabled: true,
|
||
deParallelRouterTrialFired: false,
|
||
telemetryNoticeShown: true,
|
||
};
|
||
producerState.executeImpl = async (job) => {
|
||
job.perfSummary = {
|
||
resolution: { width: 100, height: 100 },
|
||
drawElement: { parallelRouter: "routed" },
|
||
};
|
||
};
|
||
|
||
for (let i = 0; i < 30; i++) {
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
|
||
}
|
||
|
||
expect(process.env.HF_DE_PARALLEL_ROUTER).toBeUndefined();
|
||
expect(
|
||
configState.writeConfigCalls.some((call) => call.deParallelRouterTrialFired === true),
|
||
).toBe(false);
|
||
});
|
||
|
||
// The config write landing is NOT enough: config.json is the copy a stale
|
||
// writer or a re-mint can erase, so a run that mirrored nothing has left the
|
||
// safety fact on the erasable store only. writeConfig() collapsed
|
||
// {ok:true, mirrored:false} to success and the loop stopped there.
|
||
it("retries when the install-state mirror fails even though config.json landed", async () => {
|
||
configState.disk = afterOneStrike();
|
||
configState.failMirrors = 1; // first attempt mirrors nothing
|
||
producerState.executeImpl = async (job) => {
|
||
job.perfSummary = {
|
||
resolution: { width: 100, height: 100 },
|
||
drawElement: { parallelRouter: "reverted" },
|
||
};
|
||
};
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
|
||
|
||
expect(configState.disk.deParallelRouterTrialFired).toBe(true);
|
||
// Two writes: the one whose mirror failed, then the retry that mirrored.
|
||
const firedWrites = configState.writeConfigCalls.filter(
|
||
(c) => c.deParallelRouterTrialFired === true,
|
||
);
|
||
expect(firedWrites.length).toBeGreaterThanOrEqual(2);
|
||
});
|
||
|
||
it("re-asserts the fired flag when the write is lost (concurrent clobber / transient failure), without re-counting the render", async () => {
|
||
configState.disk = afterOneStrike();
|
||
configState.failWrites = 1; // the consume's main write is silently dropped
|
||
producerState.executeImpl = async (job) => {
|
||
job.perfSummary = {
|
||
resolution: { width: 100, height: 100 },
|
||
drawElement: { parallelRouter: "reverted" },
|
||
};
|
||
};
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
|
||
// The fired flag was verified and re-asserted (idempotent)...
|
||
expect(configState.disk.deParallelRouterTrialFired).toBe(true);
|
||
// ...but the render counter is deliberately NOT re-applied — a lost
|
||
// increment under a race is benign, a re-applied one double-counts the
|
||
// render and trips the exposure cap early (review finding).
|
||
expect(configState.disk.deParallelRouterTrialRenderCount).toBe(1);
|
||
});
|
||
|
||
it("blocks re-arming for the rest of the process when the fired flag can never persist (unwritable config)", async () => {
|
||
configState.disk = afterOneStrike();
|
||
configState.failWrites = Number.MAX_SAFE_INTEGER; // ~/.hyperframes is unwritable
|
||
producerState.executeImpl = async (job) => {
|
||
job.perfSummary = {
|
||
resolution: { width: 100, height: 100 },
|
||
drawElement: { parallelRouter: "reverted" },
|
||
};
|
||
};
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
|
||
// Nothing could persist...
|
||
expect(configState.disk.deParallelRouterTrialFired).toBe(false);
|
||
// ...but the in-process latch still blocks the next render from
|
||
// re-running the path that just failed (review finding) — and now does
|
||
// it by writing an explicit "false", since absent means ON.
|
||
producerState.executeImpl = async () => undefined;
|
||
await renderLocal(PROJECT_DIR, "/tmp/out.mp4", baseOptions);
|
||
expect(process.env.HF_DE_PARALLEL_ROUTER).toBe("false");
|
||
});
|
||
});
|
||
|
||
describe("checkRenderResolutionPreflight", () => {
|
||
const { checkRenderResolutionPreflight } = renderModule;
|
||
|
||
// Dims must be read the same way the producer's compiler reads them:
|
||
// `data-width` / `data-height` on the `[data-composition-id]` root.
|
||
const comp = (w: number, h: number) =>
|
||
`<html><body><div data-composition-id="root" data-width="${w}" data-height="${h}"></div></body></html>`;
|
||
const portraitHtml = comp(1080, 1920);
|
||
const landscapeHtml = comp(1920, 1080);
|
||
const noModes = { alphaRequested: false, hdrRequested: false } as const;
|
||
|
||
it("returns undefined when no outputResolution is requested", async () => {
|
||
expect(await checkRenderResolutionPreflight(portraitHtml, undefined, noModes)).toBeUndefined();
|
||
});
|
||
|
||
it("returns undefined when the preset matches the composition orientation", async () => {
|
||
expect(await checkRenderResolutionPreflight(portraitHtml, "portrait", noModes)).toBeUndefined();
|
||
});
|
||
|
||
it("returns a suggestion + aspect-mismatch kind when a landscape preset is used on a portrait composition", async () => {
|
||
const result = await checkRenderResolutionPreflight(portraitHtml, "landscape", noModes);
|
||
expect(result?.message).toContain("--resolution portrait");
|
||
expect(result?.kind).toBe("aspect-mismatch");
|
||
});
|
||
|
||
it("suggests landscape for a landscape composition rendered with a portrait preset", async () => {
|
||
const result = await checkRenderResolutionPreflight(landscapeHtml, "portrait", noModes);
|
||
expect(result?.message).toContain("--resolution landscape");
|
||
});
|
||
|
||
it("preserves the 4K tier when suggesting a matching preset (square comp + landscape-4k → square-4k)", async () => {
|
||
// Tier-aware suggestion is the load-bearing new behavior; square-4k is the
|
||
// preset that only surfaces via a same-tier swap, so guard it explicitly.
|
||
const result = await checkRenderResolutionPreflight(comp(2160, 2160), "landscape-4k", noModes);
|
||
expect(result?.message).toContain("--resolution square-4k");
|
||
});
|
||
|
||
it("does not false-abort a landscape registry-block composition (data-width/height, no data-resolution)", async () => {
|
||
// Regression guard: registry blocks carry data-width/height and no
|
||
// data-resolution — a preset-snapping heuristic would misread this as
|
||
// portrait and wrongly reject the correct --resolution landscape.
|
||
expect(
|
||
await checkRenderResolutionPreflight(landscapeHtml, "landscape", noModes),
|
||
).toBeUndefined();
|
||
});
|
||
|
||
it("allows alpha output combined with an integer outputResolution scale", async () => {
|
||
const result = await checkRenderResolutionPreflight(landscapeHtml, "landscape-4k", {
|
||
alphaRequested: true,
|
||
hdrRequested: false,
|
||
});
|
||
expect(result).toBeUndefined();
|
||
});
|
||
|
||
// The remaining kinds share the same rejection sink (→ one emit each);
|
||
// guard their classification so the telemetry dimension stays accurate.
|
||
it("classifies an HDR + outputResolution combination as hdr-incompatible", async () => {
|
||
const result = await checkRenderResolutionPreflight(landscapeHtml, "landscape", {
|
||
alphaRequested: false,
|
||
hdrRequested: true,
|
||
});
|
||
expect(result?.kind).toBe("hdr-incompatible");
|
||
});
|
||
|
||
it("passes a preset smaller than the composition", async () => {
|
||
// 3840×2160 comp + landscape (1920×1080): same 16:9 aspect, rendered at 0.5× DPR.
|
||
const result = await checkRenderResolutionPreflight(comp(3840, 2160), "landscape", noModes);
|
||
expect(result).toBeUndefined();
|
||
});
|
||
|
||
it("classifies a non-integer upscale as non-integer-scale", async () => {
|
||
// 1280×720 comp + landscape (1920×1080): same 16:9 aspect, 1.5× scale.
|
||
const result = await checkRenderResolutionPreflight(comp(1280, 720), "landscape", noModes);
|
||
expect(result?.kind).toBe("non-integer-scale");
|
||
});
|
||
|
||
it("returns undefined when composition dimensions can't be determined (defers to the pipeline)", async () => {
|
||
// No [data-composition-id] root / no data-width/height → defer, never guess.
|
||
expect(await checkRenderResolutionPreflight("", "landscape", noModes)).toBeUndefined();
|
||
expect(
|
||
await checkRenderResolutionPreflight("<html><body></body></html>", "landscape", noModes),
|
||
).toBeUndefined();
|
||
});
|
||
|
||
// Aspect-agnostic aliases (`--resolution 1080p` / `hd` / `4k` / `uhd`) name a
|
||
// resolution tier without pinning an orientation. When the flag is
|
||
// aspect-agnostic the pre-flight must NOT block on an aspect-ratio mismatch —
|
||
// the compile stage adapts the preset to the composition's orientation
|
||
// downstream (see `outputResolutionAspectAgnostic` on RenderConfig).
|
||
// Field signal ts=1784176662 (darwin/arm64, CLI 0.7.59):
|
||
// "--resolution 1080p rejects a 1080x1920 portrait comp"
|
||
describe("aspect-agnostic (--resolution 1080p / hd / 4k / uhd)", () => {
|
||
const agnostic = { ...noModes, aspectAgnostic: true } as const;
|
||
|
||
it("clears a landscape preset on a portrait composition (the field-signal scenario)", async () => {
|
||
// The bug: --resolution 1080p normalized to `landscape` (1920×1080),
|
||
// then errored on a 1080×1920 portrait comp with "Output resolution
|
||
// incompatible." With aspectAgnostic=true the pre-flight steps aside
|
||
// and the compile stage re-maps landscape → portrait.
|
||
expect(
|
||
await checkRenderResolutionPreflight(portraitHtml, "landscape", agnostic),
|
||
).toBeUndefined();
|
||
});
|
||
|
||
it("clears a landscape-4k preset on a portrait composition (4K tier)", async () => {
|
||
// `--resolution 4k` → normalized `landscape-4k`. Portrait comp is fine
|
||
// when aspect-agnostic.
|
||
expect(
|
||
await checkRenderResolutionPreflight(portraitHtml, "landscape-4k", agnostic),
|
||
).toBeUndefined();
|
||
});
|
||
|
||
it("clears a landscape preset on a square composition", async () => {
|
||
// aspect > 1 → landscape, aspect = 1 → square. Both self-heal.
|
||
expect(
|
||
await checkRenderResolutionPreflight(comp(1080, 1080), "landscape", agnostic),
|
||
).toBeUndefined();
|
||
});
|
||
|
||
it("allows alpha + aspect-agnostic after adapting the orientation", async () => {
|
||
const result = await checkRenderResolutionPreflight(portraitHtml, "landscape", {
|
||
aspectAgnostic: true,
|
||
alphaRequested: true,
|
||
hdrRequested: false,
|
||
});
|
||
expect(result).toBeUndefined();
|
||
});
|
||
|
||
it("still flags HDR + aspect-agnostic", async () => {
|
||
const result = await checkRenderResolutionPreflight(landscapeHtml, "landscape", {
|
||
aspectAgnostic: true,
|
||
alphaRequested: false,
|
||
hdrRequested: true,
|
||
});
|
||
expect(result?.kind).toBe("hdr-incompatible");
|
||
});
|
||
|
||
it("passes `--resolution 1080p` on a 4K composition (a smaller, same-orientation preset)", async () => {
|
||
const result = await checkRenderResolutionPreflight(comp(3840, 2160), "landscape", agnostic);
|
||
expect(result).toBeUndefined();
|
||
});
|
||
|
||
it("never adapts `--resolution 4k` to another tier: a 1922×1080 composition is refused, not rendered at 480p", async () => {
|
||
const result = await checkRenderResolutionPreflight(
|
||
comp(1922, 1080),
|
||
"landscape-4k",
|
||
agnostic,
|
||
);
|
||
expect(result?.kind).toBeDefined();
|
||
});
|
||
|
||
it("does NOT auto-clear when the flag was explicit (orientation-locked preset stays strict)", async () => {
|
||
// The negative case: `--resolution landscape` on a portrait comp — the
|
||
// user explicitly asked for landscape orientation, and the mismatch is
|
||
// a genuine mistake. Pre-flight must still block with the actionable
|
||
// "did you mean --resolution portrait?" suggestion.
|
||
const result = await checkRenderResolutionPreflight(portraitHtml, "landscape", noModes);
|
||
expect(result?.kind).toBe("aspect-mismatch");
|
||
expect(result?.message).toContain("--resolution portrait");
|
||
});
|
||
|
||
// Rames Δ2 on PR #2529: the earlier "downgrade aspect-mismatch to
|
||
// undefined" preflight cleared *un-remapped* mismatches, so two input
|
||
// classes below regressed from an early actionable error to a late throw
|
||
// deep in `resolveDeviceScaleFactor` (browser + ffmpeg already up).
|
||
// The fix computes the *effective* preset via `suggestMatchingPreset`
|
||
// (mirroring the compile stage) and re-checks against that, so only
|
||
// genuinely-fixable mismatches clear early.
|
||
|
||
it("blocks IG 4:5 (non-preset aspect) early with an aspect-aware message", async () => {
|
||
// 1080×1350 is a 4:5 portrait — no canonical preset shares that aspect,
|
||
// so `suggestMatchingPreset` returns undefined and `adaptAspectAgnosticResolution`
|
||
// keeps the original preset. Before the fix, aspect-agnostic downgraded
|
||
// the mismatch here to undefined; now the preflight surfaces it early.
|
||
const result = await checkRenderResolutionPreflight(comp(1080, 1350), "landscape", agnostic);
|
||
expect(result?.kind).toBe("aspect-mismatch");
|
||
// No sibling preset to suggest → message falls back to the "pick a preset
|
||
// whose orientation matches" hint (see `buildAspectMismatch` in
|
||
// `@hyperframes/parsers/outputResolutionCompatibility`).
|
||
expect(result?.message).toMatch(/preset whose orientation matches|omit --resolution/i);
|
||
});
|
||
|
||
it("passes a portrait-4K comp + `1080p` once remapped to portrait (a smaller preset)", async () => {
|
||
// 2160×3840 + `--resolution 1080p` remaps `landscape` → `portrait` (1080×1920), rendered at 0.5× DPR.
|
||
const result = await checkRenderResolutionPreflight(comp(2160, 3840), "landscape", agnostic);
|
||
expect(result).toBeUndefined();
|
||
});
|
||
|
||
it("blocks a portrait 720p comp + `1080p` non-integer upscale early (orientation-flip masks the fractional DPR)", async () => {
|
||
// 720×1280 (portrait 720p) + `--resolution 1080p` — remap `landscape`
|
||
// → `portrait` (1080×1920). widthRatio = 1080 / 720 = 1.5, which
|
||
// `resolveDeviceScaleFactor` rejects. Surfacing it in preflight beats
|
||
// failing after Chrome + ffmpeg spin up. Same class as Miga's
|
||
// important note on PR #2529.
|
||
const result = await checkRenderResolutionPreflight(comp(720, 1280), "landscape", agnostic);
|
||
expect(result?.kind).toBe("non-integer-scale");
|
||
});
|
||
});
|
||
});
|
||
|
||
describe("render fps arg definition", () => {
|
||
it("declares no citty default for --fps (so data-fps resolution can run)", async () => {
|
||
// Regression guard: a `default: "30"` here makes citty set args.fps="30"
|
||
// on omission, which short-circuits resolveDefaultFpsArg (explicitFps is
|
||
// never null) and silently reverts the command to always-30 — the exact
|
||
// no-op caught in review. The "30" fallback must live at the
|
||
// parseFps(fpsArg ?? "30") call, not on the arg.
|
||
const cmd = (await import("./render.js")).default;
|
||
// citty types `args` as Resolvable (it could be a promise/factory); in
|
||
// practice it's the literal object, so read it through a plain record.
|
||
const args = cmd.args as unknown as Record<string, { default?: unknown } | undefined>;
|
||
const fpsArg = args.fps;
|
||
expect(fpsArg).toBeDefined();
|
||
expect(fpsArg?.default).toBeUndefined();
|
||
});
|
||
});
|
||
|
||
describe("render command explicit composition", () => {
|
||
it("cancels before rendering when the wrapper exits during browser preparation", async () => {
|
||
const projectDir = mkdtempSync(join(tmpdir(), "hf-render-prep-cancel-"));
|
||
writeFileSync(
|
||
join(projectDir, "index.html"),
|
||
'<!doctype html><html><body><div data-composition-id="main" data-width="1920" data-height="1080" data-no-timeline></div></body></html>',
|
||
);
|
||
const wrapper = spawn(process.execPath, ["--eval", "setInterval(() => undefined, 1000)"], {
|
||
stdio: "ignore",
|
||
});
|
||
const jobsBefore = producerState.createdJobs.length;
|
||
const stderr = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
|
||
let releasePreparation!: () => void;
|
||
const preparationBlocked = new Promise<void>((resolve) => {
|
||
releasePreparation = resolve;
|
||
});
|
||
let markWrapperExited!: () => void;
|
||
const wrapperExited = new Promise<void>((resolve) => {
|
||
markWrapperExited = resolve;
|
||
});
|
||
orphanCleanupState.parentPid = (pid) => (pid === process.pid ? wrapper.pid! : null);
|
||
orphanCleanupState.identity = (pid) => (pid === wrapper.pid ? "wrapper-birth-token" : null);
|
||
browserManagerState.onEnsure = async (signal) => {
|
||
const exited = new Promise<void>((resolve) => wrapper.once("exit", () => resolve()));
|
||
wrapper.kill("SIGTERM");
|
||
await exited;
|
||
markWrapperExited();
|
||
await new Promise<void>((resolve, reject) => {
|
||
const onAbort = () => reject(signal?.reason);
|
||
signal?.addEventListener("abort", onAbort, { once: true });
|
||
if (signal?.aborted) onAbort();
|
||
void preparationBlocked.then(() => {
|
||
signal?.removeEventListener("abort", onAbort);
|
||
resolve();
|
||
});
|
||
});
|
||
};
|
||
|
||
try {
|
||
const command = renderModule.default.run?.({
|
||
args: {
|
||
dir: projectDir,
|
||
output: join(projectDir, "out.mp4"),
|
||
quiet: true,
|
||
quality: "standard",
|
||
format: "mp4",
|
||
},
|
||
} as never);
|
||
await expect(
|
||
Promise.race([
|
||
command,
|
||
wrapperExited.then(
|
||
() =>
|
||
new Promise<never>((_resolve, reject) =>
|
||
setTimeout(
|
||
() => reject(new Error("Setup cancellation timed out")),
|
||
process.platform === "linux" ? 1_000 : 3_000,
|
||
),
|
||
),
|
||
),
|
||
]),
|
||
).rejects.toThrow("render_cancelled_parent_exited");
|
||
expect(producerState.createdJobs).toHaveLength(jobsBefore);
|
||
expect(
|
||
stderr.mock.calls.filter(([line]) =>
|
||
String(line).includes("Render cancelled: render_cancelled_parent_exited"),
|
||
),
|
||
).toEqual([["Render cancelled: render_cancelled_parent_exited\n"]]);
|
||
} finally {
|
||
releasePreparation();
|
||
const { consumeCommandResult } = await import("../utils/commandResult.js");
|
||
consumeCommandResult();
|
||
browserManagerState.onEnsure = undefined;
|
||
orphanCleanupState.parentPid = () => null;
|
||
orphanCleanupState.identity = () => null;
|
||
stderr.mockRestore();
|
||
wrapper.kill("SIGKILL");
|
||
rmSync(projectDir, { recursive: true, force: true });
|
||
}
|
||
});
|
||
|
||
it("renders an explicit composition from a project with no index.html", async () => {
|
||
const projectDir = mkdtempSync(join(tmpdir(), "hf-render-explicit-"));
|
||
const outputPath = join(projectDir, "out.mp4");
|
||
writeFileSync(
|
||
join(projectDir, "standalone.html"),
|
||
`<html><body>
|
||
<div data-composition-id="standalone" data-width="1920" data-height="1080" data-duration="1"></div>
|
||
<script>window.__timelines = { standalone: gsap.timeline({ paused: true }) };</script>
|
||
</body></html>`,
|
||
);
|
||
vi.useFakeTimers();
|
||
|
||
try {
|
||
const command = (await import("./render.js")).default;
|
||
await command.run?.({
|
||
args: {
|
||
dir: projectDir,
|
||
composition: "standalone.html",
|
||
output: outputPath,
|
||
quiet: true,
|
||
quality: "standard",
|
||
format: "mp4",
|
||
},
|
||
} as never);
|
||
|
||
expect(producerState.createdJobs.at(-1)).toMatchObject({
|
||
entryFile: "standalone.html",
|
||
});
|
||
} finally {
|
||
vi.clearAllTimers();
|
||
rmSync(projectDir, { recursive: true, force: true });
|
||
}
|
||
}, 60_000);
|
||
});
|
||
|
||
describe("render command batch options", () => {
|
||
it("forwards gif loop and video frame format to batch row renders", async () => {
|
||
const projectDir = mkdtempSync(join(tmpdir(), "hf-render-batch-options-"));
|
||
const rowsPath = join(projectDir, "rows.json");
|
||
writeFileSync(
|
||
join(projectDir, "index.html"),
|
||
'<!doctype html><html><body><div data-composition-id="main" data-width="1920" data-height="1080" data-no-timeline></div></body></html>',
|
||
"utf8",
|
||
);
|
||
writeFileSync(rowsPath, "[{}]", "utf8");
|
||
|
||
try {
|
||
await renderModule.default.run?.({
|
||
args: {
|
||
dir: projectDir,
|
||
batch: rowsPath,
|
||
output: join(projectDir, "renders", "{index}.gif"),
|
||
fps: "15",
|
||
quality: "standard",
|
||
format: "gif",
|
||
"gif-loop": "3",
|
||
"video-frame-format": "png",
|
||
quiet: true,
|
||
},
|
||
} as never);
|
||
|
||
expect(producerState.createdJobs.at(-1)).toMatchObject({
|
||
format: "gif",
|
||
gifLoop: 3,
|
||
videoFrameFormat: "png",
|
||
});
|
||
} finally {
|
||
rmSync(projectDir, { recursive: true, force: true });
|
||
}
|
||
}, 60_000);
|
||
});
|
||
|
||
describe("normalizeStageCode", () => {
|
||
const { normalizeStageCode } = renderModule;
|
||
|
||
it("maps every known updateJobStatus stage string to its code", () => {
|
||
expect(normalizeStageCode("Queued")).toBe("queued");
|
||
expect(normalizeStageCode("Compiling composition")).toBe("compiling_composition");
|
||
expect(normalizeStageCode("Extracting video frames")).toBe("extracting_video_frames");
|
||
expect(normalizeStageCode("Processing audio tracks")).toBe("processing_audio_tracks");
|
||
expect(normalizeStageCode("Starting frame capture")).toBe("starting_frame_capture");
|
||
expect(normalizeStageCode("Render complete")).toBe("render_complete");
|
||
expect(normalizeStageCode("Render cancelled")).toBe("render_cancelled");
|
||
expect(normalizeStageCode("pipeline")).toBe("pipeline");
|
||
});
|
||
|
||
it("keeps one code for the producer's browser start-up counts", () => {
|
||
expect(normalizeStageCode("Starting browsers (0/6 ready)")).toBe("starting_browsers");
|
||
expect(normalizeStageCode("Starting browsers (5/6 ready)")).toBe("starting_browsers");
|
||
});
|
||
|
||
it("keeps one code per stage whatever its live frame counts", () => {
|
||
expect(normalizeStageCode("Encoding frame 600/600")).toBe("encoding_video");
|
||
expect(normalizeStageCode("Encoding frame 12/90")).toBe("encoding_video");
|
||
expect(normalizeStageCode("Capturing frame 120/600 (6 workers)")).toBe("capturing_frame");
|
||
expect(normalizeStageCode("Streaming frame 3/40 (segment 1/2, 2 workers)")).toBe(
|
||
"streaming_frame",
|
||
);
|
||
expect(normalizeStageCode("Assembling final video")).toBe("assembling_final_video");
|
||
});
|
||
|
||
it("slugifies an unrecognized stage string instead of bucketing it as unknown", () => {
|
||
expect(normalizeStageCode("Some New Stage!")).toBe("some_new_stage");
|
||
});
|
||
|
||
it("falls back to unknown only when slugifying produces nothing usable", () => {
|
||
expect(normalizeStageCode("")).toBe("unknown");
|
||
expect(normalizeStageCode("!!!")).toBe("unknown");
|
||
});
|
||
});
|
||
|
||
// Variables-helper tests live in `../utils/variables.test.ts`.
|