Test Guidelines

File Organization

tests/
├── config.test.ts      # src/config/* (project config, loader)
├── mintlify-api.test.ts # src/backends/mintlify.ts
├── embedded.test.ts    # src/backends/embedded/*
└── <module>.test.ts    # One file per major module

Rule: One test file per source module. Don't create embedded.test.ts if tests belong in config.test.ts.

What Makes a Test Useful

Good Tests (Keep)

// 1. Integration with real systems (LanceDB, APIs)
test("persists data across instances", async () => {
  const kb1 = await createKnowledge(path, embedder);
  await kb1.addDocument({ name: "doc", content: "test" });
  await kb1.close();

  const kb2 = await createKnowledge(path, embedder);
  expect(await kb2.countDocuments()).toBe(1); // Real persistence!
});

// 2. Business logic that can fail
test("deduplicates by source URL (max 2 chunks)", async () => {
  // Tests actual deduplication logic, not just "it runs"
});

// 3. Error handling
test("handles errors gracefully", async () => {
  const mock = { retrieve: async () => { throw new Error("fail"); } };
  const result = await tool.execute({ query: "test" });
  expect(result.success).toBe(false); // Doesn't crash!
});

Bad Tests (Remove)

// 1. Testing hardcoded values
test("default model is gpt-4o-mini", () => {
  expect(config.model).toBe("gpt-4o-mini"); // So what? If it changes, is that a bug?
});

// 2. String matching on generated text
test("instructions contain 'agent'", () => {
  expect(instructions).toContain("agent"); // Superficial
});

// 3. Testing library behavior
test("LanceDB returns array", () => {
  expect(Array.isArray(results)).toBe(true); // Test your code, not theirs
});

Before Writing a Test, Ask

1. What bug would this catch? If none, skip it.
2. Is this testing MY code or a library? Only test your code.
3. If this fails, is it actually broken? Changing defaults isn't a bug.

Integration Tests

// Skip if dependencies unavailable
const hasOpenAIKey = !!process.env.OPENAI_API_KEY;

describe.skipIf(!hasOpenAIKey)("OpenAI Integration", () => {
  setDefaultTimeout(60_000); // API calls are slow
  // ...
});

Mocking

// Type-safe mocks
type MockKnowledge = Pick<EmbeddedKnowledge, "search">;

const mock: MockKnowledge = {
  search: async () => [{ name: "doc", content: "test", metadata: {} }],
};

// Cast safely
const retriever = new Retriever(mock as unknown as EmbeddedKnowledge);

Naming

// Describe WHAT it does, not HOW
test("deduplicates by source URL (max 2 chunks per URL)") // Good
test("filters results array with map and reduce")          // Bad

// Test files match source
// src/backends/embedded/* → tests/embedded.test.ts
// src/config/*           → tests/config.test.ts

Running Tests

bun test                          # All tests
bun test tests/embedded.test.ts   # Single file
bun test --watch                  # Watch mode