Context7 Platform -- Up-to-date docs for AI agents
import { afterEach, describe, expect, test, vi } from "vitest";
import { Context7 } from "./client";
import { Context7Error } from "@error";
describe("Context7 Client", () => {
afterEach(() => {
vi.unstubAllEnvs();
vi.unstubAllGlobals();
vi.restoreAllMocks();
});
test("creates a client from the environment", () => {
vi.stubEnv("CONTEXT7_API_KEY", "ctx7sk-environment");
expect(new Context7()).toBeDefined();
});
test("requires an API key or auth token", () => {
vi.stubEnv("CONTEXT7_API_KEY", "");
expect(() => new Context7({ apiKey: "" })).toThrow(Context7Error);
expect(() => new Context7()).toThrow("Authentication is required");
});
test("prefers an explicit OIDC provider over the environment and refreshes every request", async () => {
vi.stubEnv("CONTEXT7_API_KEY", "ctx7sk-legacy-environment-key");
const fetchMock = vi.fn().mockImplementation(() =>
Promise.resolve(
new Response(JSON.stringify({ results: [] }), {
headers: { "content-type": "application/json" },
})
)
);
const authToken = vi
.fn<() => Promise<string>>()
.mockResolvedValueOnce("oidc-token-1")
.mockResolvedValueOnce("oidc-token-2");
const client = new Context7({ authToken, fetch: fetchMock, retry: false });
await client.searchLibrary("state management", "react");
await client.searchLibrary("routing", "next.js");
expect(authToken).toHaveBeenCalledTimes(2);
expect(fetchMock.mock.calls[0]?.[1]).toMatchObject({
headers: expect.objectContaining({ Authorization: "Bearer oidc-token-1" }),
});
expect(fetchMock.mock.calls[1]?.[1]).toMatchObject({
headers: expect.objectContaining({ Authorization: "Bearer oidc-token-2" }),
});
});
test("rejects an empty token returned by a provider", async () => {
vi.stubEnv("CONTEXT7_API_KEY", "ctx7sk-legacy-environment-key");
const fetchMock = vi.fn();
const client = new Context7({ authToken: () => "", fetch: fetchMock });
await expect(client.searchLibrary("routing", "next.js")).rejects.toMatchObject({
code: "authentication_error",
retryable: false,
});
expect(fetchMock).not.toHaveBeenCalled();
});
test("prefers the configured API key over the environment", () => {
vi.stubEnv("CONTEXT7_API_KEY", "invalid-environment-key");
const warn = vi.spyOn(console, "warn");
new Context7({ apiKey: "ctx7sk-config" });
expect(warn).not.toHaveBeenCalled();
});
test("prefers an explicit API key when both credential forms are provided", async () => {
const fetchMock = vi.fn().mockResolvedValue(
new Response(JSON.stringify({ results: [] }), {
headers: { "content-type": "application/json" },
})
);
const authToken = vi.fn(() => "oidc-token");
const client = new Context7({
apiKey: "ctx7sk-config",
authToken,
fetch: fetchMock,
retry: false,
});
await client.searchLibrary("routing", "next.js");
expect(authToken).not.toHaveBeenCalled();
expect(fetchMock.mock.calls[0]?.[1]).toMatchObject({
headers: expect.objectContaining({ Authorization: "Bearer ctx7sk-config" }),
});
});
test("works in runtimes without process when an API key is configured", () => {
vi.stubGlobal("process", undefined);
expect(new Context7({ apiKey: "ctx7sk-config" })).toBeDefined();
expect(() => new Context7()).toThrow(Context7Error);
});
test("forwards transport configuration and protects the authorization header", async () => {
const fetchMock = vi.fn().mockResolvedValue(
new Response(JSON.stringify({ results: [] }), {
headers: { "content-type": "application/json" },
})
);
const onResponse = vi.fn();
const client = new Context7({
apiKey: "ctx7sk-config",
baseUrl: "https://proxy.example.com/context7/",
cache: "force-cache",
retry: false,
timeout: false,
keepAlive: false,
fetch: fetchMock,
headers: {
authorization: "Bearer should-not-win",
"X-Application": "test-suite",
},
onResponse,
});
await client.searchLibrary("state management", "react");
expect(fetchMock).toHaveBeenCalledOnce();
const [url, init] = fetchMock.mock.calls[0] as unknown as [string, RequestInit];
expect(url).toBe(
"https://proxy.example.com/context7/v2/libs/search?query=state+management&libraryName=react"
);
expect(init).toMatchObject({
cache: "force-cache",
keepalive: false,
headers: {
Authorization: "Bearer ctx7sk-config",
"Content-Type": "application/json",
"X-Application": "test-suite",
},
});
expect(onResponse).toHaveBeenCalledWith({ status: 200, attempt: 0 });
});
test("forwards per-request cache, timeout, and abort options", async () => {
const fetchMock = vi.fn().mockResolvedValue(
new Response(JSON.stringify({ results: [] }), {
headers: { "content-type": "application/json" },
})
);
const controller = new AbortController();
const client = new Context7({
apiKey: "ctx7sk-config",
cache: "no-store",
timeout: 30_000,
fetch: fetchMock,
});
await client.searchLibrary("state management", "react", {
cache: "reload",
timeout: false,
signal: controller.signal,
});
const [, init] = fetchMock.mock.calls[0] as unknown as [string, RequestInit];
expect(init.cache).toBe("reload");
expect(init.signal).toBeInstanceOf(AbortSignal);
});
test("sends repeated library hints to the Search API", async () => {
const fetchMock = vi.fn().mockResolvedValue(
new Response(JSON.stringify({ codeSnippets: [], infoSnippets: [] }), {
headers: { "content-type": "application/json" },
})
);
const client = new Context7({
apiKey: "ctx7sk-config",
fetch: fetchMock,
retry: false,
});
await client.search("How do I cache a function?", {
libraries: ["Next.js", "/vercel/next.js"],
version: "15.4.0",
language: "TypeScript",
});
expect(fetchMock.mock.calls[0]?.[0]).toBe(
"https://context7.com/api/v3/search?query=How+do+I+cache+a+function%3F&type=json&library=Next.js&library=%2Fvercel%2Fnext.js&version=15.4.0&language=TypeScript"
);
});
});