Test Suite Structure

Relevant source files

The following files were used as context for generating this wiki page:

• vitest.config.ts
• test/merge.test.ts
• test/reconcile.test.ts
• test/config.test.ts
• test/wire.test.ts
• test/laws.test.ts
• test/types.ts
• package.json
• AGENTS.md

The keyfold test suite is designed to ensure the immutable folding of partial deltas into state trees is deterministic, failure-safe, and adheres to strict identity-keyed list reconciliation rules. It employs a multi-layered testing strategy including unit tests for specific modules, configuration validation tests, property-based testing for algebraic laws, and static type-level assertions. The suite ensures that any valid delta is idempotent and that the system maintains structural sharing for untouched subtrees.

Sources: AGENTS.md:6-24, package.json:48-49

Testing Infrastructure

The project utilizes Vitest as its primary test runner and fast-check for property-based testing. The environment is configured for Node.js, and tests are executed against ESM modules.

Test Configuration

The test execution is defined in vitest.config.ts, which targets all .test.ts files within the test/ directory.

import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    environment: "node",
    include: ["test/**/*.test.ts"],
  },
});

Sources: vitest.config.ts:1-7

Test Execution Commands

The following scripts in package.json manage the test lifecycle:

Script	Command	Description
test	vitest run	Runs the full test suite once.
test:watch	vitest	Runs Vitest in watch mode for development.
check	npm run typecheck && npm run test ...	Full validation including types, tests, and linting.

Sources: package.json:48-55

Test Categories

1. Module-Specific Functional Tests

These tests focus on the core logic of object merging and keyed-list reconciliation.

• Object Folding (test/merge.test.ts): Validates deep-merging, structural sharing, and the behavior of special sentinels like DELETE. It ensures that plain objects merge while non-plain objects (like Date or Map) are replaced wholesale.
  Sources: test/merge.test.ts:25-70
• Keyed-List Reconciliation (test/reconcile.test.ts): Verifies that lists are updated, deleted, and appended without disturbing the order of surviving items. It tests strict identity matching (e.g., distinguishing numeric 1 from string "1").
  Sources: test/reconcile.test.ts:47-90
• Wire Protocol (test/wire.test.ts): Tests the wireDeletes configuration, ensuring DELETE_TOKEN is interpreted correctly as a field delete only at interpreted positions.
  Sources: test/wire.test.ts:16-45

2. Configuration Validation (test/config.test.ts)

This suite ensures that createMerger correctly identifies and rejects malformed, contradictory, or unreachable path policies at initialization time.

• Invalid Path Segments: Rejects empty segments, array indices in paths (e.g., items[0]), and unsafe segments like constructor.
• Unreachable Policies: Detects when a replace path makes a keyBy policy unreachable (e.g., replacing order when order.items is keyed).
• Identity Field Rules: Rejects reserved fields like $delete or __proto__ as identity fields.

Sources: test/config.test.ts:4-65

3. Algebraic Law Testing (test/laws.test.ts)

Using fast-check, this suite asserts library-wide invariants through property-based testing.

The diagram shows the flow of property-based testing where random base states and deltas are generated to verify core invariants.
Sources: test/laws.test.ts:74-135

Law	Description
Value Idempotency	Applying a delta twice results in the same value as applying it once.
Reference Idempotency	Re-applying the same delta returns the previous result by reference (toBe).
Determinism	The same base and delta always produce the same result.
Immutability	The base object is never mutated; a snapshot remains identical after merge.

Sources: test/laws.test.ts:88-125

4. Type-Level Testing (test/types.ts)

Static assertions using @ts-expect-error verify the Delta<T> type contract.

• Required vs Optional: Ensures DELETE cannot be applied to required properties.
• Atomic Types: Validates that types marked as Atomic must be supplied whole in deltas rather than partially.
• Opaque Types: Ensures built-in opaque types like Error are treated as atomic.

Sources: test/types.ts:26-95

Error Handling and Safety

The test suite explicitly checks for "Failure Safety," ensuring that errors thrown during a merge do not leave the base state in a partially mutated or corrupted form.

Reconciliation Failure Flow

The diagram illustrates the validation-first approach where delta indexing occurs before any state changes, ensuring failure safety.
Sources: test/reconcile.test.ts:153-170, test/laws.test.ts:139-148

Summary

The keyfold test suite provides comprehensive coverage by combining traditional unit testing with property-based and type-level assertions. This structure ensures that the core design principles—immutability, structural sharing, and deterministic reconciliation—are strictly enforced across all supported data shapes and configurations.

Sources: AGENTS.md:27-40