Create Test

Generate tests for existing code following project conventions.

Test File Layout

Tests live alongside the source file:

Variants (e.g., language-specific cases for a single tool) use a dotted suffix: documentationCoverage.languages.test.ts.

Framework: vitest (describe, it, expect, vi).

Workflow

1. Read the source file to understand what to test
2. Identify test cases:
   • Happy path scenarios
   • Edge cases (empty input, missing fields, large input)
   • Error handling (invalid args, file not found, parse errors)
   • Path-scoping behavior for tools that take a path parameter
3. Choose the right harness:
   • Tools (anything in src/tools/ that registers via register*Tool) → use getToolHandler + parseContent from src/testUtils/toolTestHarness.ts; parseContent reads the JSON text block, and firstItem returns the first element of a list or fails the test when it is empty (needed under noUncheckedIndexedAccess)
   • Schema or roots behavior through a real client → extend src/server.outputSchema.test.ts or src/server.roots.test.ts
   • Helpers / lib / utils → import the function directly
4. Create test file following the patterns below

5. Run tests with the smallest scope:

   npx vitest run src/tools/<name>.test.ts

Patterns

Tool Test (uses MCP harness)

Setup (temp dir, handler, beforeAll/afterAll) lives at module top level; describe blocks only group the it cases. Import vi only when the test mocks something.

import { mkdir, rm, writeFile, realpath } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { describe, it, expect, beforeAll, afterAll } from "vitest";
import { getToolHandler, parseContent } from "../testUtils/toolTestHarness.js";
import type { MyToolResult } from "../types/index.js";
import { registerMyTool } from "./myTool.js";

let testDir: string;
const handler = getToolHandler(registerMyTool, "my_tool");

beforeAll(async () => {
  const tempPath = join(tmpdir(), `scopewalker-myTool-${String(Date.now())}`);
  await mkdir(tempPath, { recursive: true });
  testDir = await realpath(tempPath);

  await writeFile(join(testDir, "sample.ts"), `export const x = 1;\n`);
});

afterAll(async () => {
  await rm(testDir, { recursive: true, force: true });
});

describe("myTool", () => {
  it("returns expected result for a valid path", async () => {
    const response = await handler({ path: testDir });
    const result = parseContent<MyToolResult>(response);

    expect(result.files).toHaveLength(1);
  });

  it("returns an error for a path outside allowed roots", async () => {
    const response = await handler({ path: "/etc" });

    expect(response.isError).toBe(true);
  });
});

Helper / Pure-Function Test

import { describe, it, expect } from "vitest";
import { myHelper } from "./myHelpers.js";

describe("myHelper", () => {
  it("returns the expected value", () => {
    expect(myHelper("input")).toBe("output");
  });

  it("handles empty input", () => {
    expect(myHelper("")).toBe("");
  });
});

Conventions

• ESM imports: always include the .js extension (the project is "type": "module")
• Use vi.mock() to stub external dependencies (../lib/tokei.js, filesystem boundaries)
• Use a unique temp directory per test file (tmpdir() + Date.now(), created in beforeAll) and resolve it with realpath to avoid macOS /private/var vs /var symlink issues
• Test the public behavior of a module, not its internals
• Cover both success and error paths for every tool

After the targeted test run, run npm run check to verify lint/types. Apply the test-change checks in docs/code-quality.md, including size limits on test files and suite callbacks. Fix violations and rescan; split tests by behavior when needed, without weakening assertions or hiding files from the scan.