🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
/* eslint-disable no-nested-ternary */
import React from "react";
import {
fireEvent,
render,
screen,
waitFor,
within,
} from "@testing-library/react";
import { beforeEach, describe, expect, it, vi } from "vitest";
import {
V4MigrationAgentUpgradeSection,
V4MigrationDetailsContent,
V4MigrationHeaderContent,
} from "./V4MigrationContent";
import {
type MigrationActionState,
type MigrationCountState,
V4_MIGRATION_LOOKBACK_DAYS,
} from "./migrationData";
import {
type V4MigrationSdkState,
type V4MigrationSdkUsageSeries,
} from "./sdkVersionStatus";
import { TABLE_AGGREGATION_OPTIONS } from "@langfuse/shared";
import { rangeFromString } from "@/src/utils/date-range-utils";
const makeSdkUsageSeries = (
overrides: Partial<V4MigrationSdkUsageSeries> = {},
): V4MigrationSdkUsageSeries => {
const source = overrides.source ?? "ingestion-api-dual-write";
const ingestionPath =
overrides.ingestionPath ??
(source === "ingestion-api-dual-write" ? "ingestion_api" : "otel");
const deliveryMode =
overrides.deliveryMode ?? (source === "otel" ? "realtime" : "delayed");
const sdkName = overrides.sdkName ?? "python";
const sdkVersion = overrides.sdkVersion ?? "4.7.1";
const canonicalSdkName = (() => {
if (overrides.canonicalSdkName !== undefined) {
return overrides.canonicalSdkName;
}
if (sdkName === "python") {
return "python";
}
if (sdkName === "javascript" || sdkName.startsWith("@langfuse/")) {
return "javascript";
}
return null;
})();
const sdkVersionMajor =
overrides.sdkVersionMajor !== undefined
? overrides.sdkVersionMajor
: Number(sdkVersion.match(/^v?(\d+)/)?.[1] ?? NaN);
const resolvedMajor = Number.isFinite(sdkVersionMajor)
? Number(sdkVersionMajor)
: null;
const latestMajor = (() => {
if (canonicalSdkName === "python") {
return 4;
}
if (canonicalSdkName === "javascript") {
return 5;
}
return null;
})();
const v4MigrationStatus =
overrides.v4MigrationStatus ??
(canonicalSdkName === null || resolvedMajor === null
? "unknown"
: resolvedMajor >= (latestMajor ?? 0)
? "compatible"
: "upgrade_required");
const remediationType =
overrides.remediationType ??
(canonicalSdkName !== null
? "update_sdk"
: ingestionPath === "otel"
? "update_otel_instrumentation"
: "upgrade_instrumentation");
const actionLevel =
overrides.actionLevel ??
(remediationType === "update_sdk"
? v4MigrationStatus === "compatible"
? "none"
: "required"
: remediationType === "update_otel_instrumentation"
? deliveryMode === "realtime"
? "none"
: "required"
: "required");
return {
source,
ingestionPath,
deliveryMode,
sdkName,
sdkVersion,
canonicalSdkName,
sdkVersionMajor: resolvedMajor,
latestSdkMajor:
overrides.latestSdkMajor !== undefined
? overrides.latestSdkMajor
: latestMajor,
isValidSdkVersion: overrides.isValidSdkVersion ?? resolvedMajor !== null,
publicKey: overrides.publicKey ?? "pk-lf-1234567890abcdef",
eventCount: overrides.eventCount ?? 10,
firstSeen: overrides.firstSeen ?? "2026-07-20T10:00:00Z",
lastSeen: overrides.lastSeen ?? "2026-07-23T10:00:00Z",
attributionStatus: overrides.attributionStatus ?? "attributed",
v4MigrationStatus,
remediationType,
actionLevel,
};
};
const cleanSdkState = (): V4MigrationSdkState => ({
status: "latest",
sdkUsageSeries: [],
upgradeRequiredCount: 0,
delayedOtelIngestionCount: 0,
});
const mocks = vi.hoisted(() => ({
// Mutable so tests can flip between Cloud and self-hosted; the component
// reads the env at render time.
env: { NEXT_PUBLIC_LANGFUSE_CLOUD_REGION: "US" } as {
NEXT_PUBLIC_LANGFUSE_CLOUD_REGION: string | undefined;
},
routerPush: vi.fn(),
capture: vi.fn(),
openAssistant: vi.fn(),
submitAgentMessage: vi.fn(),
upgradePlan: {
canUseAssistant: true,
mode: "evals-ready" as const,
showAssistantButton: true,
assistantPrompt: "eval-upgrade-prompt",
},
migrationData: {
sdk: {
status: "latest" as const,
sdkUsageSeries: [],
upgradeRequiredCount: 0,
delayedOtelIngestionCount: 0,
} as V4MigrationSdkState,
evals: { status: "loaded", count: 0 } as MigrationCountState,
experiments: {
status: "loaded",
result: "not_required",
} as MigrationActionState,
experimentInstrumentationUpgradePath: null as "sdk" | "api" | null,
apis: { status: "loaded", count: 1 } as MigrationCountState,
exports: { status: "loaded", count: 3 } as MigrationCountState,
apiUsage: [
{
endpoint: "GET /api/public/traces",
count: 42,
lastSeen: "2026-07-23T10:37:00Z",
},
] as {
endpoint: string;
count: number;
lastSeen: string;
callers?: {
sdkName?: "python" | "javascript";
sdkVersion?: string;
userAgent?: string;
isOther?: true;
count: number;
lastSeen: string;
}[];
}[],
legacyIntegrations: ["PostHog", "Mixpanel", "Blob Storage"],
},
canToggleV4: true,
isV4: true,
hasApiKeyCreateAccess: true,
canUpdateOrgSettings: true,
aiFeaturesEnabled: true,
createProjectApiKey: vi.fn(),
}));
vi.mock("@/src/env.mjs", () => ({ env: mocks.env }));
vi.mock("next/router", () => ({
useRouter: () => ({
query: { projectId: "project-1" },
push: mocks.routerPush,
}),
}));
vi.mock("@/src/features/support-chat/SupportDrawerProvider", () => ({
useSupportDrawer: () => ({ openWithMode: vi.fn() }),
}));
vi.mock("@/src/features/posthog-analytics/usePostHogClientCapture", () => ({
usePostHogClientCapture: () => mocks.capture,
}));
vi.mock("@/src/utils/api", () => ({
api: {
useUtils: () => ({
projectApiKeys: { invalidate: vi.fn() },
}),
projectApiKeys: {
create: {
useMutation: () => ({
mutateAsync: mocks.createProjectApiKey,
isPending: false,
}),
},
},
},
}));
vi.mock("@/src/features/projects/hooks", () => ({
useProject: () => ({ organization: { id: "org-1" } }),
useQueryProjectOrOrganization: () => ({
organization: {
id: "org-1",
aiFeaturesEnabled: mocks.aiFeaturesEnabled,
},
}),
}));
vi.mock("@/src/features/rbac/utils/checkProjectAccess", () => ({
useHasProjectAccess: () => mocks.hasApiKeyCreateAccess,
}));
vi.mock("@/src/features/rbac/utils/checkOrganizationAccess", () => ({
useHasOrganizationAccess: () => mocks.canUpdateOrgSettings,
}));
vi.mock("@/src/features/v4-migration/hooks/useV4MigrationData", () => ({
useProjectV4MigrationData: () => mocks.migrationData,
useProjectV4SdkData: () => mocks.migrationData.sdk,
useProjectV4EvalData: () => mocks.migrationData.evals,
}));
// The plan hook queries tRPC internally; mock it so tests need no provider.
vi.mock("@/src/features/v4-migration/useV4UpgradeAssistantSupport", () => ({
V4_CODING_AGENT_PROMPT: "coding-agent-prompt",
useEvalUpgradeAssistantPlan: () => mocks.upgradePlan,
}));
vi.mock("@/src/features/in-app-agent/components/InAppAiAgentProvider", () => ({
useIsInAppAgentLauncherVisible: () => true,
useInAppAiAgent: () => ({
openAssistant: mocks.openAssistant,
submit: mocks.submitAgentMessage,
}),
}));
// The toggle row pulls in session + tRPC state via useReadPath; stub it so the
// content tests need no SessionProvider or tRPC client.
vi.mock("@/src/features/events/components/V4SidebarToggle", () => ({
V4PreviewToggleRow: () => null,
}));
// The details content reads canToggleV4 to gate the toggle section's copy.
vi.mock("@/src/features/events/hooks/useReadPath", () => ({
useReadPath: () => ({
canToggleV4: mocks.canToggleV4,
isV4: mocks.isV4,
}),
}));
// Content stays rendered so section-body assertions need no expanding; the
// trigger toggles like Radix (open ↔ closed, seeded from defaultOpen) so the
// expand-only guard in Section is genuinely exercised.
vi.mock("@/src/components/ui/collapsible", () => {
const ToggleContext = React.createContext<() => void>(() => {});
return {
Collapsible: ({
children,
defaultOpen,
onOpenChange,
}: {
children: React.ReactNode;
defaultOpen?: boolean;
onOpenChange?: (open: boolean) => void;
}) => {
const [isOpen, setIsOpen] = React.useState(defaultOpen ?? false);
const toggle = () => {
const next = !isOpen;
setIsOpen(next);
onOpenChange?.(next);
};
return (
<ToggleContext.Provider value={toggle}>
<div>{children}</div>
</ToggleContext.Provider>
);
},
CollapsibleTrigger: ({ children }: { children: React.ReactNode }) => {
const toggle = React.useContext(ToggleContext);
return <button onClick={toggle}>{children}</button>;
},
CollapsibleContent: ({ children }: { children: React.ReactNode }) => (
<div>{children}</div>
),
};
});
describe("V4MigrationDetailsContent", () => {
beforeEach(() => {
vi.clearAllMocks();
mocks.env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION = "US";
mocks.routerPush.mockResolvedValue(true);
mocks.submitAgentMessage.mockResolvedValue(undefined);
mocks.migrationData.evals = { status: "loaded", count: 0 };
mocks.migrationData.experiments = {
status: "loaded",
result: "not_required",
};
mocks.migrationData.experimentInstrumentationUpgradePath = null;
mocks.canToggleV4 = true;
mocks.isV4 = true;
mocks.canUpdateOrgSettings = true;
mocks.aiFeaturesEnabled = true;
mocks.migrationData.sdk = cleanSdkState();
mocks.migrationData.apis = { status: "loaded", count: 1 };
mocks.migrationData.exports = { status: "loaded", count: 3 };
mocks.migrationData.apiUsage = [
{
endpoint: "GET /api/public/traces",
count: 42,
lastSeen: "2026-07-23T10:37:00Z",
},
];
mocks.migrationData.legacyIntegrations = [
"PostHog",
"Mixpanel",
"Blob Storage",
];
});
it("uses deprecated terminology and links to the migration guides", () => {
render(<V4MigrationDetailsContent projectId="project-1" />);
expect(screen.getByText("Migrate APIs")).toBeInTheDocument();
expect(screen.getByText("Migrate APIs")).toHaveClass("font-bold");
expect(screen.getByText("Migrate Integrations")).toBeInTheDocument();
expect(screen.queryByText("Legacy APIs")).not.toBeInTheDocument();
expect(screen.queryByText("Legacy Integrations")).not.toBeInTheDocument();
const endpointLink = screen.getByRole("link", {
name: "GET /api/public/traces",
});
expect(endpointLink).toHaveAttribute(
"href",
"https://langfuse.com/faq/all/deprecated-api-migration",
);
expect(endpointLink).not.toHaveClass("font-bold");
expect(within(endpointLink).getByText("traces")).toHaveClass("font-bold");
expect(
screen.getByTitle("Last seen at 2026-07-23T10:37:00Z"),
).toHaveTextContent(/42 calls · last seen/);
const expectedIntegrationGuides = {
PostHog:
"https://langfuse.com/integrations/analytics/posthog#migrate-export-source",
Mixpanel:
"https://langfuse.com/integrations/analytics/mixpanel#migrate-export-source",
"Blob Storage":
"https://langfuse.com/docs/api-and-data-platform/features/export-to-blob-storage#upgrade-path",
};
for (const [name, href] of Object.entries(expectedIntegrationGuides)) {
const settingsLink = screen.getByRole("link", { name });
expect(settingsLink).toHaveAttribute(
"href",
"/project/project-1/settings/integrations",
);
expect(
within(settingsLink.parentElement!).getByRole("link", {
name: "Migration guide",
}),
).toHaveAttribute("href", href);
}
});
it("rounds estimated API call counts and keeps positive usage visible", () => {
mocks.migrationData.apiUsage = [
{
endpoint: "GET /api/public/traces",
count: 56.5,
lastSeen: "2026-07-23T10:37:00Z",
},
{
endpoint: "GET /api/public/observations",
count: 4.5,
lastSeen: "2026-07-22T10:37:00Z",
},
{
endpoint: "GET /api/public/traces/{id}",
count: 1 / 3,
lastSeen: "2026-07-21T10:37:00Z",
},
];
render(<V4MigrationDetailsContent projectId="project-1" />);
expect(
screen.getByTitle("Last seen at 2026-07-23T10:37:00Z"),
).toHaveTextContent(/57 calls · last seen/);
expect(
screen.getByTitle("Last seen at 2026-07-22T10:37:00Z"),
).toHaveTextContent(/5 calls · last seen/);
expect(
screen.getByTitle("Last seen at 2026-07-21T10:37:00Z"),
).toHaveTextContent(/1 call · last seen/);
});
it("recommends the latest-major method and labels the previous-major fallback", () => {
mocks.migrationData.apiUsage = [
{
endpoint: "GET /api/public/scores/{id}",
count: 2,
lastSeen: "2026-07-23T10:37:00Z",
callers: [
{
sdkName: "python" as const,
sdkVersion: "4.9.0",
userAgent: "langfuse-python/4.9.0",
count: 2,
lastSeen: "2026-07-23T10:37:00Z",
},
],
},
];
render(<V4MigrationDetailsContent projectId="project-1" />);
const guidance = screen.getByText(
"client.api.scores.get_by_id",
).parentElement!;
expect(guidance).toHaveTextContent(
"Replace client.api.scores.get_by_id with client.api.scores.get_many(id=...) (SDK v5). On 4.8.1–4.x, use client.api.scores_v3.get_many_v3.",
);
});
it("shows the caller and exact SDK migration action", () => {
mocks.migrationData.apiUsage = [
{
endpoint: "GET /api/public/traces/{id}",
count: 4,
lastSeen: "2026-07-23T10:37:00Z",
callers: [
{
sdkName: "python" as const,
sdkVersion: "3.9.0",
userAgent: "langfuse-python/3.9.0",
count: 3,
lastSeen: "2026-07-23T10:37:00Z",
},
{
userAgent: "codex-cli/1.2.3",
count: 1,
lastSeen: "2026-07-23T10:30:00Z",
},
],
},
];
render(<V4MigrationDetailsContent projectId="project-1" />);
expect(screen.getByText("Langfuse Python SDK 3.9.0")).toBeInTheDocument();
expect(screen.getByText("client.api.trace.get")).toBeInTheDocument();
expect(
screen.getByText("client.api.observations.get_many"),
).toBeInTheDocument();
expect(screen.getByText("4.0.0 or newer")).toBeInTheDocument();
expect(screen.getByText("Codex")).toBeInTheDocument();
expect(screen.getByText(/traffic from a coding agent/)).toBeInTheDocument();
expect(screen.queryByText("User-Agent:")).not.toBeInTheDocument();
expect(
screen.queryByTitle("Last seen at 2026-07-23T10:37:00Z"),
).not.toBeInTheDocument();
for (const callerName of ["Langfuse Python SDK 3.9.0", "Codex"]) {
const caller = screen.getByText(callerName).closest("li");
expect(caller).toHaveClass("bg-muted/50", "border-l-4", "p-2");
expect(caller?.firstElementChild).toHaveTextContent(callerName);
expect(caller?.firstElementChild).toHaveTextContent(/calls? · last seen/);
expect(
within(caller?.firstElementChild as HTMLElement).queryByRole("link"),
).not.toBeInTheDocument();
const docsLink = within(caller!).getByRole("link", {
name: "See docs.",
});
expect(docsLink).toHaveAttribute(
"href",
"https://langfuse.com/faq/all/deprecated-api-migration",
);
expect(docsLink.parentElement).toHaveTextContent(/See docs\.$/);
}
fireEvent.click(screen.getAllByRole("link", { name: "See docs." })[0]!);
expect(mocks.capture).toHaveBeenCalledWith(
"v4_migration:section_link_clicked",
{ section: "apis", link: "deprecated_api_caller_docs" },
);
});
it("shows route totals without a caller section for unknown-only callers", () => {
mocks.migrationData.apiUsage = [
{
endpoint: "GET /api/public/traces",
count: 42,
lastSeen: "2026-07-23T10:37:00Z",
callers: [
{
isOther: true,
count: 42,
lastSeen: "2026-07-23T10:37:00Z",
},
],
},
];
render(<V4MigrationDetailsContent projectId="project-1" />);
expect(
screen.getByTitle("Last seen at 2026-07-23T10:37:00Z"),
).toHaveTextContent(/42 calls · last seen/);
expect(screen.queryByText("Unknown callers")).not.toBeInTheDocument();
expect(screen.queryByRole("list")).not.toBeInTheDocument();
});
it("collapses clean sections into one up-to-date summary", () => {
mocks.migrationData.apis = { status: "loaded", count: 0 };
mocks.migrationData.exports = { status: "loaded", count: 0 };
mocks.migrationData.apiUsage = [];
mocks.migrationData.legacyIntegrations = [];
render(<V4MigrationDetailsContent projectId="project-1" />);
expect(
screen.getByText(
`SDK, instrumentation, experiment, and API checks cover activity from the last ${V4_MIGRATION_LOOKBACK_DAYS} days. API and experiment usage counts refresh about every 15 minutes, so recent calls may not appear yet.`,
),
).toBeInTheDocument();
expect(
screen.getByText(
"Evals, experiments, APIs and integrations are up to date.",
),
).toBeInTheDocument();
expect(screen.queryByText("Update Evals")).not.toBeInTheDocument();
expect(screen.queryByText("Experiments")).not.toBeInTheDocument();
expect(screen.queryByText("Migrate APIs")).not.toBeInTheDocument();
expect(screen.queryByText("Migrate Integrations")).not.toBeInTheDocument();
});
it("keeps affected sections while summarizing the clean ones", () => {
// Default mock: apis count 1, exports count 3; evals and experiments clean.
render(<V4MigrationDetailsContent projectId="project-1" />);
expect(screen.getByText("Migrate APIs")).toBeInTheDocument();
expect(screen.getByText("Migrate Integrations")).toBeInTheDocument();
expect(
screen.getByText("Evals and experiments are up to date."),
).toBeInTheDocument();
expect(
screen.queryByText("Update Evals", { exact: true }),
).not.toBeInTheDocument();
});
it("uses Update consistently for affected evals", () => {
mocks.migrationData.evals = { status: "loaded", count: 2 };
render(<V4MigrationDetailsContent projectId="project-1" />);
fireEvent.click(screen.getByRole("button", { name: /Update Evals/ }));
expect(
screen.getByText(/Update them to target observations/),
).toBeInTheDocument();
expect(screen.queryByText(/Repoint them/)).not.toBeInTheDocument();
expect(screen.queryByText(/Retarget them/)).not.toBeInTheDocument();
});
it("shows the experiment instrumentation upgrade requirement", () => {
mocks.migrationData.experiments = { status: "loaded", result: "required" };
mocks.migrationData.experimentInstrumentationUpgradePath = "sdk";
render(<V4MigrationDetailsContent projectId="project-1" />);
fireEvent.click(screen.getByRole("button", { name: /Experiments/ }));
expect(screen.getByText(/POST \/dataset-run-items/)).toBeInTheDocument();
expect(
screen.getByRole("link", { name: "Upgrade the SDK" }),
).toBeInTheDocument();
});
it("shows inconclusive experiment runner usage as needing review", () => {
mocks.migrationData.experiments = {
status: "loaded",
result: "sdk_usage_inconclusive",
};
mocks.migrationData.experimentInstrumentationUpgradePath = "sdk";
render(<V4MigrationDetailsContent projectId="project-1" />);
fireEvent.click(screen.getByRole("button", { name: /Experiments/ }));
expect(
screen.getByText(/supports the experiment runner/),
).toBeInTheDocument();
expect(screen.getByText(".link()")).toBeInTheDocument();
});
it("asks direct API users to replace dataset-run-items POST usage", () => {
mocks.migrationData.experiments = { status: "loaded", result: "required" };
mocks.migrationData.experimentInstrumentationUpgradePath = "api";
render(<V4MigrationDetailsContent projectId="project-1" />);
fireEvent.click(screen.getByRole("button", { name: /Experiments/ }));
expect(
screen.getByRole("link", {
name: "OTel experiment instrumentation guide",
}),
).toBeInTheDocument();
});
it("hides the tracing sections when no ingestion data was detected", () => {
mocks.migrationData.sdk.status = "no_data";
render(<V4MigrationDetailsContent projectId="project-1" />);
expect(screen.queryByText("Update SDK")).not.toBeInTheDocument();
expect(
screen.queryByText("Update OTel Instrumentation"),
).not.toBeInTheDocument();
expect(screen.queryByText("Needs review")).not.toBeInTheDocument();
});
it("hides the tracing sections when everything detected is up to date", () => {
mocks.migrationData.sdk = {
...cleanSdkState(),
sdkUsageSeries: [
makeSdkUsageSeries({}),
makeSdkUsageSeries({
source: "otel",
sdkName: "otelcol",
sdkVersion: "0.98.0",
canonicalSdkName: null,
}),
],
};
render(<V4MigrationDetailsContent projectId="project-1" />);
expect(screen.queryByText("Update SDK")).not.toBeInTheDocument();
expect(
screen.queryByText("Update OTel Instrumentation"),
).not.toBeInTheDocument();
expect(
screen.getByText("Detected V4-compatible instrumentation"),
).toBeInTheDocument();
expect(screen.getByText("Python 4.7.1")).toBeInTheDocument();
expect(screen.getByText("otelcol 0.98.0")).toBeInTheDocument();
expect(screen.getByText(/Python SDK v5 is available/)).toBeInTheDocument();
expect(screen.getByRole("link", { name: "Upgrade guide" })).toHaveAttribute(
"href",
"https://langfuse.com/docs/observability/sdk/upgrade-path/python-v4-to-v5",
);
expect(screen.queryByText("· up to date")).not.toBeInTheDocument();
expect(screen.getByText("· real-time")).toBeInTheDocument();
});
it("shows SDK traffic on the latest major as up to date without an upgrade nudge", () => {
mocks.migrationData.sdk = {
...cleanSdkState(),
sdkUsageSeries: [
makeSdkUsageSeries({ sdkVersion: "5.0.1" }),
makeSdkUsageSeries({
sdkName: "@langfuse/tracing",
sdkVersion: "6.0.0",
publicKey: "pk-lf-fedcba0987654321",
}),
],
};
render(<V4MigrationDetailsContent projectId="project-1" />);
expect(screen.getAllByText("· up to date")).toHaveLength(2);
expect(screen.queryByText(/is available/)).not.toBeInTheDocument();
expect(
screen.queryByRole("link", { name: "Upgrade guide" }),
).not.toBeInTheDocument();
});
it("lists only required SDK series in Update SDK and shows compatible ones as detected", () => {
mocks.migrationData.sdk = {
status: "legacy",
sdkUsageSeries: [
makeSdkUsageSeries({
sdkVersion: "2.60.3",
}),
makeSdkUsageSeries({
sdkVersion: "4.6.9",
publicKey: "pk-lf-fedcba0987654321",
}),
],
upgradeRequiredCount: 1,
delayedOtelIngestionCount: 0,
};
render(<V4MigrationDetailsContent projectId="project-1" />);
expect(screen.getByText("Update SDK")).toBeInTheDocument();
expect(
within(screen.getByText("Update SDK").closest("button")!).getByText("1"),
).toBeInTheDocument();
expect(screen.getByText("Python 2.60.3")).toBeInTheDocument();
expect(
screen.getByText("· upgrade required to v5 (>= 4.0.0 also works)"),
).toBeInTheDocument();
// Compatible previous-major traffic lands in the detected section.
expect(
screen.getByText("Detected V4-compatible instrumentation"),
).toBeInTheDocument();
expect(screen.getByText("Python 4.6.9")).toBeInTheDocument();
expect(screen.getByText(/Python SDK v5 is available/)).toBeInTheDocument();
expect(
screen.queryByText("· recommended to upgrade to >= 4.7.0"),
).not.toBeInTheDocument();
// The explicit evidence link targets this key + SDK name/version over the
// detection lookback window, so versions on the same key stay distinct.
const outdatedRow = screen.getByText("Python 2.60.3").closest("li")!;
const evidenceLink = within(outdatedRow).getByRole("link", {
name: "View observations",
});
expect(evidenceLink).toHaveAttribute(
"href",
`/project/project-1/observations?filter=${encodeURIComponent(
"ingestionApiKey;stringOptions;;any of;pk-lf-1234567890abcdef," +
"ingestionSource;stringOptions;;any of;ingestion-api-dual-write," +
"ingestionSdkName;stringOptions;;any of;python," +
"ingestionSdkVersion;stringOptions;;any of;2.60.3",
)}&dateRange=${V4_MIGRATION_LOOKBACK_DAYS}d`,
);
expect(evidenceLink).toHaveAttribute("target", "_blank");
expect(evidenceLink).toHaveAttribute("rel", "noopener noreferrer");
expect(
within(outdatedRow).queryByRole("link", {
name: "pk-lf-123…abcdef",
}),
).not.toBeInTheDocument();
expect(
screen.queryByText("Update OTel Instrumentation"),
).not.toBeInTheDocument();
});
it("hides Update SDK when every SDK series is already compatible", () => {
mocks.migrationData.sdk = {
status: "latest",
sdkUsageSeries: [
makeSdkUsageSeries({
sdkVersion: "4.6.9",
}),
],
upgradeRequiredCount: 0,
delayedOtelIngestionCount: 0,
};
render(<V4MigrationDetailsContent projectId="project-1" />);
expect(screen.queryByText("Update SDK")).not.toBeInTheDocument();
expect(screen.queryByText(/needs an update/)).not.toBeInTheDocument();
expect(
screen.getByText("Detected V4-compatible instrumentation"),
).toBeInTheDocument();
expect(screen.getByText("Python 4.6.9")).toBeInTheDocument();
});
it("keeps outdated SDK usage surfaced when a newer version later used the same key", () => {
// The check reports what it observed in the lookback window: a newer SDK
// ingesting later on the same public key is not evidence that the
// outdated usage is gone, so it must not retire the offender.
mocks.migrationData.sdk = {
status: "legacy",
sdkUsageSeries: [
makeSdkUsageSeries({
sdkVersion: "2.60.3",
firstSeen: "2026-07-20T09:00:00Z",
lastSeen: "2026-07-20T10:00:00Z",
}),
makeSdkUsageSeries({
firstSeen: "2026-07-21T09:00:00Z",
lastSeen: "2026-07-21T10:00:00Z",
}),
],
upgradeRequiredCount: 1,
delayedOtelIngestionCount: 0,
};
render(<V4MigrationDetailsContent projectId="project-1" />);
expect(
within(screen.getByText("Update SDK").closest("button")!).getByText("1"),
).toBeInTheDocument();
expect(screen.getByText("Python 2.60.3")).toBeInTheDocument();
expect(screen.getByText(/upgrade required/)).toBeInTheDocument();
expect(screen.queryByText(/upgrade completed/)).not.toBeInTheDocument();
// Compatible series are listed under the detected section, not Update SDK.
expect(
screen.getByText("Detected V4-compatible instrumentation"),
).toBeInTheDocument();
expect(screen.getByText("Python 4.7.1")).toBeInTheDocument();
});
it("renders the key as plain text when an offender has no observation evidence", () => {
// A series with no events_core rows: a link would open an empty table,
// so the evidence link must stay hidden.
mocks.migrationData.sdk = {
status: "legacy",
sdkUsageSeries: [
makeSdkUsageSeries({
sdkVersion: "2.60.3",
eventCount: 0,
}),
],
upgradeRequiredCount: 1,
delayedOtelIngestionCount: 0,
};
render(<V4MigrationDetailsContent projectId="project-1" />);
expect(screen.getByText("Python 2.60.3")).toBeInTheDocument();
expect(screen.getByText("pk-lf-123…abcdef")).toBeInTheDocument();
expect(
screen.queryByRole("link", { name: "View observations" }),
).not.toBeInTheDocument();
});
it("links keyless raw OTel observations with an exact empty-key filter", () => {
mocks.migrationData.sdk = {
status: "otel_header_required",
sdkUsageSeries: [
makeSdkUsageSeries({
source: "otel-dual-write",
sdkName: "unknown",
sdkVersion: "unknown",
canonicalSdkName: null,
publicKey: "",
}),
],
upgradeRequiredCount: 0,
delayedOtelIngestionCount: 1,
};
render(<V4MigrationDetailsContent projectId="project-1" />);
expect(screen.getByText("No API key")).toBeInTheDocument();
expect(screen.getByText("Custom instrumentation")).toBeInTheDocument();
const evidenceLink = screen.getByRole("link", {
name: "View observations",
});
expect(evidenceLink).toHaveAttribute(
"href",
`/project/project-1/observations?filter=${encodeURIComponent(
"ingestionApiKey;stringOptions;;any of;," +
"ingestionSource;stringOptions;;any of;otel-dual-write",
)}&dateRange=${V4_MIGRATION_LOOKBACK_DAYS}d`,
);
expect(evidenceLink).toHaveAttribute("target", "_blank");
expect(evidenceLink).toHaveAttribute("rel", "noopener noreferrer");
});
it("captures panel_checks_loaded once when all checks settle", () => {
const { rerender } = render(
<V4MigrationDetailsContent projectId="project-1" />,
);
rerender(<V4MigrationDetailsContent projectId="project-1" />);
const loadedCalls = mocks.capture.mock.calls.filter(
([name]) => name === "v4_migration:panel_checks_loaded",
);
expect(loadedCalls).toHaveLength(1);
expect(loadedCalls[0]![1]).toEqual({
readiness: "action-needed",
sdkStatus: "latest",
sdkActionableCount: 0,
delayedOtelCount: 0,
customInstrumentationCount: 0,
evalsCount: 0,
apisCount: 1,
integrationsCount: 3,
experimentsResult: "not_required",
});
});
it("holds panel_checks_loaded while a check is still running", () => {
mocks.migrationData.evals = { status: "loading", count: 0 };
render(<V4MigrationDetailsContent projectId="project-1" />);
expect(mocks.capture).not.toHaveBeenCalledWith(
"v4_migration:panel_checks_loaded",
expect.anything(),
);
});
it("holds panel_checks_loaded when one check errors while another loads", () => {
// readiness collapses to "unavailable" on the first error, but the event
// must wait for the in-flight checks instead of locking in a mid-flight
// snapshot; errored counts then report null, not a clean-looking zero.
mocks.migrationData.evals = { status: "error", count: 0 };
mocks.migrationData.apis = { status: "loading", count: 0 };
render(<V4MigrationDetailsContent projectId="project-1" />);
expect(mocks.capture).not.toHaveBeenCalledWith(
"v4_migration:panel_checks_loaded",
expect.anything(),
);
mocks.migrationData.apis = { status: "loaded", count: 1 };
render(<V4MigrationDetailsContent projectId="project-1" />);
expect(mocks.capture).toHaveBeenCalledWith(
"v4_migration:panel_checks_loaded",
expect.objectContaining({ readiness: "unavailable", evalsCount: null }),
);
});
it("captures section_expanded and evidence_link_clicked in the SDK section", () => {
const onNavigate = vi.fn();
mocks.migrationData.sdk = {
status: "legacy",
sdkUsageSeries: [
makeSdkUsageSeries({
sdkVersion: "2.60.3",
v4MigrationStatus: "upgrade_required",
}),
],
upgradeRequiredCount: 1,
delayedOtelIngestionCount: 0,
};
render(
<V4MigrationDetailsContent
projectId="project-1"
onNavigate={onNavigate}
/>,
);
fireEvent.click(screen.getByText("Update SDK").closest("button")!);
expect(mocks.capture).toHaveBeenCalledWith(
"v4_migration:section_expanded",
{ section: "sdk" },
);
// Collapsing must not count as engagement.
fireEvent.click(screen.getByText("Update SDK").closest("button")!);
expect(
mocks.capture.mock.calls.filter(
([name]) => name === "v4_migration:section_expanded",
),
).toHaveLength(1);
fireEvent.click(screen.getByRole("link", { name: "View observations" }));
expect(onNavigate).not.toHaveBeenCalled();
// Only bounded values: the canonical SDK enum and status enums — never
// the raw client-supplied sdkName/sdkVersion header strings.
expect(mocks.capture).toHaveBeenCalledWith(
"v4_migration:evidence_link_clicked",
{
section: "sdk",
sdkName: "python",
v4MigrationStatus: "upgrade_required",
attributionStatus: "attributed",
},
);
fireEvent.click(screen.getByRole("link", { name: "upgrade path" }));
expect(mocks.capture).toHaveBeenCalledWith(
"v4_migration:section_link_clicked",
{ section: "sdk", link: "sdk_upgrade_docs" },
);
});
it("shows delayed OTel exporters and moves realtime OTel to Detected", () => {
mocks.migrationData.sdk = {
status: "otel_header_required",
sdkUsageSeries: [
makeSdkUsageSeries({}),
makeSdkUsageSeries({
source: "otel-dual-write",
sdkName: "openlit",
sdkVersion: "1.35.4",
canonicalSdkName: null,
publicKey: "pk-lf-aaaa000011112222",
}),
makeSdkUsageSeries({
source: "otel",
sdkName: "otelcol",
sdkVersion: "0.98.0",
canonicalSdkName: null,
publicKey: "pk-lf-bbbb333344445555",
}),
],
upgradeRequiredCount: 0,
delayedOtelIngestionCount: 1,
};
render(<V4MigrationDetailsContent projectId="project-1" />);
expect(screen.getByText("Update OTel Instrumentation")).toBeInTheDocument();
expect(
within(
screen.getByText("Update OTel Instrumentation").closest("button")!,
).getByText("1"),
).toBeInTheDocument();
expect(
screen.getByText("x-langfuse-ingestion-version: 4").closest("p"),
).toHaveTextContent(
"Your OpenTelemetry data is using delayed ingestion. For real-time ingestion, upgrade your integration or, if you use OpenTelemetry directly, set x-langfuse-ingestion-version: 4 on your OTLP exporter. Migration guide.",
);
expect(screen.getByText("openlit 1.35.4")).toBeInTheDocument();
expect(screen.getByText("· delayed")).toBeInTheDocument();
expect(screen.queryByText("Update SDK")).not.toBeInTheDocument();
// Compatible SDK + realtime OTel land in the detected section.
expect(
screen.getByText("Detected V4-compatible instrumentation"),
).toBeInTheDocument();
expect(screen.getByText("Python 4.7.1")).toBeInTheDocument();
expect(screen.getByText("otelcol 0.98.0")).toBeInTheDocument();
expect(screen.getByText("· real-time")).toBeInTheDocument();
});
it("keeps Update SDK visible for a recognized SDK with an unparsable version", () => {
mocks.migrationData.sdk = {
status: "unknown",
sdkUsageSeries: [
makeSdkUsageSeries({
sdkVersion: "not-a-version",
sdkVersionMajor: null,
isValidSdkVersion: false,
v4MigrationStatus: "unknown",
actionLevel: "required",
}),
],
upgradeRequiredCount: 0,
delayedOtelIngestionCount: 0,
};
render(<V4MigrationDetailsContent projectId="project-1" />);
expect(screen.getByText("Update SDK")).toBeInTheDocument();
// Badge and sentence share the same count.
expect(
within(screen.getByText("Update SDK").closest("button")!).getByText("1"),
).toBeInTheDocument();
expect(
screen.getByText(/1 detected SDK configuration needs an update/),
).toBeInTheDocument();
expect(screen.getByText("· version not recognized")).toBeInTheDocument();
});
it("keeps the evidence-link date range expressible as a table range", () => {
// The events table resolves ?dateRange= through rangeFromString against
// TABLE_AGGREGATION_OPTIONS; an unknown abbreviation silently falls back
// to the page default and unscopes the evidence links.
expect(
rangeFromString(
`${V4_MIGRATION_LOOKBACK_DAYS}d`,
TABLE_AGGREGATION_OPTIONS,
"last1Day",
),
).toEqual({ range: `last${V4_MIGRATION_LOOKBACK_DAYS}Days` });
});
it("renders the public key as plain text when the v4 preview is off", () => {
mocks.isV4 = false;
mocks.migrationData.sdk = {
status: "legacy",
sdkUsageSeries: [
makeSdkUsageSeries({
sdkVersion: "2.60.3",
v4MigrationStatus: "upgrade_required",
}),
],
upgradeRequiredCount: 1,
delayedOtelIngestionCount: 0,
};
render(<V4MigrationDetailsContent projectId="project-1" />);
expect(screen.getByText("pk-lf-123…abcdef")).toBeInTheDocument();
expect(
screen.queryByRole("link", { name: "View observations" }),
).not.toBeInTheDocument();
});
it("shows ingestion-API traffic without an SDK header as Upgrade Instrumentation", () => {
mocks.migrationData.sdk = {
status: "unknown",
sdkUsageSeries: [
makeSdkUsageSeries({
source: "ingestion-api-dual-write",
sdkName: "unknown",
sdkVersion: "unknown",
canonicalSdkName: null,
attributionStatus: "missing_name_and_version",
}),
],
upgradeRequiredCount: 0,
delayedOtelIngestionCount: 0,
};
render(<V4MigrationDetailsContent projectId="project-1" />);
expect(screen.getByText("Upgrade Instrumentation")).toBeInTheDocument();
expect(
within(
screen.getByText("Upgrade Instrumentation").closest("button")!,
).getByText("1"),
).toBeInTheDocument();
expect(screen.getByText("Custom instrumentation")).toBeInTheDocument();
// Unattributed series ("unknown" SDK name/version) keep a key-only
// evidence link — "unknown" is the fallback bucket, not an exact value.
const customInstrumentationRow = screen
.getByText("Custom instrumentation")
.closest("li")!;
const evidenceLink = within(customInstrumentationRow).getByRole("link", {
name: "View observations",
});
expect(evidenceLink).toHaveAttribute(
"href",
`/project/project-1/observations?filter=${encodeURIComponent(
"ingestionApiKey;stringOptions;;any of;pk-lf-1234567890abcdef," +
"ingestionSource;stringOptions;;any of;ingestion-api-dual-write",
)}&dateRange=${V4_MIGRATION_LOOKBACK_DAYS}d`,
);
expect(evidenceLink).toHaveAttribute("target", "_blank");
expect(evidenceLink).toHaveAttribute("rel", "noopener noreferrer");
// The guidance stays language-agnostic: the upgrade applies to every
// Langfuse SDK, so the copy must not read as Python-or-JS-only.
expect(
screen.getByRole("link", { name: "any Langfuse SDK" }),
).toHaveAttribute(
"href",
"https://langfuse.com/docs/observability/sdk/overview",
);
expect(
screen.getByRole("link", { name: "OpenTelemetry endpoint" }),
).toHaveAttribute(
"href",
"https://langfuse.com/integrations/native/opentelemetry",
);
expect(screen.queryByText("Update SDK")).not.toBeInTheDocument();
expect(
screen.queryByText("Update OTel Instrumentation"),
).not.toBeInTheDocument();
});
it("omits a missing API key from custom instrumentation rows", () => {
mocks.migrationData.sdk = {
status: "unknown",
sdkUsageSeries: [
makeSdkUsageSeries({
source: "ingestion-api-dual-write",
sdkName: "unknown",
sdkVersion: "unknown",
canonicalSdkName: null,
publicKey: "",
attributionStatus: "missing_name_and_version",
}),
],
upgradeRequiredCount: 0,
delayedOtelIngestionCount: 0,
};
render(<V4MigrationDetailsContent projectId="project-1" />);
const row = screen.getByText("Custom instrumentation").closest("li")!;
expect(within(row).queryByText("No API key")).not.toBeInTheDocument();
expect(within(row).getByText(/last seen/)).toBeInTheDocument();
});
it("renders the agent upgrade group with the prompt CTA", () => {
render(<V4MigrationDetailsContent projectId="project-1" />);
expect(screen.getByText("Upgrade using coding agents")).toBeInTheDocument();
expect(
screen.getByText(/Paste prompt into Claude Code or other coding agents/),
).toBeInTheDocument();
expect(
screen.getByRole("button", { name: "Copy prompt" }),
).toBeInTheDocument();
});
it("links the walkthrough video from the help footer on Cloud", () => {
render(<V4MigrationDetailsContent projectId="project-1" />);
const link = screen.getByRole("link", { name: "Walkthrough video" });
// Straight to YouTube in a new tab; the panel never embeds the player,
// so no iframe may render before or after the click.
expect(link).toHaveAttribute(
"href",
"https://www.youtube.com/watch?v=g3YbbqVGt4g",
);
expect(link).toHaveAttribute("target", "_blank");
expect(document.querySelector("iframe")).toBeNull();
fireEvent.click(link);
expect(mocks.capture).toHaveBeenCalledWith(
"v4_migration:walkthrough_video_clicked",
);
expect(document.querySelector("iframe")).toBeNull();
});
it("hides the walkthrough video link on self-hosted deployments", () => {
mocks.env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION = undefined;
render(<V4MigrationDetailsContent projectId="project-1" />);
expect(screen.queryByText("Walkthrough video")).not.toBeInTheDocument();
});
it("shows the preview-toggle section only when the session can toggle v4", () => {
const { unmount } = render(
<V4MigrationDetailsContent projectId="project-1" />,
);
expect(
screen.getByText(/Compare traces while you upgrade/),
).toBeInTheDocument();
unmount();
mocks.canToggleV4 = false;
render(<V4MigrationDetailsContent projectId="project-1" />);
expect(
screen.queryByText(/Compare traces while you upgrade/),
).not.toBeInTheDocument();
});
it("starts the assistant only after confirmation", async () => {
mocks.migrationData.evals = { status: "loaded", count: 1 };
mocks.openAssistant.mockReturnValue(true);
render(<V4MigrationDetailsContent projectId="project-1" />);
fireEvent.click(screen.getByRole("button", { name: "Use Halo" }));
// The panel entry point preselects the assistant: no choice screen.
const migrationDialog = screen.getByRole("dialog");
expect(
within(migrationDialog).getByRole("heading", {
name: "Ready to start your evaluator upgrade?",
}),
).toBeInTheDocument();
expect(
within(migrationDialog).queryByRole("button", {
name: /^Use Halo/,
}),
).not.toBeInTheDocument();
fireEvent.click(
within(migrationDialog).getByRole("button", {
name: "Start upgrade now",
}),
);
await waitFor(() => {
expect(mocks.openAssistant).toHaveBeenCalledWith("v4_migration");
});
expect(mocks.submitAgentMessage).toHaveBeenCalledWith(
"eval-upgrade-prompt",
{ newConversation: true },
);
});
it("keeps the choice screen when AI features are disabled", () => {
mocks.migrationData.evals = { status: "loaded", count: 1 };
mocks.aiFeaturesEnabled = false;
render(<V4MigrationDetailsContent projectId="project-1" />);
// Without AI features the button drops the assistant branding …
expect(
screen.queryByRole("button", { name: "Use Halo" }),
).not.toBeInTheDocument();
fireEvent.click(screen.getByRole("button", { name: "Update evals" }));
// … and the dialog does not preselect the assistant, so the choice
// screen keeps owning the enable-AI flow.
const migrationDialog = screen.getByRole("dialog");
expect(
within(migrationDialog).getByRole("heading", {
name: "How would you like to upgrade your evaluators?",
}),
).toBeInTheDocument();
expect(
within(migrationDialog).getByRole("button", {
name: /^Use Halo/,
}),
).toBeInTheDocument();
});
it("shows the admin handoff after a non-admin chooses the Assistant", () => {
mocks.migrationData.evals = { status: "loaded", count: 1 };
mocks.canUpdateOrgSettings = false;
mocks.aiFeaturesEnabled = false;
render(<V4MigrationDetailsContent projectId="project-1" />);
fireEvent.click(screen.getByRole("button", { name: "Update evals" }));
const migrationDialog = screen.getByRole("dialog");
fireEvent.click(
within(migrationDialog).getByRole("button", {
name: /^Use Halo/,
}),
);
expect(
screen.getByRole("heading", {
name: "Ask your organization admin to enable AI features",
}),
).toBeInTheDocument();
expect(
screen.getByText(/enable AI features for our Langfuse organization/),
).toBeInTheDocument();
expect(
screen.queryByRole("button", { name: "Continue with manual upgrade" }),
).not.toBeInTheDocument();
});
});
describe("V4MigrationHeaderContent", () => {
beforeEach(() => {
mocks.env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION = "US";
mocks.migrationData.evals = { status: "loaded", count: 0 };
mocks.migrationData.experiments = {
status: "loaded",
result: "not_required",
};
mocks.migrationData.experimentInstrumentationUpgradePath = null;
mocks.migrationData.apis = { status: "loaded", count: 1 };
mocks.migrationData.exports = { status: "loaded", count: 3 };
mocks.hasApiKeyCreateAccess = true;
mocks.createProjectApiKey.mockReset();
mocks.createProjectApiKey.mockImplementation(
({ projectId }: { projectId: string }) =>
Promise.resolve({
secretKey: `sk-lf-${projectId}`,
publicKey: `pk-lf-${projectId}`,
}),
);
});
it("uses the project-independent compatibility title and requested description", () => {
render(<V4MigrationHeaderContent readiness="action-needed" />);
// The title stays off the version number: the app shell already shows a v4
// build, so a "upgrade to v4" headline read as a contradiction.
expect(
screen.getByText("Ensure compatibility after November 16"),
).toBeInTheDocument();
expect(screen.queryByText("Upgrade to v4")).not.toBeInTheDocument();
expect(screen.queryByText(/Project 1/)).not.toBeInTheDocument();
expect(screen.getByText(/Langfuse v4 is live/)).toHaveTextContent(
"Langfuse v4 is live: a re-architecture of our data model and database tables. It is up to 165× more performant in UI and on APIs. It also enables new features such as full-text search, a new filter search bar, alerts, code evaluators, and the Langfuse Halo. Complete the action items below to avoid disruption. See docs.",
);
expect(
screen.getByRole("link", { name: "full-text search" }),
).toHaveAttribute(
"href",
"https://langfuse.com/docs/observability/features/full-text-search",
);
expect(
screen.getByRole("link", { name: "new filter search bar" }),
).toHaveAttribute(
"href",
"https://langfuse.com/docs/observability/features/filter-search-bar",
);
expect(screen.getByRole("link", { name: "alerts" })).toHaveAttribute(
"href",
"https://langfuse.com/docs/metrics/features/alerts",
);
expect(
screen.getByRole("link", { name: "code evaluators" }),
).toHaveAttribute(
"href",
"https://langfuse.com/docs/evaluation/evaluation-methods/code-evaluators",
);
expect(screen.getByRole("link", { name: "Langfuse Halo" })).toHaveAttribute(
"href",
"https://langfuse.com/docs/langfuse-assistant",
);
expect(screen.getByRole("link", { name: "See docs." })).toHaveAttribute(
"href",
"https://langfuse.com/docs/v4",
);
expect(
screen.getByText(/some features may stop working/),
).toHaveTextContent(
"After November 16, 2026 some features may stop working if you don't update integrations.",
);
expect(
screen.getByRole("link", { name: "November 16, 2026" }),
).toHaveAttribute("href", "https://langfuse.com/docs/v4#timeline");
});
it("drops the dated deadline for self-hosted deployments", () => {
// The date is a Cloud commitment: a self-hosted deployment keeps its legacy
// surfaces until its own operator moves the write mode off dual.
mocks.env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION = undefined;
render(<V4MigrationHeaderContent readiness="action-needed" />);
expect(screen.getByText("Ensure compatibility")).toBeInTheDocument();
expect(screen.getByText(/features may stop working/)).toHaveTextContent(
"Some features may stop working if you don't update integrations before your administrator disables the legacy mode.",
);
expect(screen.queryByText(/November 16/)).not.toBeInTheDocument();
expect(
screen.queryByRole("link", { name: "November 16, 2026" }),
).not.toBeInTheDocument();
});
it("reserves a close-button gutter on the title row when the host asks", () => {
// The modal host floats the dialog's fallback close button over the
// body's top-right corner; without the gutter it overlaps the title.
render(<V4MigrationHeaderContent titleRowClassName="pr-6" />);
expect(
screen.getByText("Ensure compatibility after November 16").parentElement,
).toHaveClass("pr-6");
});
it("keeps the pitch but drops the action ask for ready or unresolved projects", () => {
for (const readiness of [
"ready",
"checking",
"unavailable",
undefined,
] as const) {
const { unmount } = render(
<V4MigrationHeaderContent readiness={readiness} />,
);
expect(
screen.queryByText(/Complete the action items below/),
).not.toBeInTheDocument();
expect(screen.getByText(/Langfuse v4 is live/)).toBeInTheDocument();
expect(
screen.queryByText(/some features may stop working/),
).not.toBeInTheDocument();
unmount();
}
});
it("labels the help footer and groups content with three separators", () => {
const { container } = render(
<V4MigrationDetailsContent projectId="project-1" />,
);
expect(screen.getByText("Need help?")).toBeInTheDocument();
expect(screen.getByRole("link", { name: "Docs" })).toHaveAttribute(
"href",
"https://langfuse.com/docs/v4",
);
// One divider above Action items, one above the agent CTA, one above
// Need help. Decorative Radix separators render role="none", so query
// by data attribute.
expect(
container.querySelectorAll('[data-orientation="horizontal"]'),
).toHaveLength(3);
});
it("shows the prompt without any click and copies it in a single click", () => {
Object.assign(navigator, { clipboard: { writeText: vi.fn() } });
render(<V4MigrationAgentUpgradeSection projectId="project-1" />);
// The prompt is always visible; no reveal step required.
expect(screen.getByText("coding-agent-prompt")).toBeInTheDocument();
expect(mocks.createProjectApiKey).not.toHaveBeenCalled();
// A single CTA click copies; still no credentials. (jsdom has no clipboard.)
fireEvent.click(screen.getByRole("button", { name: "Copy prompt" }));
expect(navigator.clipboard.writeText).toHaveBeenCalledWith(
"coding-agent-prompt",
);
expect(mocks.createProjectApiKey).not.toHaveBeenCalled();
});
it("creates keys only on the explicit create action and shows an env block", async () => {
render(<V4MigrationAgentUpgradeSection projectId="project-1" />);
const createButton = screen.getByRole("button", {
name: "Create API keys",
});
fireEvent.click(createButton);
expect(mocks.createProjectApiKey).toHaveBeenCalledWith({
projectId: "project-1",
name: "v4-migration-key",
});
await waitFor(() =>
expect(
screen.getByText(/LANGFUSE_PUBLIC_KEY=pk-lf-project-1/),
).toBeInTheDocument(),
);
expect(
screen.getByText(/LANGFUSE_SECRET_KEY=sk-lf-project-1/),
).toBeInTheDocument();
expect(screen.getByText(/LANGFUSE_BASE_URL=/)).toBeInTheDocument();
// The secret must never leak into the agent prompt.
expect(screen.getByText("coding-agent-prompt").textContent).not.toContain(
"sk-lf-project-1",
);
// The create action is consumed; no accidental duplicates.
expect(
screen.queryByRole("button", { name: "Create API keys" }),
).not.toBeInTheDocument();
expect(mocks.createProjectApiKey).toHaveBeenCalledTimes(1);
});
it("keeps the prompt available but disables key creation without access", () => {
mocks.hasApiKeyCreateAccess = false;
render(<V4MigrationAgentUpgradeSection projectId="project-1" />);
const promptButton = screen.getByRole("button", { name: "Copy prompt" });
expect(promptButton).toBeEnabled();
expect(screen.getByText("coding-agent-prompt")).toBeInTheDocument();
const createButton = screen.getByRole("button", {
name: "Create API keys",
});
expect(createButton).toBeDisabled();
fireEvent.click(createButton);
expect(mocks.createProjectApiKey).not.toHaveBeenCalled();
});
it("requires a fresh explicit creation when the project changes", async () => {
const { rerender } = render(
<V4MigrationAgentUpgradeSection key="project-1" projectId="project-1" />,
);
fireEvent.click(screen.getByRole("button", { name: "Create API keys" }));
await waitFor(() =>
expect(
screen.getByText(/LANGFUSE_PUBLIC_KEY=pk-lf-project-1/),
).toBeInTheDocument(),
);
rerender(
<V4MigrationAgentUpgradeSection key="project-2" projectId="project-2" />,
);
expect(
screen.queryByText(/LANGFUSE_PUBLIC_KEY=pk-lf-project-1/),
).not.toBeInTheDocument();
fireEvent.click(screen.getByRole("button", { name: "Create API keys" }));
await waitFor(() =>
expect(
screen.getByText(/LANGFUSE_PUBLIC_KEY=pk-lf-project-2/),
).toBeInTheDocument(),
);
expect(mocks.createProjectApiKey).toHaveBeenLastCalledWith({
projectId: "project-2",
name: "v4-migration-key",
});
});
});