Testing Philosophy & TDD
Relevant source files
The following files were used as context for generating this wiki page:
Vata follows a rigorous testing philosophy centered on Test-Driven Development (TDD) and high-fidelity unit testing. The project utilizes Vitest and JSDOM to validate logic across the database layer, business logic managers, and utility modules. Testing is integrated into the development lifecycle through specific command-line tools and a "root cause first" bug-fixing strategy.
Sources: CLAUDE.md:144-147, package.json:33-40
Core Testing Principles
The project mandates a "Reproduction First" approach to bug fixing. Developers are required to write a failing test or a reliable manual reproduction that captures a bug before any production code is modified. If a fix fails, the project dictates a shift to root-cause investigation rather than iterative patching.
Sources: CLAUDE.md:214-220
Test-Driven Development (TDD) Workflow
Vata employs a "red-green-refactor" cycle, often assisted by specialized agents like the test-writer which generates behavioral tests during the TDD "red" phase.
A visual representation of the project's behavioral testing cycle.
Sources: CLAUDE.md:214-220, CLAUDE.md:257
Testing Infrastructure & Tooling
The testing stack is built on modern JavaScript tooling, ensuring fast execution and comprehensive coverage reporting.
| Tool | Purpose |
|---|---|
| Vitest | Primary test runner and assertion library |
| JSDOM | Browser environment simulation for UI-related tests |
| SQLite In-Memory | High-speed, isolated database environments for unit tests |
| V8 | Coverage provider for generating analysis reports |
Sources: CLAUDE.md:33-40, CLAUDE.md:144-147, package.json:104-105
Development Scripts
Tests can be executed in various modes depending on the developer's needs:
pnpm test: Launches Vitest in watch mode for active development.pnpm test:coverage: Generates a full coverage report using the V8 engine.pnpm vitest run [path]: Executes a specific test file to reduce context overhead.
Sources: CLAUDE.md:33-40
Database Layer Testing
Database tests (located in src/db/**) use a specialized in-memory SQLite helper (sqlite-memory.ts) to ensure tests are isolated and do not leave artifacts.
Mocking and State Management
Test files colocate with their source (e.g., individuals.test.ts next to individuals.ts). They follow a strict pattern of mocking the database connection and resetting the state between tests.
The lifecycle of a database unit test in Vata.
Sources: src/db/trees/events.test.ts:39-65, src/db/trees/names.test.ts:26-31
Example: Names Module Test Coverage
The Names module tests validate complex logic such as primary name management and formatting:
- Primary Name Enforcement: Ensuring only one name is marked
isPrimaryfor an individual. - Format Logic: Validating that
formatNamecorrectly handles prefixes, suffixes, and "sortable" name strings. - CRUD Operations: Verifying that creating, updating, and deleting name records persists correctly to the in-memory store.
Sources: src/db/trees/names.test.ts:40-100, src/db/trees/names.test.ts:182-250
Logic Orchestration Testing
Managers, such as the SourceWorkspaceManager, are tested to ensure they correctly coordinate multiple database layers and handle complex business rules.
Workspace Manager Flow
Tests for SourceWorkspaceManager verify the orchestration of creating individuals, events, families, and citations from templates.
The data flow validated during SourceWorkspaceManager integration tests.
Sources: src/managers/SourceWorkspaceManager.test.ts:360-390
Parser & Lexer Testing
The GEDCOM parsing engine is validated through extensive string-based unit tests. These tests ensure the lexer can handle various line endings (Windows, Mac, Unix), process continuations (CONC and CONT tags), and correctly reconstruct individual and family entities from raw strings.
Validation Categories
| Category | Validated Logic |
|---|---|
| Lexing | Tokenization, line endings, BOM handling, and tag casing. |
| Continuations | Concatenation of split strings without adding illegal whitespace. |
| Integrity | Detection of duplicate XREFs, missing headers, or invalid level jumps. |
Sources: src/gedcom-parser/lexer.test.ts:4-60, src/gedcom-parser/parse.test.ts:44-80, src/gedcom-parser/validate.test.ts:5-60
Summary
Vata's testing philosophy prioritizes technical accuracy and stability through a mandatory TDD approach. By utilizing in-memory SQLite instances for database tests and strict reproduction requirements for bug fixes, the project maintains a high-quality codebase where logic changes are continuously verified against an extensive suite of unit and integration tests.
Sources: CLAUDE.md:214-222, package.json:33-40