# 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 `getArticleBySlug(slug: string): Promise<Article | undefined>`. Before implementing anything, write a controller test that constructs the dependencies directly — no container rebinding.

```typescript
// packages/blog/src/interface-adapters/controllers/get-article-by-slug.controller.test.ts
import { describe, expect, it } from "vitest";
import { getArticleBySlugController } from "@/interface-adapters/controllers/get-article-by-slug.controller";
import { getArticleBySlugUseCase } from "@/application/use-cases/get-article-by-slug.use-case";
import { MockArticlesRepository } from "@/infrastructure/repositories/articles.repository.mock";
import { articleFactory } from "@/__factories__/article.factory";

describe("getArticleBySlugController", () => {
  it("returns the article when the slug exists", async () => {
    const repo = new MockArticlesRepository();
    articleFactory.reset();
    await repo.createArticle(
      articleFactory.build({ slug: "hello-world", authorId: "u1" }),
    );

    const useCase = getArticleBySlugUseCase(repo);
    const controller = getArticleBySlugController(useCase);

    const result = await controller({ slug: "hello-world" });
    expect(result?.slug).toBe("hello-world");
  });

  it("throws ArticleNotFoundError for a missing slug", async () => {
    const repo = new MockArticlesRepository();
    const useCase = getArticleBySlugUseCase(repo);
    const controller = getArticleBySlugController(useCase);

    await expect(controller({ slug: "no-such-slug" })).rejects.toBeInstanceOf(
      ArticleNotFoundError,
    );
  });
});
```

**Run it — confirm RED:**

```
pnpm test --filter @repo/blog -- get-article-by-slug.controller.test.ts

 FAIL  src/interface-adapters/controllers/get-article-by-slug.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)**

```typescript
// packages/blog/src/interface-adapters/controllers/get-article-by-slug.controller.ts
import type {
  IGetArticleBySlugUseCase,
  GetArticleBySlugOutput,
} from "../application/use-cases/get-article-by-slug.use-case";
import { getArticleBySlugInputSchema } from "../application/use-cases/get-article-by-slug.use-case";
import { InputParseError } from "../entities/errors/common";

function presenter(value: GetArticleBySlugOutput) {
  return value;
}

export function getArticleBySlugController(useCase: IGetArticleBySlugUseCase) {
  return async (input: unknown): Promise<ReturnType<typeof presenter>> => {
    const parsed = getArticleBySlugInputSchema.safeParse(input);
    if (!parsed.success)
      throw new InputParseError("Invalid get-article-by-slug input", {
        cause: parsed.error,
      });
    return presenter(await useCase(parsed.data));
  };
}

export type IGetArticleBySlugController = ReturnType<
  typeof getArticleBySlugController
>;
```

**Run again — confirm GREEN:**

```
pnpm test --filter @repo/blog -- get-article-by-slug.controller.test.ts

 PASS  src/interface-adapters/controllers/get-article-by-slug.controller.test.ts
  getArticleBySlugController
    ✓ returns the article when the slug exists
    ✓ throws ArticleNotFoundError for a missing slug
```

**Step 3 — Refactor**

If the same `safeParse` + `InputParseError` throw pattern appears in multiple controllers, extract a shared `parseOrThrow` helper:

```typescript
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:**

```typescript
// 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("getArticleBySlugController", () => {
  it("returns the article when the slug exists", async () => { ... });
  it("throws ArticleNotFoundError for a missing slug", async () => { ... });
  it("throws InputParseError on invalid input shape", 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:**

```typescript
it("filters by status when status is provided", async () => {
  // Arrange
  const repo = new MockArticlesRepository();
  articleFactory.reset();
  await repo.createArticle(articleFactory.build({ status: "draft" }));
  await repo.createArticle(articleFactory.build({ status: "published" }));
  const useCase = getArticlesUseCase(repo);

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

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

**Example 2 — React component test:**

```typescript
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?
  → Construct new MockXRepository() and inject directly into the factory:
      const repo = new MockXRepository();
      const useCase = xUseCase(repo);
      await useCase(input);
  → No container unbind/rebind.

Is it a controller test?
  → Construct the mock repo, build the use case, inject into the controller factory:
      const repo = new MockXRepository();
      const useCase = xUseCase(repo);
      const controller = xController(useCase);
      await controller(input);

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?
  → Use blogContainer / xContainer with unbindAll + load(XModule) in
    beforeEach/afterEach. Call the procedure through xRouter.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/models/*.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:**

```bash
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:

```bash
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:

```typescript
// 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` (or inline before use) 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`:

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

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` (or inline) that uses it.

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

---

## 9. Output Validation Tests

Every **non-void** use case must have an output-validation test that injects a malformed mock response and asserts the use case throws `ZodError`. This verifies that the `xOutputSchema.parse(result)` at the end of each use case actually guards against misbehaving repositories.

**Void use cases are exempt:** `signOutUseCase`, `deleteMediaUseCase`, and any future use case returning `Promise<void>` — they have no output schema.

**Pattern A — reach into `_articles` (or equivalent backing array) when the typed API prevents you from inserting bad data:**

```typescript
// packages/blog/src/application/use-cases/get-articles.use-case.test.ts
import { ZodError } from "zod";
import {
  getArticlesUseCase,
  getArticlesOutputSchema,
} from "@/application/use-cases/get-articles.use-case";
import { MockArticlesRepository } from "@/infrastructure/repositories/articles.repository.mock";

describe("getArticlesUseCase output validation", () => {
  it("throws when the repository returns a malformed article", async () => {
    const repo = new MockArticlesRepository();
    // bypass typed createArticle by reaching into the backing array directly
    (repo as unknown as { _articles: unknown[] })._articles.push({ id: 123 });

    const useCase = getArticlesUseCase(repo);
    await expect(useCase({})).rejects.toBeInstanceOf(ZodError);
  });

  it("exports an output schema that mirrors Article[]", () => {
    expect(getArticlesOutputSchema).toBeDefined();
    expect(getArticlesOutputSchema.safeParse([]).success).toBe(true);
  });
});
```

**Pattern B — inline stub when pattern A is impractical (service layer or complex dependency):**

```typescript
// packages/auth/src/application/use-cases/sign-in.use-case.test.ts
import type { IAuthenticationService } from "@/application/services/authentication.service.interface";

describe("signInUseCase output validation", () => {
  it("throws when authenticationService returns a malformed session", async () => {
    const users = new MockUsersRepository([]);
    await users.createUser(userFactory.build({ username: "alice" }));

    const auth = {
      verifyPassword: async () => true,
      createSession: async () => ({ session: { id: 123 }, cookie: null }),
    } as unknown as IAuthenticationService;

    const useCase = signInUseCase(users, auth);
    await expect(
      useCase({ username: "alice", password: "x" }),
    ).rejects.toBeInstanceOf(ZodError);
  });
});
```

Group output-validation tests in a separate `describe` block labelled `"<useCase> output validation"` so they are easy to grep.

---

## 10. Router Error-Mapping Tests

Each feature's `router.test.ts` must assert that thrown domain errors become `TRPCError` with the correct code. The router test uses `xRouter.createCaller({})` and calls real procedures backed by the default mock bindings.

The `beforeEach` / `afterEach` blocks reload the DI module so each test gets a fresh mock repository:

```typescript
// packages/blog/src/integrations/api/router.test.ts
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import { TRPCError } from "@trpc/server";
import { blogContainer } from "@/di/container";
import { BlogModule } from "@/di/module";
import { blogRouter } from "@/integrations/api/router";

describe("blogRouter error mapping", () => {
  beforeEach(() => {
    blogContainer.unbindAll();
    blogContainer.load(BlogModule);
  });

  afterEach(() => {
    blogContainer.unbindAll();
  });

  it("translates ArticleNotFoundError → NOT_FOUND", async () => {
    const caller = blogRouter.createCaller({});
    try {
      await caller.articleBySlug({ slug: "missing" });
      throw new Error("expected throw");
    } catch (e) {
      expect(e).toBeInstanceOf(TRPCError);
      expect((e as TRPCError).code).toBe("NOT_FOUND");
    }
  });

  it("translates zod parse failure → BAD_REQUEST", async () => {
    const caller = blogRouter.createCaller({});
    try {
      await caller.articleBySlug({} as unknown as { slug: string });
      throw new Error("expected throw");
    } catch (e) {
      expect(e).toBeInstanceOf(TRPCError);
      expect((e as TRPCError).code).toBe("BAD_REQUEST");
    }
  });
});
```

For features where a domain error can only be triggered by an empty store (e.g. `navigation`'s `HeaderNotFoundError`), inline a `NullXRepository` and rebind the container:

```typescript
it("translates HeaderNotFoundError → NOT_FOUND", async () => {
  @injectable()
  class NullHeaderRepository implements IHeaderRepository {
    async getHeader() {
      return undefined;
    }
  }
  navigationContainer.unbind(NAVIGATION_SYMBOLS.IHeaderRepository);
  navigationContainer
    .bind(NAVIGATION_SYMBOLS.IHeaderRepository)
    .to(NullHeaderRepository);

  const caller = navigationRouter.createCaller({});
  try {
    await caller.header({});
    throw new Error("expected throw");
  } catch (e) {
    expect(e).toBeInstanceOf(TRPCError);
    expect((e as TRPCError).code).toBe("NOT_FOUND");
  }
});
```

Every feature needs at least one `NOT_FOUND` (or domain-error) test and one `BAD_REQUEST` (schema validation) test.

---

## 11. Presenter Shape Tests

When a controller's presenter **reshapes** the use-case output (rather than returning it unchanged), the controller test must assert the **view shape** — not the full use-case output.

**Example — auth `sign-in` (non-identity presenter):**

The `signInUseCase` returns `{ session, cookie }`. The presenter extracts `cookie` and returns it directly. The controller test must assert the cookie's shape:

```typescript
// packages/auth/src/interface-adapters/controllers/sign-in.controller.test.ts
describe("signInController", () => {
  it("returns a cookie on successful sign-in", async () => {
    const users = new MockUsersRepository([]);
    const auth = new MockAuthenticationService(users);
    await users.createUser(
      userFactory.build({
        username: "alice",
        passwordHash: "hashed_testpassword",
      }),
    );

    const useCase = signInUseCase(users, auth);
    const controller = signInController(useCase);

    const result = await controller({
      username: "alice",
      password: "testpassword",
    });
    // assert the VIEW shape (cookie), not the use-case output ({ session, cookie })
    expect(result.name).toBe("session");
    expect(result.value).toBeTruthy();
  });
});
```

**Identity presenters skip this.** Blog, marketing-pages, navigation, and media controllers all use identity presenters (`return value`). Their controller tests assert on the same fields the use case would return — that is fine, because the presenter does not transform.

**Rule of thumb:** if `presenter(value)` does anything other than `return value`, write a test that cannot pass by accident — assert a field that only exists on the _view_, not on `XOutput`.

Void controllers (`signOutController`, `deleteMediaController`) return `Promise<void>` and have no presenter — no view-shape test applies.

---

## 12. 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`:

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

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:

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

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

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

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

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

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

4. Run tests. Fix until green.

The `buildSubject` pattern ensures each `run()` call supplies a fresh instance — every contract `it()` starts with a clean repository.

**File naming convention (post-Plan-8):**

- Mock implementation: `<x>.repository.mock.ts` (not `mock-<x>.repository.ts`)
- Mock test: `<x>.repository.mock.test.ts`
- Real implementation: `<x>.repository.ts` (no `payload-` prefix)
- Interface: `<x>.repository.interface.ts`

---

## 13. Running Tests

**Watch mode (recommended during development):**

```bash
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:**

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

Run the file directly:

```bash
pnpm test --filter @repo/blog -- get-article-by-slug.controller.test.ts
```

**Debug a failing test:**

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

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

For node-level debugging:

```bash
node --inspect-brk node_modules/.bin/vitest run src/interface-adapters/controllers/get-article-by-slug.controller.test.ts
```

Then attach Chrome DevTools at `chrome://inspect`.

**Coverage:**

```bash
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:**

```bash
pnpm test:stories
```

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

**Playwright e2e:**

```bash
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.

---

## Asserting spans and captures

Use cases, controllers, and repositories emit OpenTelemetry-style spans through the `ITracer` interface. Repositories also call `logger.captureException` inline; use cases and controllers get capture composed in via `withCapture` at DI bind time. Tests that need to assert either inject `RecordingTracer` + `RecordingLogger`:

```ts
import {
  RecordingTracer,
  RecordingLogger,
} from "@repo/core-testing/instrumentation";
import { withSpan, withCapture } from "@repo/core-shared/instrumentation";
import { MockArticlesRepository } from "@/infrastructure/repositories/articles.repository.mock";
import { getArticlesUseCase } from "@/application/use-cases/get-articles.use-case";

describe("blog.getArticles use case", () => {
  it("emits a use-case span when invoked", async () => {
    const tracer = new RecordingTracer();
    const logger = new RecordingLogger();
    const repo = new MockArticlesRepository(tracer, logger);
    // Use cases are wrapped at DI bind time. For direct-injection tests,
    // mirror the binder's sandwich: withSpan(withCapture(factory(deps))).
    const wrapped = withSpan(
      tracer,
      { name: "blog.getArticles", op: "use-case" },
      withCapture(
        logger,
        { feature: "blog", layer: "use-case", name: "blog.getArticles" },
        getArticlesUseCase(repo),
      ),
    );
    await wrapped({ limit: 10 });
    expect(tracer.findSpan("blog.getArticles")?.op).toBe("use-case");
    expect(tracer.findSpan("articles.getArticles")?.op).toBe("repository");
  });
});
```

**Capture assertions** use `RecordingLogger`. Note: `RecordingLogger.captureException` honours the `__sentryReported` flag — so when a repo's catch block captures and the outer `withCapture` sees the bubbled error, only the inner-most call records:

```ts
const logger = new RecordingLogger();
const repo = new MockArticlesRepository(tracer, logger);
// Force an infra error in your test setup, then:
expect(logger.captures).toHaveLength(1); // exactly one — flag prevents double
expect(logger.captures[0]).toMatchObject({
  kind: "exception",
  ctx: { tags: { feature: "blog", repo: "articles", method: "getArticles" } },
});
```

For an end-to-end example (controller → use case → repo, all wrapped, asserting no double-capture across layers), see `packages/blog/tests/r44-no-double-capture.test.ts`.

**Default mocks** (when you don't need assertions): construct `new MockArticlesRepository()` with no args — the constructor defaults bind `NoopTracer` + `NoopLogger`.

---

## Conformance gates (post-TDD)

After your tests are green and the impl is committed, four gates check that the new code stays consistent with the feature's manifest:

1. **TypeScript brands** — the `ProductionUseCase<I, O, M>` slot in `bind-production.ts` only accepts factories wrapped through `withSpan` + `withCapture` + (if mutating with audits) `withAudit`.
2. **ESLint rules** — five `conformance/*` rules check manifest ↔ code drift; see `docs/guides/conformance-quickref.md`.
3. **Boot assertion** — `assertFeatureConformance` runs at the tail of every `bindProductionX(ctx)`; `pnpm dev` refuses to start on drift.
4. **CI drift gate** — `pnpm conformance` runs after `pnpm lint` in CI; fails on orphan event consumers across features.

The TDD red-green cycle covers behavioural correctness; the conformance gates cover architectural correctness.