agentic-dev/docs/guides/tdd-workflow.md

TDD Workflow

TDD in this monorepo is not dogma — it is a feedback mechanism. Writing a test first forces you to design the interface before the implementation, surface integration issues early, and guarantee that every line of production code is covered by an intentional assertion. The cycle keeps each increment small: one failing test, the minimal code to pass it, a clean refactor. Nothing more.

---

1. The Red-Green-Refactor Cycle

Worked example: getArticleBySlug

Step 1 — Write the failing test (RED)

packages/blog/src/application/repositories/articles-repository.interface.ts defines the getArticleBySlug(slug: string): Promise<Article | undefined> method. Before implementing anything, write a test that calls it through the use case or controller.

// packages/blog/src/interface-adapters/controllers/articles.controller.test.ts
import { beforeEach, describe, expect, it } from "vitest";
import { blogContainer } from "../../di/container";
import { BLOG_SYMBOLS } from "../../di/symbols";
import { MockArticlesRepository } from "../../infrastructure/repositories/mock-articles.repository";
import type { IArticlesRepository } from "../../application/repositories/articles-repository.interface";
import { articleFactory } from "../../__factories__/article.factory";
import { getArticleBySlugController } from "./articles.controller";

describe("getArticleBySlugController", () => {
  let repo: MockArticlesRepository;

  beforeEach(() => {
    if (blogContainer.isBound(BLOG_SYMBOLS.IArticlesRepository)) {
      blogContainer.unbind(BLOG_SYMBOLS.IArticlesRepository);
    }
    repo = new MockArticlesRepository();
    blogContainer
      .bind<IArticlesRepository>(BLOG_SYMBOLS.IArticlesRepository)
      .toConstantValue(repo);
    articleFactory.reset();
  });

  it("returns the article when the slug exists", async () => {
    await repo.createArticle(
      articleFactory.build({ slug: "hello-world", authorId: "u1" }),
    );
    const result = await getArticleBySlugController({ slug: "hello-world" });
    expect(result?.slug).toBe("hello-world");
  });

  it("returns undefined for a missing slug", async () => {
    const result = await getArticleBySlugController({ slug: "no-such-slug" });
    expect(result).toBeUndefined();
  });
});

Run it — confirm RED:

pnpm test --filter @repo/blog -- articles.controller.test.ts

 FAIL  src/interface-adapters/controllers/articles.controller.test.ts
  getArticleBySlugController
    × returns the article when the slug exists
      AssertionError: expected undefined to equal "hello-world"

Step 2 — Write the minimal implementation (GREEN)

// packages/blog/src/interface-adapters/controllers/articles.controller.ts
export async function getArticleBySlugController(input: {
  slug: string;
}): Promise<Article | undefined> {
  const parsed = getBySlugInputSchema.safeParse(input);
  if (!parsed.success) {
    throw new InputParseError("Invalid get-article-by-slug input", {
      cause: parsed.error,
    });
  }
  const repo = blogContainer.get<IArticlesRepository>(
    BLOG_SYMBOLS.IArticlesRepository,
  );
  return repo.getArticleBySlug(parsed.data.slug);
}

Run again — confirm GREEN:

pnpm test --filter @repo/blog -- articles.controller.test.ts

 PASS  src/interface-adapters/controllers/articles.controller.test.ts
  getArticleBySlugController
    ✓ returns the article when the slug exists
    ✓ returns undefined for a missing slug

Step 3 — Refactor

Extract the schema parse + error throw into a helper if the same pattern appears in three controllers:

function parseOrThrow<T>(schema: z.ZodSchema<T>, raw: unknown, msg: string): T {
  const parsed = schema.safeParse(raw);
  if (!parsed.success) throw new InputParseError(msg, { cause: parsed.error });
  return parsed.data;
}

Re-run tests — still GREEN. Commit.

---

2. Test Naming

Every test file follows these conventions:

describe(<SubjectUnderTest>)
  it("<does X> when <condition Y>")

Three examples:

// Entity validation
describe("articleSchema", () => {
  it("accepts a minimal valid article with default status", () => { ... });
  it("rejects empty title", () => { ... });
  it("rejects title over 255 chars", () => { ... });
});

// Use case
describe("getArticlesUseCase", () => {
  it("returns all articles with no filters", async () => { ... });
  it("filters by status when status is provided", async () => { ... });
});

// Controller
describe("articles controller", () => {
  describe("createArticleController", () => {
    it("creates an article on valid input", async () => { ... });
    it("throws InputParseError on missing title", async () => { ... });
  });
});

Rules:

• describe names the class or function under test — not the file.
• it uses active voice: returns, throws, filters, creates.
• Conditions go after when: it("returns undefined when slug is missing").
• No should — it adds words without meaning.

---

3. Arrange / Act / Assert (AAA)

Every test body has three clearly separated sections. No logic between Act and Assert.

Example 1 — use case test:

it("filters by status when status is provided", async () => {
  // Arrange
  await repo.createArticle(articleFactory.build({ status: "draft" }));
  await repo.createArticle(articleFactory.build({ status: "published" }));

  // Act
  const result = await getArticlesUseCase({ status: "published" });

  // Assert
  expect(result).toHaveLength(1);
  expect(result[0]?.status).toBe("published");
});

Example 2 — React component test:

it("renders the article title when data loads", async () => {
  // Arrange
  const article = articleFactory.build({ title: "My Post" });
  const screen = renderWithProviders(<ArticleCard article={article} />);

  // Act
  // (render is the act; no user interaction needed here)

  // Assert
  expect(screen.getByText("My Post")).toBeInTheDocument();
});

Keep Arrange lean — use factories, not hand-rolled objects. Keep Assert specific — test exactly what the step under test owns, not downstream effects.

---

4. When to Mock — Decision Tree

Is it a pure function (entity validation, slug generation)?
  → No mock. Pass inputs, assert output.

Is it a use case test?
  → Rebind the repository at DI level using blogContainer.unbind / .bind.
  → Use MockArticlesRepository, not a vi.fn() spy.

Is it a repository test (Payload implementation)?
  → vi.mock('payload') at the top of the file.
  → Provide a stub via stubPayloadConfig from @repo/core-testing/payload.
  → Run the contract suite to prove correctness.

Is it a React component that fetches data?
  → renderWithProviders from @repo/core-testing/react with tRPC mocks.
  → Do not mock fetch or XMLHttpRequest directly.

Is it a route handler / tRPC procedure?
  → Mock at the boundary only (the repository). Call the procedure through
    blogRouter.createCaller({}) — do not mock the router internals.

The rule: mock the thing your layer depends on, never the thing under test.

---

5. Test Pyramid for This Monorepo

Layer	Tool	Target ratio	Location pattern
Entity (schema, type guards)	Vitest	Highest — every entity	src/entities/*.test.ts
Use case (business logic)	Vitest + mock repo	High — every use case	src/application/use-cases/*.test.ts
Controller (input parsing)	Vitest + mock repo	High — every controller	src/interface-adapters/controllers/*.test.ts
Repository contract	Vitest + contract suite	One per impl	src/infrastructure/repositories/*.test.ts
Feature integration (tRPC)	Vitest + createCaller	Medium — happy path + error	src/integrations/api/router.test.ts
Component	Vitest + RTL	Per UI component	src/ui/**/*.test.tsx
E2E	Playwright	Few — smoke + critical flows	apps/web-next/e2e/*.spec.ts

Entities and use cases have the highest ratio because they encode business rules. E2E tests have the lowest ratio because they are slow and test the full stack.

---

6. What NOT to Test

• Plain getters/setters — if a function only returns this.field, the test adds no signal.
• Framework code — do not test that Next.js routes requests correctly; test the handler that Next.js calls.
• Third-party libraries — do not test that Zod parses a z.string() correctly; test that your schema rejects your domain-specific invalid inputs.
• Types-only modules — a file containing only export type Foo = ... cannot have runtime behavior; skip it.
• Generated code — Payload-generated types in node_modules/.payload/, migration files; these are not your code.
• console.log calls — test observable output, not side-channel logging.
• Private implementation details — if refactoring internals breaks a test without breaking any observable behavior, the test was testing the wrong thing.

---

7. Coverage Targets

Scope	Statements	Branches	Functions	Lines
Baseline (all packages)	80%	75%	80%	80%
Entities	100%	100%	100%	100%
Use cases	100%	100%	100%	100%
Controllers	100%	100%	100%	100%
Infrastructure (repos)	80%	75%	80%	80%

Inspect coverage locally:

pnpm test --coverage --filter @repo/blog

HTML report lands at packages/blog/coverage/index.html — open it in a browser to see uncovered branches highlighted in red.

To run coverage across all packages:

pnpm test -- --coverage

Coverage thresholds are enforced in packages/core-typescript/vitest.base.ts and inherited by every package's vitest.config.ts via nodeVitestConfig / jsdomVitestConfig.

---

8. Factory Usage

When to use factory.build()

Use articleFactory.build() (from packages/blog/src/__factories__/article.factory.ts) whenever you need a valid Article in a test and you do not care about specific field values. Override only what the test assertion depends on:

// Good — only override what the test cares about
articleFactory.build({ slug: "my-slug", status: "published" })

// Avoid — hand-crafting the full object obscures intent
{
  id: "abc",
  title: "Article 1",
  slug: "my-slug",
  content: null,
  status: "published",
  authorId: "user-1",
  createdAt: new Date("2026-01-01T00:00:00Z"),
  updatedAt: new Date("2026-01-01T00:00:00Z"),
}

Always call factory.reset() in beforeEach to restart the sequence counter.

When to hand-craft

Hand-craft objects only when testing boundary values (empty string, max-length title, null content) where the exact shape matters more than the valid-object semantics a factory provides.

Adding a new factory

1. Create packages/<feature>/src/__factories__/<entity>.factory.ts:

import { defineFactory } from "@repo/core-testing/factory";
import type { Comment } from "../entities/comment.js";

export const commentFactory = defineFactory<Comment>(({ sequence }) => ({
  id: `comment-${sequence}`,
  articleId: "article-1",
  body: `Comment body ${sequence}`,
  authorId: "user-1",
  createdAt: new Date("2026-01-01T00:00:00Z"),
}));

2. Re-export from packages/<feature>/src/__factories__/index.ts.
3. Call commentFactory.reset() in every beforeEach that uses it.

The defineFactory function lives in packages/core-testing/src/factory/define-factory.ts.

---

9. Contract Suite Usage

A contract suite asserts that every implementation of a repository interface satisfies the same behavioral contract. The suite runs once per implementation; the implementation is supplied via buildSubject.

How to add a contract suite for a new repository

1. Define the contract in packages/<feature>/src/__contracts__/<entity>-repository.contract.ts:

import { it, expect, beforeEach } from "vitest";
import { defineContractSuite } from "@repo/core-testing/contract";
import type { ICommentsRepository } from "../application/repositories/comments-repository.interface.js";
import { commentFactory } from "../__factories__/comment.factory.js";

export const commentsRepositoryContract =
  defineContractSuite<ICommentsRepository>(
    "ICommentsRepository",
    ({ buildSubject }) => {
      let repo: ICommentsRepository;

      beforeEach(async () => {
        commentFactory.reset();
        repo = await buildSubject();
      });

      it("createComment returns a comment with the correct fields", async () => {
        const seed = commentFactory.build({ body: "Hello" });
        const created = await repo.createComment(seed);
        expect(typeof created.id).toBe("string");
        expect(created.body).toBe("Hello");
      });
    },
  );

2. Run the contract against the mock implementation:

// packages/<feature>/src/infrastructure/repositories/mock-comments.repository.test.ts
import { describe } from "vitest";
import { commentsRepositoryContract } from "@/__contracts__/comments-repository.contract";
import { MockCommentsRepository } from "./mock-comments.repository";

describe("MockCommentsRepository", () => {
  commentsRepositoryContract.run(async () => new MockCommentsRepository());
});

3. Run the contract against the Payload implementation (with vi.mock('payload')):

// packages/<feature>/src/infrastructure/repositories/payload-comments.repository.test.ts
import { describe, vi } from "vitest";
import { commentsRepositoryContract } from "@/__contracts__/comments-repository.contract";
import { PayloadCommentsRepository } from "./payload-comments.repository";
import { stubPayloadConfig } from "@repo/core-testing/payload";

vi.mock("payload", () => ({ getPayload: vi.fn() }));

describe("PayloadCommentsRepository", () => {
  commentsRepositoryContract.run(async () => {
    const { getPayload } = await import("payload");
    (getPayload as ReturnType<typeof vi.fn>).mockResolvedValue(buildStub());
    return new PayloadCommentsRepository(stubPayloadConfig);
  });
});

4. Run tests. Fix until green. Both implementations now share the same contract.

The buildSubject pattern is the key: each run() call provides a fresh instance, so every contract it() starts with a clean repository.

---

10. Running Tests

Watch mode (recommended during development):

pnpm test --watch --filter @repo/blog

Vitest re-runs only the affected files on save. Use this instead of manual re-runs.

Focus a single test:

it.only("returns undefined for a missing slug", async () => { ... });

Run the file directly:

pnpm test --filter @repo/blog -- articles.controller.test.ts

Debug a failing test:

Add console.log inline, or launch with the Vitest inspector:

pnpm test --filter @repo/blog -- --reporter=verbose

For node-level debugging:

node --inspect-brk node_modules/.bin/vitest run src/interface-adapters/controllers/articles.controller.test.ts

Then attach Chrome DevTools at chrome://inspect.

Coverage:

pnpm test --coverage --filter @repo/blog
# HTML report: packages/blog/coverage/index.html

pnpm test -- --coverage
# HTML reports: packages/*/coverage/index.html

Storybook smoke tests:

pnpm test:stories

Requires Storybook running on port 6006. Start it first: pnpm dev --filter @repo/storybook.

Playwright e2e:

pnpm test:e2e                    # headless
pnpm test:e2e -- --ui            # interactive UI mode
pnpm test:e2e -- --headed        # visible browser

E2E tests live in apps/web-next/e2e/. The webServer block in apps/web-next/playwright.config.ts starts the dev server automatically.