fraqtal/agentic-dev
Template
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

refactor: strip Lazar references from top-level docs + guides

Browse Source
This commit is contained in:
Danijel Martinek
2026-05-13 09:57:19 +02:00
parent 17ae157365
commit 06da37f723
8 changed files with 271 additions and 189 deletions
Download Patch File Download Diff File Expand all files Collapse all files

177
docs/guides/adding-a-feature.md
View File

@@ -5,7 +5,7 @@ tRPC router, CMS collection, DI container, and query builders — all owned
by one package under `packages/<feature>/`.
> **Prefer the generator.** `pnpm turbo gen feature` produces a
> Lazar-conformant single-entity / single-use-case package matching the
> A single-entity / single-use-case package matching the
> `navigation` reference shape (DI, tRPC router with tests, span + capture
> sandwich, dev seed, contract suite). See
> [Scaffolding a Feature](./scaffolding-a-feature.md). Use this guide when
@@ -44,20 +44,20 @@ For the fast path, run `pnpm turbo gen feature <name>` — the generator emits t
Every feature package owns:
| Layer | What lives there |
|---|---|
| `entities/models/` | Zod schemas + inferred TypeScript types |
| `entities/errors/` | Domain error classes (`this.name` required); `common.ts` for `InputParseError` |
| `application/repositories/` | Repository interface (no implementation) |
| `application/use-cases/` | One factory per operation; owns `xInputSchema`, `xOutputSchema`, and `xOutputSchema.parse()` |
| `infrastructure/repositories/` | Real (`<noun>.repository.ts`) and mock (`<noun>.repository.mock.ts`) siblings |
| `interface-adapters/controllers/` | One factory per use case; accepts `unknown`, calls `safeParse`, runs presenter |
| `di/` | `symbols.ts` + `module.ts` + `container.ts` + `bind-production.ts` |
| `integrations/api/` | `procedures.ts` (feature error map) + `router.ts` (uses `xProcedure.input(xInputSchema)`) |
| `integrations/cms/` | Payload collection/global configs |
| `ui/` | Query builders and future React components (behind `./ui` subpath) |
| `__factories__/` | Test data factories |
| `__contracts__/` | Contract suites shared by mock and real repository tests |
| Layer | What lives there |
| --------------------------------- | -------------------------------------------------------------------------------------------- |
| `entities/models/` | Zod schemas + inferred TypeScript types |
| `entities/errors/` | Domain error classes (`this.name` required); `common.ts` for `InputParseError` |
| `application/repositories/` | Repository interface (no implementation) |
| `application/use-cases/` | One factory per operation; owns `xInputSchema`, `xOutputSchema`, and `xOutputSchema.parse()` |
| `infrastructure/repositories/` | Real (`<noun>.repository.ts`) and mock (`<noun>.repository.mock.ts`) siblings |
| `interface-adapters/controllers/` | One factory per use case; accepts `unknown`, calls `safeParse`, runs presenter |
| `di/` | `symbols.ts` + `module.ts` + `container.ts` + `bind-production.ts` |
| `integrations/api/` | `procedures.ts` (feature error map) + `router.ts` (uses `xProcedure.input(xInputSchema)`) |
| `integrations/cms/` | Payload collection/global configs |
| `ui/` | Query builders and future React components (behind `./ui` subpath) |
| `__factories__/` | Test data factories |
| `__contracts__/` | Contract suites shared by mock and real repository tests |
The walkthrough below builds a minimal `comments` feature from scratch.
All concrete code mirrors the `blog` package (the most fully developed
@@ -108,7 +108,7 @@ packages/comments/
api/
procedures.ts # commentsProcedure with feature error map
router.ts # commentsProcedure.input(xInputSchema)
router.test.ts # includes R26 error-mapping assertions
router.test.ts # includes error-mapping assertions
index.ts
cms/
collections/
@@ -245,7 +245,13 @@ describe("commentSchema", () => {
it("rejects an empty body", () => {
expect(() =>
commentSchema.parse({ id: "c-1", articleId: "a-1", body: "", authorId: "u-1", createdAt: new Date() }),
commentSchema.parse({
id: "c-1",
articleId: "a-1",
body: "",
authorId: "u-1",
createdAt: new Date(),
}),
).toThrow();
});
});
@@ -285,7 +291,7 @@ pnpm test --filter @repo/comments -- comment.test.ts # GREEN
export class CommentNotFoundError extends Error {
constructor(message = "Comment not found", options?: ErrorOptions) {
super(message, options);
this.name = "CommentNotFoundError"; // required — R6
this.name = "CommentNotFoundError"; // required — R6
}
}
```
@@ -295,7 +301,7 @@ export class CommentNotFoundError extends Error {
export class InputParseError extends Error {
constructor(message: string, options?: ErrorOptions) {
super(message, options);
this.name = "InputParseError"; // required — R6
this.name = "InputParseError"; // required — R6
}
}
```
@@ -364,6 +370,7 @@ export const commentFactory = defineFactory<Comment>(({ sequence }) => ({
### Step 9: Use case — factory function with input/output schemas (RED → GREEN)
Every use case exports:
- `xInputSchema` — a `z.ZodObject` with `.strict()` (use `z.object({}).strict()` for void inputs)
- `xOutputSchema` — for non-void use cases
- `XInput` / `XOutput` types
@@ -404,14 +411,16 @@ describe("getCommentsUseCase", () => {
});
});
// R25 — output validation
describe("getCommentsUseCase output validation (R25)", () => {
// output validation
describe("getCommentsUseCase output validation", () => {
it("throws ZodError when the repository returns malformed data", async () => {
const repo = new MockCommentsRepository();
(repo as unknown as { _comments: unknown[] })._comments.push({ id: 123 });
const useCase = getCommentsUseCase(repo);
await expect(useCase({ articleId: "a-1" })).rejects.toBeInstanceOf(ZodError);
await expect(useCase({ articleId: "a-1" })).rejects.toBeInstanceOf(
ZodError,
);
});
it("exports getCommentsOutputSchema that validates Comment[]", () => {
@@ -448,7 +457,9 @@ export type IGetCommentsUseCase = ReturnType<typeof getCommentsUseCase>;
export const getCommentsUseCase =
(commentsRepository: ICommentsRepository) =>
async (input: GetCommentsInput): Promise<GetCommentsOutput> => {
const result = await commentsRepository.getCommentsForArticle(input.articleId);
const result = await commentsRepository.getCommentsForArticle(
input.articleId,
);
return getCommentsOutputSchema.parse(result);
};
```
@@ -586,7 +597,9 @@ describe("getCommentsController", () => {
it("throws InputParseError on unknown extra fields (strict)", async () => {
const repo = new MockCommentsRepository();
const ctrl = getCommentsController(getCommentsUseCase(repo));
await expect(ctrl({ articleId: "a-1", extra: true })).rejects.toBeInstanceOf(InputParseError);
await expect(
ctrl({ articleId: "a-1", extra: true }),
).rejects.toBeInstanceOf(InputParseError);
});
});
```
@@ -617,7 +630,9 @@ export const getCommentsController =
async (input: unknown): Promise<ReturnType<typeof presenter>> => {
const parsed = getCommentsInputSchema.safeParse(input);
if (!parsed.success) {
throw new InputParseError("Invalid get-comments input", { cause: parsed.error });
throw new InputParseError("Invalid get-comments input", {
cause: parsed.error,
});
}
const result = await getCommentsUseCase(parsed.data);
return presenter(result);
@@ -659,17 +674,27 @@ import {
import { COMMENTS_SYMBOLS } from "./symbols";
export const CommentsModule = new ContainerModule((bind: interfaces.Bind) => {
bind<ICommentsRepository>(COMMENTS_SYMBOLS.ICommentsRepository).to(MockCommentsRepository);
bind<ICommentsRepository>(COMMENTS_SYMBOLS.ICommentsRepository).to(
MockCommentsRepository,
);
bind<IGetCommentsUseCase>(COMMENTS_SYMBOLS.IGetCommentsUseCase).toDynamicValue((ctx) =>
bind<IGetCommentsUseCase>(
COMMENTS_SYMBOLS.IGetCommentsUseCase,
).toDynamicValue((ctx) =>
getCommentsUseCase(
ctx.container.get<ICommentsRepository>(COMMENTS_SYMBOLS.ICommentsRepository),
ctx.container.get<ICommentsRepository>(
COMMENTS_SYMBOLS.ICommentsRepository,
),
),
);
bind<IGetCommentsController>(COMMENTS_SYMBOLS.IGetCommentsController).toDynamicValue((ctx) =>
bind<IGetCommentsController>(
COMMENTS_SYMBOLS.IGetCommentsController,
).toDynamicValue((ctx) =>
getCommentsController(
ctx.container.get<IGetCommentsUseCase>(COMMENTS_SYMBOLS.IGetCommentsUseCase),
ctx.container.get<IGetCommentsUseCase>(
COMMENTS_SYMBOLS.IGetCommentsUseCase,
),
),
);
});
@@ -695,15 +720,21 @@ import { COMMENTS_SYMBOLS } from "@/di/symbols";
describe("commentsContainer", () => {
it("resolves ICommentsRepository", () => {
expect(commentsContainer.get(COMMENTS_SYMBOLS.ICommentsRepository)).toBeDefined();
expect(
commentsContainer.get(COMMENTS_SYMBOLS.ICommentsRepository),
).toBeDefined();
});
it("resolves IGetCommentsUseCase", () => {
expect(commentsContainer.get(COMMENTS_SYMBOLS.IGetCommentsUseCase)).toBeDefined();
expect(
commentsContainer.get(COMMENTS_SYMBOLS.IGetCommentsUseCase),
).toBeDefined();
});
it("resolves IGetCommentsController", () => {
expect(commentsContainer.get(COMMENTS_SYMBOLS.IGetCommentsController)).toBeDefined();
expect(
commentsContainer.get(COMMENTS_SYMBOLS.IGetCommentsController),
).toBeDefined();
});
});
```
@@ -733,9 +764,10 @@ export const commentsProcedure = t.procedure.use(
---
### Step 14: tRPC router (RED → GREEN, includes R26 error-mapping test)
### Step 14: tRPC router (RED → GREEN, includes error-mapping test)
The router:
- uses `commentsProcedure` (never bare `publicProcedure`)
- calls `.input(xInputSchema)` importing from the use-case file — never redefines the schema inline
- resolves controllers from the container
@@ -758,7 +790,9 @@ describe("commentsRouter", () => {
});
it("exposes getComments procedure", () => {
expect(Object.keys(commentsRouter._def.procedures)).toContain("getComments");
expect(Object.keys(commentsRouter._def.procedures)).toContain(
"getComments",
);
});
it("getComments returns empty array by default", async () => {
@@ -767,8 +801,8 @@ describe("commentsRouter", () => {
});
});
// R26 — error mapping
describe("commentsRouter (R26 error mapping)", () => {
// error mapping
describe("commentsRouter error mapping", () => {
beforeEach(() => {
commentsContainer.unbindAll();
commentsContainer.load(CommentsModule);
@@ -871,7 +905,11 @@ export class CommentsRepository implements ICommentsRepository {
async getComment(id: string): Promise<Comment | undefined> {
const payload = await getPayload({ config: this.config });
try {
const doc = await payload.findByID({ collection: "comments", id, overrideAccess: true });
const doc = await payload.findByID({
collection: "comments",
id,
overrideAccess: true,
});
return mapDoc(doc as PayloadCommentDoc);
} catch {
return undefined;
@@ -892,7 +930,11 @@ export class CommentsRepository implements ICommentsRepository {
const payload = await getPayload({ config: this.config });
const created = await payload.create({
collection: "comments",
data: { articleId: input.articleId, body: input.body, author: input.authorId } as never,
data: {
articleId: input.articleId,
body: input.body,
author: input.authorId,
} as never,
overrideAccess: true,
});
return mapDoc(created as PayloadCommentDoc);
@@ -917,13 +959,17 @@ describe("CommentsRepository", () => {
const store = new Map<string, Record<string, unknown>>();
const stub = {
findByID: vi.fn(async ({ id }: { id: string }) => store.get(id)),
find: vi.fn(async ({ where }: { where?: { articleId?: { equals: string } } }) => {
let docs = Array.from(store.values());
if (where?.articleId) {
docs = docs.filter((d) => d["articleId"] === where.articleId?.equals);
}
return { docs };
}),
find: vi.fn(
async ({ where }: { where?: { articleId?: { equals: string } } }) => {
let docs = Array.from(store.values());
if (where?.articleId) {
docs = docs.filter(
(d) => d["articleId"] === where.articleId?.equals,
);
}
return { docs };
},
),
create: vi.fn(async ({ data }: { data: Record<string, unknown> }) => {
const doc = { id: `stub-${store.size + 1}`, ...data };
store.set(String(doc.id), doc);
@@ -996,7 +1042,12 @@ export const comments: CollectionConfig = {
fields: [
{ name: "articleId", type: "text", required: true },
{ name: "body", type: "textarea", required: true },
{ name: "author", type: "relationship", relationTo: "users", required: true },
{
name: "author",
type: "relationship",
relationTo: "users",
required: true,
},
],
};
```
@@ -1089,7 +1140,9 @@ Add path aliases to `tsconfig.base.json`:
"@repo/comments/api": ["packages/comments/src/integrations/api/index.ts"],
"@repo/comments/ui": ["packages/comments/src/ui/index.ts"],
"@repo/comments/cms": ["packages/comments/src/integrations/cms/index.ts"],
"@repo/comments/di/bind-production": ["packages/comments/src/di/bind-production.ts"]
"@repo/comments/di/bind-production": [
"packages/comments/src/di/bind-production.ts"
]
}
}
}
@@ -1131,14 +1184,14 @@ All must pass before shipping.
## 4. Configuration Checklist
| File | Key items |
|---|---|
| `package.json` | `"type": "module"`; exports map with `.`, `./ui`, `./api`, `./cms`, `./di/bind-production`; `@repo/core-shared`, `inversify`, `zod`, `payload` in deps |
| `tsconfig.json` | `"rootDir": "."` (covers both `src/` and `tests/`); `"outDir": "dist"` |
| `vitest.config.ts` | `resolve.alias: { "@": path.resolve(__dirname, "./src") }` |
| `eslint.config.js` | extends `@repo/core-eslint`; tag set to `"feature"` in Turborepo `turbo.json` |
| `tsconfig.base.json` | path aliases for every subpath export |
| `turbo.json` | feature package must appear (or be glob-matched) in the workspace graph |
| File | Key items |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `package.json` | `"type": "module"`; exports map with `.`, `./ui`, `./api`, `./cms`, `./di/bind-production`; `@repo/core-shared`, `inversify`, `zod`, `payload` in deps |
| `tsconfig.json` | `"rootDir": "."` (covers both `src/` and `tests/`); `"outDir": "dist"` |
| `vitest.config.ts` | `resolve.alias: { "@": path.resolve(__dirname, "./src") }` |
| `eslint.config.js` | extends `@repo/core-eslint`; tag set to `"feature"` in Turborepo `turbo.json` |
| `tsconfig.base.json` | path aliases for every subpath export |
| `turbo.json` | feature package must appear (or be glob-matched) in the workspace graph |
---
@@ -1168,7 +1221,7 @@ All must pass before shipping.
`Promise<ReturnType<typeof presenter>>`. Identity (`return value`) is
fine, but the function must exist. Skipping it makes adding a view
transform later a structural change instead of a one-line edit
(ADR-013 R11).
(ADR-013).
5. **Adding feature error classes to `core-shared`.** `core-shared` must
stay boundary-clean — it provides `defineErrorMiddleware` but knows
@@ -1194,22 +1247,16 @@ All must pass before shipping.
## 6. Cross-References
- **ADR-012** (`docs/decisions/adr-012-lazar-conformance.md`) — factory-function
- **ADR-012** (`docs/decisions/adr-012-feature-conventions.md`) — factory-function
use cases and controllers, entity layout, file naming, one-controller-per-use-case,
`.toDynamicValue()` DI bindings, direct injection in tests.
- **ADR-013** (`docs/decisions/adr-013-input-output-unification.md`) — use-case
file as single source for `xInputSchema` + `xOutputSchema`; presenter pattern;
per-feature `procedures.ts` error map; public surface split (`./` vs `./ui`).
- **Refactor log — Plan 8** (`docs/superpowers/refactor-logs/2026-05-05-lazar-pattern-conformance.md`) —
file-by-file inventory of every rename, split, and pattern change applied
to all existing features.
- **Refactor log — Plan 9** (`docs/superpowers/refactor-logs/2026-05-06-input-output-unification.md`) —
inventory of schema additions, presenter additions, `procedures.ts` additions,
and `./ui` subpath additions across all 5 features.
- **CLAUDE.md** (root) — Key Conventions section is the quick-reference
summary; this guide is the authoritative walkthrough.
- **Architecture overview** (`docs/architecture/overview.md`) — canonical
data-flow diagram showing the full request path from React component
through tRPC, controller, use case, repository, and back.
- **TDD Workflow** (`docs/guides/tdd-workflow.md`) — required reading on
RED → GREEN discipline, direct factory injection, and R25/R26 test obligations.
RED → GREEN discipline, direct factory injection, and test obligations per layer.

2
docs/guides/runbook.md
View File

@@ -165,7 +165,7 @@ This emits:
- `packages/<name>/src/feature.manifest.ts` — the conformance manifest (use cases, audits, publishes, consumes)
- `packages/<name>/src/di/bind-production.ts` with `assertFeatureConformance(...)` at the tail (refuses to boot on drift)
- Mock repository, factory, seed, entity, use-case, controller, tests — full Lazar-conformant shape
- Mock repository, factory, seed, entity, use-case, controller, tests — full canonical shape
- `packages/<name>/src/index.ts` exports
After scaffolding, the four-step ordering for any new use case:

18
docs/guides/scaffolding-a-feature.md
View File

@@ -1,6 +1,6 @@
# Scaffolding a feature
`turbo gen feature` produces a Lazar-conformant feature package under
`turbo gen feature` produces a feature package under
`packages/<name>/` matching the shape of the reference `navigation` feature.
## Invoking the generator
@@ -18,11 +18,11 @@ Non-interactive (positional bypass — order matches the prompts in
pnpm turbo gen feature --args <name> <Entity> <entities-plural>
```
| Position | Prompt | Example | Conventions |
|---|---|---|---|
| `<name>` | Feature package name | `widgets` | `kebab-case`, becomes `@repo/<name>` and `packages/<name>/` |
| `<Entity>` | Entity name | `Widget` | `PascalCase` singular, drives class/symbol/use-case names |
| `<entities-plural>` | Entity plural slug | `widgets` | `kebab-case`, used for the future Payload collection slug |
| Position | Prompt | Example | Conventions |
| ------------------- | -------------------- | --------- | ----------------------------------------------------------- |
| `<name>` | Feature package name | `widgets` | `kebab-case`, becomes `@repo/<name>` and `packages/<name>/` |
| `<Entity>` | Entity name | `Widget` | `PascalCase` singular, drives class/symbol/use-case names |
| `<entities-plural>` | Entity plural slug | `widgets` | `kebab-case`, used for the future Payload collection slug |
Example end-to-end:
@@ -60,7 +60,7 @@ See `docs/guides/conformance-quickref.md` for the manifest field reference.
- DI: `symbols.ts`, `module.ts`, `container.ts`, plus
`bind-production.ts` and `bind-dev-seed.ts` that compose
`withSpan(tracer, opts, withCapture(logger, tags, factory(deps)))` at
bind time (post-R44 sandwich pattern)
bind time (span + capture sandwich pattern)
- tRPC integration: `procedures.ts` (feature-scoped error middleware) and
`router.ts` exposing `get<Entity>` with full router tests including
`BAD_REQUEST` / `NOT_FOUND` mapping
@@ -123,8 +123,8 @@ The realtime generators insert at three additional fixed `// <gen:realtime-*>` a
schemas-in-use-case, three binding modes per feature, span + capture sandwich)
- `packages/navigation/AGENTS.md` — canonical reference shape the templates mirror
- `docs/architecture/vertical-feature-spec.md` — design rationale for the layout
- `docs/decisions/adr-012-lazar-conformance.md` — file naming + factory pattern
- `docs/decisions/adr-012-feature-conventions.md` — file naming + factory pattern
- `docs/decisions/adr-013-input-output-unification.md` — schemas-in-use-case + presenter
- `docs/decisions/adr-014-instrumentation-sentry.md` — span + capture wiring (R41–R44)
- `docs/decisions/adr-014-instrumentation-sentry.md` — span + capture wiring
- `docs/decisions/adr-015-events-and-jobs.md` — cross-feature events + background jobs
- `docs/decisions/adr-016-realtime-layer.md` — Socket.IO realtime channels + handlers

116
docs/guides/tdd-workflow.md
View File

@@ -24,7 +24,9 @@ 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" }));
await repo.createArticle(
articleFactory.build({ slug: "hello-world", authorId: "u1" }),
);
const useCase = getArticleBySlugUseCase(repo);
const controller = getArticleBySlugController(useCase);
@@ -38,9 +40,9 @@ describe("getArticleBySlugController", () => {
const useCase = getArticleBySlugUseCase(repo);
const controller = getArticleBySlugController(useCase);
await expect(
controller({ slug: "no-such-slug" }),
).rejects.toBeInstanceOf(ArticleNotFoundError);
await expect(controller({ slug: "no-such-slug" })).rejects.toBeInstanceOf(
ArticleNotFoundError,
);
});
});
```
@@ -60,23 +62,31 @@ pnpm test --filter @repo/blog -- get-article-by-slug.controller.test.ts
```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 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; }
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 });
throw new InputParseError("Invalid get-article-by-slug input", {
cause: parsed.error,
});
return presenter(await useCase(parsed.data));
};
}
export type IGetArticleBySlugController = ReturnType<typeof getArticleBySlugController>;
export type IGetArticleBySlugController = ReturnType<
typeof getArticleBySlugController
>;
```
**Run again — confirm GREEN:**
@@ -140,6 +150,7 @@ describe("getArticleBySlugController", () => {
```
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")`.
@@ -232,15 +243,15 @@ 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` |
| 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.
@@ -260,13 +271,13 @@ Entities and use cases have the highest ratio because they encode business rules
## 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% |
| 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:**
@@ -339,21 +350,24 @@ The `defineFactory` function lives in `packages/core-testing/src/factory/define-
---
## 9. Output Validation Tests (R25)
## 9. Output Validation Tests
Every **non-void** use case must have an R25 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.
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>` skip R25 — they have no output schema.
**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 {
getArticlesUseCase,
getArticlesOutputSchema,
} from "@/application/use-cases/get-articles.use-case";
import { MockArticlesRepository } from "@/infrastructure/repositories/articles.repository.mock";
describe("getArticlesUseCase output validation (R25)", () => {
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
@@ -376,7 +390,7 @@ describe("getArticlesUseCase output validation (R25)", () => {
// 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 (R25)", () => {
describe("signInUseCase output validation", () => {
it("throws when authenticationService returns a malformed session", async () => {
const users = new MockUsersRepository([]);
await users.createUser(userFactory.build({ username: "alice" }));
@@ -387,16 +401,18 @@ describe("signInUseCase output validation (R25)", () => {
} as unknown as IAuthenticationService;
const useCase = signInUseCase(users, auth);
await expect(useCase({ username: "alice", password: "x" })).rejects.toBeInstanceOf(ZodError);
await expect(
useCase({ username: "alice", password: "x" }),
).rejects.toBeInstanceOf(ZodError);
});
});
```
Group R25 tests in a separate `describe` block labelled `"<useCase> output validation (R25)"` so they are easy to grep.
Group output-validation tests in a separate `describe` block labelled `"<useCase> output validation"` so they are easy to grep.
---
## 10. Router Error-Mapping Tests (R26)
## 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.
@@ -410,7 +426,7 @@ import { blogContainer } from "@/di/container";
import { BlogModule } from "@/di/module";
import { blogRouter } from "@/integrations/api/router";
describe("blogRouter (R26 error mapping)", () => {
describe("blogRouter error mapping", () => {
beforeEach(() => {
blogContainer.unbindAll();
blogContainer.load(BlogModule);
@@ -450,10 +466,14 @@ For features where a domain error can only be triggered by an empty store (e.g.
it("translates HeaderNotFoundError → NOT_FOUND", async () => {
@injectable()
class NullHeaderRepository implements IHeaderRepository {
async getHeader() { return undefined; }
async getHeader() {
return undefined;
}
}
navigationContainer.unbind(NAVIGATION_SYMBOLS.IHeaderRepository);
navigationContainer.bind(NAVIGATION_SYMBOLS.IHeaderRepository).to(NullHeaderRepository);
navigationContainer
.bind(NAVIGATION_SYMBOLS.IHeaderRepository)
.to(NullHeaderRepository);
const caller = navigationRouter.createCaller({});
try {
@@ -470,7 +490,7 @@ Every feature needs at least one `NOT_FOUND` (or domain-error) test and one `BAD
---
## 11. Presenter Shape Tests (R27/R28)
## 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.
@@ -485,13 +505,19 @@ describe("signInController", () => {
const users = new MockUsersRepository([]);
const auth = new MockAuthenticationService(users);
await users.createUser(
userFactory.build({ username: "alice", passwordHash: "hashed_testpassword" }),
userFactory.build({
username: "alice",
passwordHash: "hashed_testpassword",
}),
);
const useCase = signInUseCase(users, auth);
const controller = signInController(useCase);
const result = await controller({ username: "alice", password: "testpassword" });
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();
@@ -501,7 +527,7 @@ describe("signInController", () => {
**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`.
**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.
@@ -580,6 +606,7 @@ describe("CommentsRepository", () => {
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)
@@ -655,12 +682,15 @@ E2E tests live in `apps/web-next/e2e/`. The `webServer` block in `apps/web-next/
---
## Asserting spans and captures (Plan 10)
## 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 {
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";

109
docs/guides/testing-strategy.md
View File

@@ -2,23 +2,23 @@
A layered approach: direct factory injection + colocated unit tests + Playwright e2e.
For the *how* of TDD (red-green-refactor cycle, when to mock, what NOT to test), see [tdd-workflow.md](./tdd-workflow.md). This document covers test *placement* and infrastructure.
For the _how_ of TDD (red-green-refactor cycle, when to mock, what NOT to test), see [tdd-workflow.md](./tdd-workflow.md). This document covers test _placement_ and infrastructure.
For the full R25 / R26 / R27 / R28 patterns with worked examples, see [tdd-workflow.md §4 (mock decision tree)](./tdd-workflow.md).
For the full output-validation, error-mapping, and view-shape patterns with worked examples, see [tdd-workflow.md §4 (mock decision tree)](./tdd-workflow.md).
Related ADRs: [ADR-012](../decisions/adr-012-lazar-conformance.md) — Clean Architecture conformance; [ADR-013](../decisions/adr-013-input-output-unification.md) — input/output unification + presenter + error middleware.
Related ADRs: [ADR-012](../decisions/adr-012-feature-conventions.md) — Clean Architecture conformance; [ADR-013](../decisions/adr-013-input-output-unification.md) — input/output unification + presenter + error middleware.
## Test placement
| Level | Location | Tool | Example |
|---|---|---|---|
| **Unit (colocated)** | `packages/<feature>/src/entities/models/<entity>.test.ts` | Vitest | Schema validation, type guards |
| **Use case** | `packages/<feature>/src/application/use-cases/<name>.use-case.test.ts` | Vitest | Direct factory injection + R25 output-validation |
| **Controller** | `packages/<feature>/src/interface-adapters/controllers/<name>.controller.test.ts` | Vitest | Direct factory injection + R10 input validation + R27/R28 view shape |
| **Repository contract** | `packages/<feature>/src/infrastructure/repositories/<impl>.repository.test.ts` | Vitest + contract suite | Interface conformance |
| **Router (integration)** | `packages/<feature>/src/integrations/api/router.test.ts` | Vitest + container | R26 domain → TRPCError mapping |
| **Feature level** | `packages/<feature>/tests/<name>.feature.test.ts` | Vitest | Cross-layer integration via direct injection |
| **E2E (app)** | `apps/web-next/e2e/<name>.spec.ts` | Playwright | Full user flow across frontend + backend |
| Level | Location | Tool | Example |
| ------------------------ | --------------------------------------------------------------------------------- | ----------------------- | -------------------------------------------------------- |
| **Unit (colocated)** | `packages/<feature>/src/entities/models/<entity>.test.ts` | Vitest | Schema validation, type guards |
| **Use case** | `packages/<feature>/src/application/use-cases/<name>.use-case.test.ts` | Vitest | Direct factory injection + output-validation |
| **Controller** | `packages/<feature>/src/interface-adapters/controllers/<name>.controller.test.ts` | Vitest | Direct factory injection + input validation + view shape |
| **Repository contract** | `packages/<feature>/src/infrastructure/repositories/<impl>.repository.test.ts` | Vitest + contract suite | Interface conformance |
| **Router (integration)** | `packages/<feature>/src/integrations/api/router.test.ts` | Vitest + container | Domain → TRPCError mapping |
| **Feature level** | `packages/<feature>/tests/<name>.feature.test.ts` | Vitest | Cross-layer integration via direct injection |
| **E2E (app)** | `apps/web-next/e2e/<name>.spec.ts` | Playwright | Full user flow across frontend + backend |
**Colocated vs feature-level:** Colocated tests (`*.test.ts` next to source) test isolated units. Feature-level tests (`tests/` folder) wire the full chain via direct injection and test interactions between layers.
@@ -39,10 +39,14 @@ describe("getArticlesUseCase", () => {
it("filters by status", async () => {
const repo = new MockArticlesRepository();
articleFactory.reset();
await repo.createArticle(articleFactory.build({ id: "1", status: "draft" }));
await repo.createArticle(articleFactory.build({ id: "2", status: "published" }));
await repo.createArticle(
articleFactory.build({ id: "1", status: "draft" }),
);
await repo.createArticle(
articleFactory.build({ id: "2", status: "published" }),
);
const useCase = getArticlesUseCase(repo); // direct injection
const useCase = getArticlesUseCase(repo); // direct injection
const result = await useCase({ status: "published" });
expect(result).toHaveLength(1);
});
@@ -63,10 +67,13 @@ describe("signInController", () => {
const users = new MockUsersRepository([]);
const auth = new MockAuthenticationService(users);
const useCase = signInUseCase(users, auth);
const controller = signInController(useCase); // direct injection
const controller = signInController(useCase); // direct injection
const result = await controller({ username: "alice", password: "testpassword" });
expect(result.name).toBe("session"); // presenter view shape (R27)
const result = await controller({
username: "alice",
password: "testpassword",
});
expect(result.name).toBe("session"); // presenter view shape
expect(result.value).toBeTruthy();
});
});
@@ -86,10 +93,10 @@ import { blogContainer } from "@/di/container";
import { BlogModule } from "@/di/module";
import { blogRouter } from "@/integrations/api/router";
describe("blogRouter (R26 error mapping)", () => {
describe("blogRouter error mapping", () => {
beforeEach(() => {
blogContainer.unbindAll();
blogContainer.load(BlogModule); // loads default mock bindings
blogContainer.load(BlogModule); // loads default mock bindings
});
afterEach(() => {
@@ -98,10 +105,9 @@ describe("blogRouter (R26 error mapping)", () => {
it("translates ArticleNotFoundError → NOT_FOUND", async () => {
const caller = blogRouter.createCaller({});
await expect(caller.articleBySlug({ slug: "missing" }))
.rejects.toSatisfy((e: unknown) =>
e instanceof TRPCError && e.code === "NOT_FOUND"
);
await expect(caller.articleBySlug({ slug: "missing" })).rejects.toSatisfy(
(e: unknown) => e instanceof TRPCError && e.code === "NOT_FOUND",
);
});
});
```
@@ -111,7 +117,9 @@ When a test needs a specific repo behaviour at the router level, bind it directl
```typescript
beforeEach(() => {
blogContainer.unbindAll();
blogContainer.bind(BLOG_SYMBOLS.IArticlesRepository).toConstantValue(new AlwaysEmptyRepo());
blogContainer
.bind(BLOG_SYMBOLS.IArticlesRepository)
.toConstantValue(new AlwaysEmptyRepo());
});
```
@@ -137,12 +145,13 @@ The mock repository satisfies the repository interface without touching Payload
### Option 2: Router-level — use the feature's DI container
When testing the tRPC router (R26 error-mapping, procedure wiring), bind a mock or stub repository through the feature container in `beforeEach`:
When testing the tRPC router (error-mapping, procedure wiring), bind a mock or stub repository through the feature container in `beforeEach`:
```typescript
beforeEach(() => {
blogContainer.unbindAll();
blogContainer.bind(BLOG_SYMBOLS.IArticlesRepository)
blogContainer
.bind(BLOG_SYMBOLS.IArticlesRepository)
.toConstantValue(new MockArticlesRepository());
});
```
@@ -156,25 +165,25 @@ vi.mock("payload", () => ({ getPayload: vi.fn() }));
Then provide a stub via `stubPayloadConfig` from `@repo/core-testing/payload` (see [tdd-workflow.md §4](./tdd-workflow.md) for the full contract-suite pattern).
## Test obligations per layer (Plan 9)
## Test obligations per layer
| Layer | Test type | Required by spec | Example |
|---|---|---|---|
| Entity | Schema validation | — | `articleSchema.safeParse(...)` → accepts valid / rejects invalid |
| Use case (input) | Behavior | — | factory injection; assert result shape and filtering |
| Use case (output, R25) | Runtime guarantee | R25 | inject malformed mock output → `.rejects.toBeInstanceOf(ZodError)` |
| Controller (input, R10) | Validation | R10 | `controller({} as unknown)` → `.rejects.toBeInstanceOf(InputParseError)` |
| Controller (presenter, R27/R28) | View shape | R27/R28 (when reshaping) | `expect(result.name).toBe("session")` (not `result.session`) |
| Repository contract | Interface conformance | — | run `defineContractSuite` against mock + real impl |
| Router (R26) | Domain → TRPCError | R26 | `xRouter.createCaller({}).x(...)` → assert `TRPCError.code` |
| Feature-level (`tests/`) | Cross-layer integration | — | wire the chain via direct injection (no container) |
| E2E | Full user flow | — | Playwright |
| Layer | Test type | Required by spec | Example |
| ------------------------ | ----------------------- | ---------------- | ------------------------------------------------------------------------ |
| Entity | Schema validation | — | `articleSchema.safeParse(...)` → accepts valid / rejects invalid |
| Use case (input) | Behavior | — | factory injection; assert result shape and filtering |
| Use case (output) | Runtime guarantee | — | inject malformed mock output → `.rejects.toBeInstanceOf(ZodError)` |
| Controller (input) | Validation | — | `controller({} as unknown)` → `.rejects.toBeInstanceOf(InputParseError)` |
| Controller (presenter) | View shape | when reshaping | `expect(result.name).toBe("session")` (not `result.session`) |
| Repository contract | Interface conformance | — | run `defineContractSuite` against mock + real impl |
| Router | Domain → TRPCError | — | `xRouter.createCaller({}).x(...)` → assert `TRPCError.code` |
| Feature-level (`tests/`) | Cross-layer integration | — | wire the chain via direct injection (no container) |
| E2E | Full user flow | — | Playwright |
**R25** — Every non-void use case ends with `xOutputSchema.parse(result)`. The R25 test proves this: inject a mock that returns a structurally invalid object and assert `ZodError` propagates.
**Output validation** — Every non-void use case ends with `xOutputSchema.parse(result)`. The test proves this: inject a mock that returns a structurally invalid object and assert `ZodError` propagates.
**R26** — Every feature has `procedures.ts` with a `defineErrorMiddleware` error map. The R26 test calls the tRPC procedure through `router.createCaller({})` and asserts the correct `TRPCError.code` (e.g. `NOT_FOUND`, `BAD_REQUEST`, `UNAUTHORIZED`).
**Error mapping** — Every feature has `procedures.ts` with a `defineErrorMiddleware` error map. The router test calls the tRPC procedure through `router.createCaller({})` and asserts the correct `TRPCError.code` (e.g. `NOT_FOUND`, `BAD_REQUEST`, `UNAUTHORIZED`).
**R27/R28** — Controllers that reshape the use-case output (e.g. auth controllers that return a cookie instead of the full session object) must have a test asserting the view shape — not the raw use-case output.
**View shape** — Controllers that reshape the use-case output (e.g. auth controllers that return a cookie instead of the full session object) must have a test asserting the view shape — not the raw use-case output.
## Vitest setup per package
@@ -308,18 +317,17 @@ Root `turbo.json`:
3. **E2E tests** prove the app works end-to-end (minimal smoke specs initially)
4. **Per-feature containers** are used at the **router level**; use-case + controller tests inject mocks directly into the factory (no container)
## R49 / R50 — Instrumentation testing (Plan 10)
## Instrumentation testing
**R49 — No real Sentry in tests.** The `core-testing/setup/no-sentry.ts` guard mocks `@sentry/nextjs`, `@sentry/node`, and `@sentry/react` at the module level, so any code that imports them gets a no-op surface during vitest runs. Tests that want to assert specific Sentry SDK calls add their own `vi.mock(...)` per file.
**No real Sentry in tests.** The `core-testing/setup/no-sentry.ts` guard mocks `@sentry/nextjs`, `@sentry/node`, and `@sentry/react` at the module level, so any code that imports them gets a no-op surface during vitest runs. Tests that want to assert specific Sentry SDK calls add their own `vi.mock(...)` per file.
**R50 — Repository contracts assert span shape.** Every `__contracts__/<x>-repository.contract.ts` includes a `span emission (R50)` describe block enumerating one assertion per public method. Suites run against both mock and real (Payload-backed) implementations, ensuring span emission stays in sync. Wire the recording tracer at the call site:
**Repository contracts assert span shape.** Every `__contracts__/<x>-repository.contract.ts` includes a `span emission` describe block enumerating one assertion per public method. Suites run against both mock and real (Payload-backed) implementations, ensuring span emission stays in sync. Wire the recording tracer at the call site:
```ts
const tracer = new RecordingTracer();
articlesRepositoryContract.run(
() => new MockArticlesRepository(tracer),
{ tracer: () => tracer },
);
articlesRepositoryContract.run(() => new MockArticlesRepository(tracer), {
tracer: () => tracer,
});
```
**Capture vs span assertions:**
@@ -330,5 +338,4 @@ articlesRepositoryContract.run(
- `RecordingLogger.users` — every `setUser` call (history).
- `RecordingAuditLog.entries` — every `record(entry)` call. Use to assert audit emissions in feature-package tests **without** importing `@repo/core-audit` (the recording double lives in `@repo/core-testing/instrumentation` and mirrors the `AuditEntry` shape inline to avoid the tooling→core boundary). Also exposes `RecordingAuditLog.erasures` for `eraseSubject` history. See ADR-018 and `docs/guides/audit-and-compliance.md` for what to assert.
**Test cleanup:** call `tracer.reset()`, `logger.reset()`, and `auditLog.reset()` in `beforeEach` if the test creates one shared instance across multiple cases.
5. **Mock repos** are the default; only use real Payload in dedicated infrastructure tests
**Test cleanup:** call `tracer.reset()`, `logger.reset()`, and `auditLog.reset()` in `beforeEach` if the test creates one shared instance across multiple cases. 5. **Mock repos** are the default; only use real Payload in dedicated infrastructure tests