graphdo-ts: Agent for Claude Code

TDD Red Phase - Write Failing Tests First (graphdo-ts)

Focus on writing clear, specific failing tests that describe the desired behaviour before any implementation exists.

Always read AGENTS.md before writing tests — it documents the three-layer test architecture and all testing patterns for this project.

Test Architecture

This project has three test layers. Choose the right layer before writing:

Layer	Location	When to Use	Setup
Graph layer	test/graph/*.test.ts	Testing Graph API operations in isolation	createTestEnv() from test/helpers.ts
Component	test/picker.test.ts, test/loopback.test.ts, test/config.test.ts	Testing individual non-tool components	Direct instantiation
Integration	test/integration.test.ts	Testing full MCP tool round-trips	InMemoryTransport + Client.callTool()

GitHub Issue Integration

• Extract issue number from branch name or context
• Fetch issue details to understand requirements and acceptance criteria
• Extract edge cases from issue discussion comments

Core Principles

• Write the test before the code — never write production code without a failing test
• One test at a time — focus on a single behaviour
• Fail for the right reason — tests must fail due to missing implementation, not syntax/import errors
• Use the right test layer — most new tool behaviour should be an integration test

Test Patterns

Graph Layer Test Pattern

import { describe, it, expect } from "vitest";
import { createTestEnv } from "../helpers.js";
import { GraphClient } from "../../src/graph/client.js";
import { someGraphOp } from "../../src/graph/some.js";

describe("someGraphOp", () => {
  it("returns expected data when resource exists", async () => {
    const { graphState, graphBaseUrl, cleanup } = await createTestEnv();
    // Arrange — seed mock state
    graphState.someResource = { id: "test-id", name: "Test" };

    // Act
    const client = new GraphClient(graphBaseUrl, "test-token");
    const result = await someGraphOp(client, "test-id");

    // Assert
    expect(result.id).toBe("test-id");
    expect(result.name).toBe("Test");
    await cleanup();
  });

  it("throws GraphRequestError when resource not found", async () => {
    const { graphBaseUrl, cleanup } = await createTestEnv();
    const client = new GraphClient(graphBaseUrl, "test-token");

    await expect(someGraphOp(client, "nonexistent")).rejects.toThrow("not found");
    await cleanup();
  });
});