Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

test(web): avoid broad imports during resource cleanup (#17237)

Tobias Wochinger6b6fa75e3d1d
diff --git a/packages/shared/AGENTS.md b/packages/shared/AGENTS.md
index 5711023e61..993d3e87c9 100644
--- a/packages/shared/AGENTS.md
+++ b/packages/shared/AGENTS.md
@@ -57,6 +57,10 @@
AI SDK-native LLM execution helpers (`generateLLMText` and
`streamLLMText`), Bedrock default-credential provider auth
(`createDefaultBedrockProviderAuth`), and server test utilities.
+- `@langfuse/shared/src/server/clickhouse` via `src/server/clickhouse/index.ts`:
+ ClickHouse clients and helpers without loading the full server barrel. Use this
+ entry point for test cleanup so built and source-aliased clients retain the same
+ module identity.
- `@langfuse/shared/src/db` via `src/db.ts`: Prisma client singleton plus
Prisma namespace/types for direct database access. Never route this into
frontend-safe code.
diff --git a/packages/shared/package.json b/packages/shared/package.json
index 596f07f4ae..23b83e9cd4 100644
--- a/packages/shared/package.json
+++ b/packages/shared/package.json
@@ -31,6 +31,10 @@
"import": "./dist/src/server/index.js",
"require": "./dist/src/server/index.js"
},
+ "./src/server/clickhouse": {
+ "import": "./dist/src/server/clickhouse/index.js",
+ "require": "./dist/src/server/clickhouse/index.js"
+ },
"./src/server/clickhouse/clickhouseIdentifiers": {
"import": "./dist/src/server/clickhouse/clickhouseIdentifiers.js",
"require": "./dist/src/server/clickhouse/clickhouseIdentifiers.js"
diff --git a/packages/shared/src/server/clickhouse/index.ts b/packages/shared/src/server/clickhouse/index.ts
new file mode 100644
index 0000000000..558399d77d
--- /dev/null
+++ b/packages/shared/src/server/clickhouse/index.ts
@@ -0,0 +1 @@
+export { ClickHouseClientManager, clickhouseClient } from "./client";
diff --git a/web/AGENTS.md b/web/AGENTS.md
index 2b3a15e144..71e459435c 100644
--- a/web/AGENTS.md
+++ b/web/AGENTS.md
@@ -199,6 +199,10 @@ Sentry instrumentation skill first and decide whether it should capture at all
`JobConfiguration` naming into the public contract.
- Keep tests independent; in `src/__tests__/server/**`, prefer scoped cleanup or
unique test data over global reset helpers.
+- Test teardown closes existing `globalThis.redis` and imports ClickHouse through
+ `@langfuse/shared/src/server/clickhouse`, not the full server barrel or relative
+ shared source paths. Suites own their private Redis clients; shared-context
+ workers skip per-file teardown.
- Put pure server unit tests that do not need Postgres bootstrap under
`src/__tests__/server/unit/**` so they skip the shared DB setup hook.
- Server tests that drive the public REST API over HTTP need a web server on
diff --git a/web/src/__tests__/after-teardown.ts b/web/src/__tests__/after-teardown.ts
index 8507eddca8..88521d8a6b 100644
--- a/web/src/__tests__/after-teardown.ts
+++ b/web/src/__tests__/after-teardown.ts
@@ -11,7 +11,4 @@ afterAll(async () => {
}
await teardown();
- // The teardown dynamically imports the heavy @langfuse/shared server module
- // graph; under a fully loaded CI runner that alone can exceed the default
- // 10s hook timeout.
}, 30_000);
diff --git a/web/src/__tests__/server/unit/teardown-shared-source.servertest.ts b/web/src/__tests__/server/unit/teardown-shared-source.servertest.ts
new file mode 100644
index 0000000000..8bc77fceff
--- /dev/null
+++ b/web/src/__tests__/server/unit/teardown-shared-source.servertest.ts
@@ -0,0 +1,17 @@
+import { expect, it, vi } from "vitest";
+import { env } from "@langfuse/shared/src/env";
+import { clickhouseClient } from "@langfuse/shared/src/server";
+import teardown from "../../teardown";
+
+it("closes clients through the same source-module identity", async () => {
+ const client = clickhouseClient({ url: env.CLICKHOUSE_URL });
+ const close = vi.spyOn(client, "close");
+
+ try {
+ await teardown();
+
+ expect(close).toHaveBeenCalledOnce();
+ } finally {
+ close.mockRestore();
+ }
+});
diff --git a/web/src/__tests__/server/unit/teardown.servertest.ts b/web/src/__tests__/server/unit/teardown.servertest.ts
new file mode 100644
index 0000000000..2347508f82
--- /dev/null
+++ b/web/src/__tests__/server/unit/teardown.servertest.ts
@@ -0,0 +1,100 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type * as SharedServer from "@langfuse/shared/src/server";
+import teardown from "../../teardown";
+
+vi.mock("@langfuse/shared/src/server", () => {
+ throw new Error("Test cleanup must not load the shared server barrel");
+});
+
+describe("server test resource cleanup", () => {
+ beforeEach(() => {
+ vi.stubGlobal("redis", undefined);
+ });
+
+ afterEach(() => {
+ vi.unstubAllGlobals();
+ vi.unstubAllEnvs();
+ vi.restoreAllMocks();
+ });
+
+ it("does not initialize Redis when no test opened it", async () => {
+ await teardown();
+
+ expect(globalThis.redis).toBeUndefined();
+ });
+
+ it.each(["ready", "end", "close"])(
+ "disconnects only an active Redis connection (%s)",
+ async (status) => {
+ const disconnect = vi.fn();
+ vi.stubGlobal("redis", { status, disconnect });
+
+ await teardown();
+
+ expect(disconnect).toHaveBeenCalledTimes(status === "ready" ? 1 : 0);
+ },
+ );
+
+ it("waits for existing ClickHouse clients to close", async () => {
+ const { clickhouseClient } =
+ await import("@langfuse/shared/src/server/clickhouse");
+ const client = clickhouseClient();
+ let finishClose!: () => void;
+ const closed = new Promise<void>((resolve) => {
+ finishClose = resolve;
+ });
+ const close = vi.spyOn(client, "close").mockReturnValue(closed);
+ const finished = vi.fn();
+ const cleanup = teardown().then(finished);
+
+ try {
+ await vi.waitFor(() => expect(close).toHaveBeenCalledOnce());
+ expect(finished).not.toHaveBeenCalled();
+ } finally {
+ finishClose();
+ await cleanup;
+ }
+
+ expect(finished).toHaveBeenCalledOnce();
+ });
+
+ it("closes clients created through the built shared server export", async () => {
+ const actual = await vi.importActual<typeof SharedServer>(
+ "@langfuse/shared/src/server",
+ );
+ try {
+ const client = actual.clickhouseClient();
+ const close = vi.spyOn(client, "close");
+
+ await teardown();
+
+ expect(close).toHaveBeenCalledOnce();
+ } finally {
+ actual.redis?.disconnect();
+ }
+ });
+
+ it("leaves shared-context resources open for later test files", async () => {
+ const { clickhouseClient } =
+ await import("@langfuse/shared/src/server/clickhouse");
+ const disconnect = vi.fn();
+ const close = vi.spyOn(clickhouseClient(), "close");
+ vi.stubGlobal("redis", { status: "ready", disconnect });
+ vi.stubEnv("VITEST_SHARED_CONTEXT", "1");
+ let afterAllHook!: () => Promise<void>;
+ vi.stubGlobal("afterAll", (hook: () => Promise<void>) => {
+ afterAllHook = hook;
+ });
+ vi.resetModules();
+ await import("../../after-teardown");
+
+ try {
+ await afterAllHook();
+
+ expect(disconnect).not.toHaveBeenCalled();
+ expect(close).not.toHaveBeenCalled();
+ } finally {
+ await teardown();
+ }
+ });
+});
diff --git a/web/src/__tests__/teardown.ts b/web/src/__tests__/teardown.ts
index 023ecebaff..94f41e2953 100644
--- a/web/src/__tests__/teardown.ts
+++ b/web/src/__tests__/teardown.ts
@@ -1,13 +1,12 @@
export default async function teardown() {
- const { redis, logger, ClickHouseClientManager } =
- await import("@langfuse/shared/src/server");
-
- logger.debug(`Redis status ${redis?.status}`);
+ // Redis records the existing non-production singleton on globalThis.
+ // Importing its module here would create a connection for otherwise pure tests.
+ const redis = globalThis.redis;
if (redis && redis.status !== "end" && redis.status !== "close") {
redis.disconnect();
}
+ const { ClickHouseClientManager } =
+ await import("@langfuse/shared/src/server/clickhouse");
await ClickHouseClientManager.getInstance().closeAllConnections();
-
- logger.debug("Teardown complete");
}