A guided tour
of one feature's
data flow.

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.