docs(tests): add tests/README.md with factory and mock catalogs

[aaight]

Summary

• Creates tests/README.md documenting all shared test helpers, factory functions, mock catalogs, and conventions
• Adds a pointer in CLAUDE.md under the Testing section linking to the new README

Card: https://trello.com/c/dC7hK1vw/524-as-a-developer-i-want-a-tests-readmemd-with-factory-and-mock-catalogs-so-that-new-test-contributors-follow-consistent-patterns

What was implemented

tests/README.md (new file)

1. Overview — describes the 4 unit projects + 1 integration project structure, with a table showing include patterns and a directory listing of tests/helpers/
2. Running Tests — commands for running each project, including the single-file shortcut
3. Factory Catalog — complete table listing every factory function in factories.ts (project, tRPC user/context, trigger context, Trello payload, GitHub payload) with file paths, descriptions, and usage examples
4. Mock Catalog — complete tables for sharedMocks.ts (15 exports) and backendMocks.ts (5 exports), each with the module they mock and vi.mock() usage examples
5. tRPC Test Harness — documents createCallerFor, setupOwnershipCheckMock, and expectTRPCError with full usage examples
6. DB Mock Helper — documents createMockDb (all options) and createMockDbWithGetDb with usage examples
7. PM Provider Mock — documents createMockPMProvider with all stubbed methods listed
8. Conventions — documents vi.mock() hoisting constraint, vi.hoisted() preferred pattern, clearMocks: true auto-reset behavior, and isolate: false safety rules for unit-core
9. Adding New Shared Mocks — checklist for when to extract vs. keep inline

CLAUDE.md (updated)

• Added a single line under ### Testing linking to tests/README.md

Test plan

• npm run lint passes (zero errors)
• npm run typecheck passes (zero errors)
• No test files were modified — this is a documentation-only change

🤖 Generated with Claude Code

🕵️ claude-code · claude-sonnet-4-6 · run details

[nhopeatall]

Summary

LGTM — This is a thorough, accurate documentation of the test infrastructure. I verified every factory, mock, harness function, and convention claim against the actual source files and vitest config. The documentation faithfully reflects the codebase.

Verification performed

• factories.ts: All 13 documented factory functions match (names, signatures, return types, default values)
• sharedMocks.ts: All 15 documented exports match the source (names, mocked modules, descriptions)
• backendMocks.ts: All 5 documented exports match the source
• trpcTestHarness.ts: createCallerFor, setupOwnershipCheckMock, and expectTRPCError all match documented signatures and behavior
• mockDb.ts: createMockDb options (withLimit, withDoubleJoin, withUpsert, withThenable) and createMockDbWithGetDb match
• mockPMProvider.ts: All documented stubbed methods match the source (including default return values for addComment → '' and linkPR → undefined)
• vitest.config.ts: Project structure (4 unit + 1 integration), clearMocks: true, isolate: false for unit-core all confirmed
• CLAUDE.md: Pointer line correctly placed under ### Testing

Minor note (not blocking)

mockPersonas.ts is listed in the directory tree (└── mockPersonas.ts — GitHub bot-identity stub helpers) but has no dedicated catalog entry like the other helpers. It exports mockPersonaIdentities, IMPLEMENTER_USERNAME, and REVIEWER_USERNAME. Since it's a small file (14 lines, 3 exports), the tree listing is probably sufficient — but if the goal is a complete catalog, a one-row table under Mock Catalog would round it out.

🕵️ claude-code · claude-opus-4-6 · run details