breeze-testing

name	breeze-testing
description	Writing guidelines for Breeze RMM tests — API route (Vitest + Drizzle mocks), Go agent, shared validators, and the required coverage checklist for every new feature. Use when writing or modifying tests in this repo.

Breeze Testing

Project-specific conventions for writing tests. Frameworks and file placement live in CLAUDE.md; this skill covers the writing craft: patterns that catch real bugs, gotchas that burn people, and the coverage contract every new feature must satisfy.

Writing API Route Tests (Vitest)

• Mock Drizzle ORM query chains matching the exact chain pattern in the source (e.g., select().from().where()).
• Always test multi-tenant isolation — verify org-scoped data can't be accessed cross-org.
• Test all HTTP methods, auth/authz, Zod validation failures, not-found, and error cases.
• Use proper UUIDs in mock data — Zod validates UUID format and will reject 'other-org'.
• Avoid trailing slashes in test URLs — Hono sub-routers return 404 for trailing slashes.
• vi.mock factories are hoisted — don't reference module-level const values inside them; use literal values instead.
• Read 2-3 existing test files in the same directory before writing new ones to match patterns.

Writing Go Agent Tests

• Use table-driven tests for functions with multiple input/output combinations.
• Always run with -race flag to catch data races.
• Mock external dependencies (network, OS, filesystem) — never make real network calls.
• Use build tags for platform-specific tests: //go:build !windows or //go:build darwin.
• Test nil/empty inputs, error paths, and concurrency safety (spawn goroutines in tests).
• Place test helpers in the same package, not in a separate _test package.

Writing Shared Validator Tests

• Test valid inputs, invalid inputs, boundary values, and Zod defaults/coercion.
• For discriminated unions, test each variant separately.
• Test omitempty/optional fields with both present and absent values.
• For schemas with superRefine, test all validation branches.

Coverage Contract — Every New Feature Must Test

1. Happy path — basic success case.
2. Auth/authz — unauthenticated, wrong role, wrong org.
3. Validation — missing required fields, invalid types, boundary values.
4. Multi-tenant isolation — cross-org access denied.
5. Error cases — not found, conflict, server error.
6. Edge cases — empty arrays, nil inputs, concurrent access.

Related

• Frameworks, file placement, and CI integration: see CLAUDE.md → Testing Standards.
• Post-implementation end-to-end verification: use the feature-testing skill.