test-file-organization

Test File Organization

File Size Limit

Maximum file size: 500 lines. Keep test files under 500 lines for readability and navigability; split when a file exceeds it.

Splitting Strategy

When to split: the file exceeds 500 lines, contains multiple distinct concerns that separate logically, or has multiple top-level describe blocks splittable by functionality.

How to split:

• Identify logical groupings — by functionality (basic, errors, structure, generation), feature area (joins, projections, includes), or test type (unit, integration, edge-cases). Integration tests that depend on multiple packages belong in integration-tests to avoid cyclic dependencies (e.g. tests using both sql-contract-ts and sql-query).
• Use descriptive names — suffix by category (.basic.test.ts, .errors.test.ts, .structure.test.ts), prefix by feature area (runtime.joins.test.ts), keep the base name consistent (codecs.registry.test.ts, codecs.encoding.test.ts).
• Split at natural boundaries — by describe block (distinct concerns), test category (basic vs advanced, success vs error), or feature area. Never split arbitrarily by line count (codecs.part1.test.ts, part2…) — that makes related tests hard to find.
• Ensure each file is complete — all necessary imports and setup/teardown, independently runnable.

// ✅ Split by functionality
// codecs.registry.test.ts
describe('codec registry', () => { it('registers codec', () => {}); it('gets codec by id', () => {}); });
// codecs.encoding.test.ts
describe('codec encoding', () => { it('encodes string value', () => {}); it('handles null values', () => {}); });

// ✅ Split by feature area
// runtime.joins.test.ts
describe('runtime joins', () => { it('executes inner join', () => {}); it('executes left join', () => {}); });
// runtime.projections.test.ts
describe('runtime projections', () => { it('executes nested projection', () => {}); });