Two small testing utilities you'll see in every feature: __contracts__/<x>-repository.contract.ts and __factories__/<x>.factory.ts. They look optional — they aren't, once you have more than two implementations of the same interface.
Three things in every feature live near tests but play different roles. The mock repository is a real implementation of the repository interface — it's also the default DI binding. The contract is a portable test suite that runs against any implementation. The factory is a builder for valid entity values. The mock isn't only a test thing; that's the part that surprises people.
The mock is the surprising one. People assume it lives in __mocks__/ because tests use it — but the DI container needs it as the default binding at runtime, and reaching into __mocks__/ from production code crosses a boundary. So the mock lives next to the real implementation, in infrastructure/repositories/. They're siblings.
it() blocks, run twice (once per impl)Article entities with overridable defaultsThe mock has two jobs.
+BlogModule binds IArticlesRepository to MockArticlesRepository at module-load time. Anything resolving that symbol — use cases, controllers, the whole chain — gets the mock until bindProductionBlog(config) swaps it for the real Payload-backed one. See §03.new MockArticlesRepository() and pass it directly into the use-case factory function. No DI involved — just a closure with a fake repo.The contract and factory are pure test ergonomics — they only show up in *.test.ts files. Both live under __-prefixed directories that signal "test territory; not part of the public surface; not imported by runtime code." Their roles:
it() blocks parameterized by buildSubject. Run it against the mock, run it against the real impl. If they diverge — your mock is lying to you and you'd never have caught it without the contract.articleFactory.build({ slug: "x" }) hands you a valid Article with sensible defaults; you only override the fields the test actually cares about. Used by the contract and by every use-case / controller test.This is from packages/blog/src/di/module.ts — the very first binding in the module is the mock. Everything downstream (use cases, controllers) resolves through this default. bindProductionBlog(config) later replaces only this one line at app boot — use case + controller bindings stay put.
export const BlogModule = new ContainerModule((bind) => { + // 1) Mock is the DEFAULT binding for the repo symbol. + // Dev server, unit tests, storybook all resolve to this. + bind<IArticlesRepository>(BLOG_SYMBOLS.IArticlesRepository) + .to(MockArticlesRepository); + + // 2) Use cases consume IArticlesRepository — they don't know or + // care which impl they got. Same factory function in either mode. + bind<IGetArticlesUseCase>(BLOG_SYMBOLS.IGetArticlesUseCase) + .toDynamicValue((ctx) => + getArticlesUseCase( + ctx.container.get<IArticlesRepository>(BLOG_SYMBOLS.IArticlesRepository), + ), + ); + // ... + 5 more bindings, all the same shape. +});+
Use-case + controller tests skip DI entirely. They construct the mock and pass it as the first argument to the use-case factory, then call the resulting closure with the input. Three lines of setup, then assertions.
+it("filters by status", async () => { + // Construct the mock directly — no DI container, no rebinding. + const repo = new MockArticlesRepository(); + + // Use the factory to seed valid entities (only override what we care about). + articleFactory.reset(); + await repo.createArticle(articleFactory.build({ status: "draft" })); + await repo.createArticle(articleFactory.build({ status: "published" })); + + // Inject the mock into the use-case factory; call the resulting closure. + const useCase = getArticlesUseCase(repo); + const result = await useCase({ status: "published" }); + + expect(result).toHaveLength(1); +});+
Two tiny test files, one shared suite. If the suite ever fails on the real impl but passes on the mock — your mock is lying about Payload's behavior and you'd ship a bug. The factory is doing real work here too: every it() in the suite uses articleFactory.build(...) for seed data, so the assertions stay readable.
describe("MockArticlesRepository", () => { + articlesRepositoryContract.run(async () => new MockArticlesRepository()); +}); + +// articles.repository.test.ts (Payload-backed) — same suite, real impl +vi.mock("payload", () => ({ getPayload: vi.fn() })); + +describe("ArticlesRepository (Payload)", () => { + articlesRepositoryContract.run(async () => { + const stub = buildPayloadStub(); + (getPayload as Mock).mockResolvedValue(stub); + return new ArticlesRepository(stubPayloadConfig); + }); +});+
When you run pnpm test --filter @repo/blog, the contract's twelve it() blocks run twice — once per implementation. Twenty-four assertions for the price of writing twelve.