band CLAUDE.md

Band

IDE-agnostic agent orchestrator.

Testing Strategy

This project uses integration tests as the primary testing approach. Do not write unit tests with mocked dependencies.

When writing, adding, or modifying tests — backend OR frontend — invoke the write-integration-test skill FIRST. It is the canonical reference for this repository: real-server boot, Express stubs for external services, no tRPC mocking, no page.route() on own routes, Page Object Model for Playwright, locator priority, the universal checklist, and worked examples for both layers. The rules below are the summary; the skill is the source of truth.

Why Integration Tests

Unit tests with heavy mocking verify that your mocks work, not that your system works. Integration tests exercise the real system through its public interfaces — the same way a client or user would interact with it.

Rules

• Never modify production code to make a test pass. No test-only branches, no exporting internals, no NODE_ENV checks in business logic.
• Black-box testing only. Test through public interfaces: HTTP endpoints, CLI commands, file system outputs, the rendered DOM (frontend).
• Real infrastructure. For databases use test containers, not mocks. For file-based state use temporary directories. Start real servers on random ports.
• External-only stubs at the network boundary. Mock only services your process calls out to (third-party APIs, agent binaries, GitHub, etc.) using an Express stub on a random port + env-var override read at request time. Do NOT use MSW (it misses subprocess-originated traffic, and the env-var indirection is what forces the production code into a testable shape). Do NOT use page.route() to intercept your own backend routes from a Playwright test. Do NOT add a tRPC mock layer.
• Test framework: match the package. node:test with node:assert/strict is the default for new code. The web app (apps/web) is the exception: it already standardised on vitest before this convention was written down (the existing test suite uses describe/it/expect/beforeAll from vitest), so new tests under apps/web/tests/ should use vitest too rather than mix runners in one package. Don't add test framework dependencies elsewhere unless already present.