Testing Strategy
Relevant source files
The following files were used as context for generating this wiki page:
The testing strategy for chkpt is multi-layered, ensuring the reliability of its content-addressable storage system across different language implementations (Rust and Node.js) and platforms. The strategy encompasses unit testing of core logic, integration testing of save/restore operations, and end-to-end (E2E) validation of the entire lifecycle.
The primary goal is to ensure data integrity during deduplication (using XXH3-128 or BLAKE3) and compression (LZ4 or zstd), while maintaining incremental performance via SQLite indexing. Testing is enforced through a pre-commit checklist and CI/CD requirements.
Sources: CLAUDE.md:1-25, README.md:1-20
Rust Core Testing
The core Rust library (chkpt-core) serves as the foundation for the entire project. Its testing focuses on the underlying storage mechanisms, including blob storage, indexing, and manifest persistence.
Integration Tests
Rust integration tests are located in crates/chkpt-core/tests/ and cover major components.
Sources: CONTRIBUTING.md:95-102
- Save Operations: Tests verify basic saving, incremental deduplication (no new objects created if files are unchanged), and subdirectory handling.
Sources: crates/chkpt-core/tests/save_test.rs:65-118 - Restore Operations: Tests validate that restoring a snapshot returns the workspace to its exact original state, including the removal of files added after the snapshot was taken.
Sources: crates/chkpt-core/tests/restore_test.rs:9-62 - Data Integrity: Specific tests ensure that pre-compressed files (like JPEGs) are not double-compressed and can be successfully round-tripped.
Sources: crates/chkpt-core/tests/save_test.rs:10-50
Testing Commands
| Scope | Command |
|---|---|
| All Rust Crates | cargo test --workspace |
| Specific Test File | cargo test -p chkpt-core --test <test_name> |
| Sources: CLAUDE.md:28-35, CONTRIBUTING.md:104-106 |
Node.js (NAPI) Testing
Testing for the Node.js native bindings ensures that the JavaScript API correctly interfaces with the Rust core. These tests are written in TypeScript and executed using Vitest.
Sources: CONTRIBUTING.md:108-110, crates/chkpt-napi/package.json:28
Lifecycle and E2E Tests
The NAPI tests simulate a full user lifecycle within a temporary workspace.
The diagram shows the standard E2E test flow used to validate the Node.js bindings.
Sources: crates/chkpt-napi/test/e2e.spec.ts:18-68
Low-Level API Validation
Beyond high-level operations, NAPI tests verify deterministic project ID generation and the correctness of low-level utilities like blobHash and scanWorkspace.
Sources: crates/chkpt-napi/test/e2e.spec.ts:69-77, crates/chkpt-napi/test/config.spec.ts:9-17
Performance and Regression Testing
Given that chkpt is designed for speed, benchmarking is a critical part of the testing strategy. This includes automated scripts that compare performance against real-world repositories.
Benchmarking Scenarios
The project utilizes a Python-based benchmark suite (scripts/benchmarks.py) to run various scenarios:
| Scenario | Description |
|---|---|
bench_catalog | Measures SQLite metadata performance for large manifests (up to 80k entries). |
bench_ops | End-to-end synthetic workloads measuring cold/warm save and restore. |
save_pipeline | Breaks down the save process into phases: Scan, Index, Read+Hash, Compress, Pack, Tree Build. |
| Sources: scripts/benchmarks.py:90-195, crates/chkpt-core/benches/save_pipeline.rs:130-250 |
Comparison Testing
The compare-commits tool allows developers to build two different Git refs and run them in alternating "rounds" to detect performance regressions.
Sources: scripts/benchmarks.py:840-920
Automation and Protection Patterns
Testing also covers the "Skills" and "MCP Tools" logic, which includes "Proactive Automation" patterns. These patterns define when the system should suggest or automatically trigger a checkpoint.
The diagram illustrates the logic for proactive save suggestions before risky operations.
Sources: crates/chkpt-plugin/skills/chkpt/references/automation-patterns.md:3-25
Conclusion
The chkpt testing strategy combines standard Rust/Node.js testing practices with specialized performance benchmarking and data integrity validation. By utilizing temporary directories for every test case and verifying state before and after "Dry-Run" vs "Actual" operations, the suite ensures that snapshots are reliable enough for critical workspace rollbacks.
Sources: crates/chkpt-core/tests/restore_test.rs:27-46, crates/chkpt-napi/test/ops.spec.ts:46-59