pr-narrator-mcp testing.instructions.md

Test File Review Rules

Mock Setup (Critical Ordering)

• vi.mock() calls MUST appear before any imports from the mocked module
• This is a Vitest hoisting requirement — violations cause tests to use real implementations

// Correct: vi.mock BEFORE imports
vi.mock("../../src/utils/git.js", () => ({
  getCurrentBranch: vi.fn(),
  getStagedChanges: vi.fn(),
  getGitInfo: vi.fn(),
  getBranchChanges: vi.fn(),
  getWorkingTreeStatus: vi.fn(),
  extractTicketFromBranch: vi.fn(),
  extractBranchPrefix: vi.fn(),
  extractTicketsFromCommits: vi.fn(),
}));

// THEN import the module under test and mocked modules
import { analyzeGitChanges } from "../../src/tools/analyze-git-changes.js";
import {
  getCurrentBranch,
  getStagedChanges,
  getWorkingTreeStatus,
} from "../../src/utils/git.js";

// Wrong: import before mock — mock is ignored
import { getCurrentBranch } from "../../src/utils/git.js";
vi.mock("../../src/utils/git.js", () => ({ ... }));  // Too late!

Mock Completeness

• Each tool test file must mock ALL git.ts functions used by that tool
• Missing mocks cause real git operations against the developer's repo
• Use vi.mocked(fn) for type-safe mock access — never use as jest.Mock or similar casts

// Correct
vi.mocked(getCurrentBranch).mockResolvedValue("feature/PROJ-123-add-login");

// Avoid
(getCurrentBranch as any).mockResolvedValue("feature/PROJ-123-add-login");

Mock Return Values

• Mock return values must match the actual interface exactly
• Do not skip required fields — this hides integration bugs
• For complex interfaces, define reusable fixtures

// Good: all required fields present
vi.mocked(getWorkingTreeStatus).mockResolvedValue({
  modified: [],
  untracked: [],
  deleted: [],
  modifiedCount: 0,
  untrackedCount: 0,
  deletedCount: 0,
  totalUncommitted: 0,
});

// Bad: missing required fields
vi.mocked(getWorkingTreeStatus).mockResolvedValue({
  modified: [],
});

Test Lifecycle