Testing Strategy
Relevant source files
The following files were used as context for generating this wiki page:
The testing strategy for data-path is designed to ensure the integrity, type safety, and functional correctness of object property path manipulations. It leverages a multi-layered approach combining runtime unit tests, static type checking tests, and automated linting. The primary goal is to validate that Proxy-based lambda expressions correctly capture path segments and that operations like data access, path algebra, and template expansions behave predictably across various data structures.
The project utilizes Vitest as the primary test runner, configured to handle both standard runtime specifications (.spec.ts) and TypeScript-specific type assertions (.test-d.ts). This ensures that the library's promise of 100% type safety is verified during the CI/CD pipeline.
Sources: vitest.config.ts:3-11, package.json:18-19
Core Testing Components
The testing suite is organized into distinct categories based on the functionality of the data-path API.
Test Infrastructure and Tooling
The project relies on a modern TypeScript testing stack. The package.json defines several scripts for maintaining code quality:
| Script | Command | Purpose |
|---|---|---|
test | vitest run --typecheck | Executes all runtime and type-level tests once. |
test:watch | vitest --typecheck | Runs tests in watch mode for local development. |
lint | biome check src | Performs static analysis and linting. |
typecheck | tsc --noEmit | Validates that the source code compiles without errors. |
Sources: package.json:14-19
Runtime Functional Testing
Runtime tests focus on the execution logic of the path objects. These tests are located in src/tests/*.spec.ts and cover:
- Path Creation: Validating that lambda expressions correctly serialize to dot-notation strings and segment arrays. Sources: src/tests/path.spec.ts:11-20
- Data Access: Verifying that
.get()and.set()operations correctly traverse objects and maintain immutability. Sources: src/tests/data-access.spec.ts:15-55 - Path Algebra: Testing complex operations like
.merge(),.subtract(), and.slice(). Sources: src/tests/algebra.spec.ts:13-100 - Templates: Validating wildcard behavior (
*and**) and expansion into concrete paths. Sources: src/tests/templates.spec.ts:18-80
Static Type Testing
A unique aspect of the strategy is the inclusion of .test-d.ts files. These files do not execute logic but instead use Vitest's expectTypeOf and assertType utilities to ensure the TypeScript compiler correctly infers types for complex path operations.
Sources: src/tests/types.test-d.ts:1-15
Testing Architecture
The following diagram illustrates the flow of a typical test execution within the project environment.
This diagram represents the integrated verification process where both logic and types must pass for a successful build.
Sources: package.json:14-19, vitest.config.ts:3-11
Detailed Test Modules
1. Creation and Serialization
Tests in path.spec.ts and unsafePath.spec.ts ensure that the Proxy-based mechanism correctly identifies property access.
- Lambda Capture: Tests confirm that dynamic indices and function call results are evaluated once during path creation. Sources: src/tests/path.spec.ts:22-32
- Unsafe Paths: Validates the parsing of raw string inputs into segments, including handling of numeric-looking keys and malformed strings. Sources: src/tests/unsafe.spec.ts:12-30
2. Relational Algebra and Interactions
The interactions.spec.ts module validates how different path objects relate to one another.
The interaction tests ensure that standard paths and templates can be compared for hierarchical relationships.
Sources: src/tests/interactions.spec.ts:14-80
3. Data Mutation and Immutability
A critical part of the strategy involves verifying structural sharing. Tests in data-access.spec.ts assert that .set() operations only create new references along the updated path while preserving original references for unchanged branches.
Sources: src/tests/data-access.spec.ts:60-100
4. Template and Wildcard Logic
Tests in templates.spec.ts verify the behavior of .each() and .deep().
- Expansion:
templatePath.expand(data)is tested to ensure it returns the correct array of concretePathobjects based on existing data. Sources: src/tests/templates.spec.ts:61-75 - Bulk Operations:
.get()and.set()on templates are tested for their ability to retrieve or update multiple values simultaneously. Sources: src/tests/templates.spec.ts:146-165
Conclusion
The data-path testing strategy provides a robust safety net by treating TypeScript types as first-class citizens in the verification process. By combining runtime assertions with static type checks, the project ensures that any refactoring or change in object structure is immediately caught by the testing suite, maintaining the library's reliability for deep state management and form binding.
Sources: src/tests/types.test-d.ts:100-150, package.json:3-10