Testing Strategy
Relevant source files
The following files were used as context for generating this wiki page:
The guiltty project employs a multi-tiered testing strategy designed to ensure the reliability of its pixel-level 2D graphics rendering. This strategy encompasses automated unit testing for core logic, protocol-specific verification for terminal communication, and manual visual acceptance for end-to-end rendering correctness.
The strategy is enforced through a strict "Quality Gate" in the Continuous Integration (CI) pipeline, requiring all code changes to pass formatting checks, linting, and a minimum code coverage threshold.
Sources: tasks/plan.md:12, tasks/issue-16-consumability-assessment-from-iklo-guiltty-s.md:7, README.md:43-48
Core Quality Gates
The project maintains high code quality standards through automated tools. Every task and PR must satisfy a specific set of commands, which are also enforced by CI.
| Tool | Command | Requirement |
|---|---|---|
| rustfmt | cargo fmt --all -- --check | Strict adherence to stable defaults |
| clippy | cargo clippy --workspace --all-targets -- -D warnings | No warnings allowed; strict complexity limits |
| llvm-cov | cargo llvm-cov --workspace --summary-only --fail-under-lines 90 | Minimum 90% line coverage |
Sources: tasks/issue-16-consumability-assessment-from-iklo-guiltty-s.md:7, tasks/plan.md:12, rustfmt.toml
Automated Unit Testing
Unit tests are primarily located within the guiltty-core crate. These tests focus on the mathematical correctness of primitive operations, shape rasterization, and sprite management.
Rasterization and Geometry Tests
The Canvas implementation includes extensive tests for drawing operations. These verify that pixels are correctly set in the internal buffer according to geometry rules (e.g., Bresenham for lines, even-odd rule for polygons).
- Clipping Logic: Tests ensure that drawing shapes outside the canvas bounds does not result in panics and that the
liang_barsky_clipalgorithm correctly identifies visible segments. - Coordinate Precision: Tests verify that large coordinates (e.g.,
i32::MAX) do not cause overflows or hangs during rasterization. - Polygon Fills: Specific tests lock down the behavior of the even-odd rule for convex, concave, and self-intersecting paths.
Sources: crates/guiltty-core/src/lib.rs:770-985, tasks/plan.md:65-71
Sprite and Bitmap Management
Tests for Sprite and Bitmap verify the integrity of pixel data during loading and manipulation.
- Image Loading:
Bitmap::from_fileis tested using fixture images (RGBA, RGB, and Grayscale) to ensure proper conversion to the internal RGBA8 format. - Recoverable Errors: Tests confirm that missing or malformed files return a
Result::Errrather than panicking. - Save-Under/Restore-Under: Tests verify that moving a sprite correctly restores the background footprint on the
Canvas.
Sources: crates/guiltty-core/src/lib.rs:987-1110, tasks/plan.md:91-100
Protocol Verification
The guiltty-kitty crate utilizes "Protocol Tests" to verify the encoding of terminal escape sequences without requiring a real terminal.
By using the KittyBackend::with_writer method, tests inject a Vec<u8> or similar buffer to capture the generated output. This allows the suite to assert the structure of APC (_G) sequences, including control keys (like a=T, f=32, C=1) and chunking behavior for large payloads.
Sources: crates/guiltty-kitty/src/lib.rs:95-150, tasks/plan.md:46-51
Manual Visual Verification
Since automated tests cannot easily verify the actual visual output on a physical terminal, the strategy includes a manual phase using example binaries.
The success criteria for v0 require a runnable example that demonstrates:
- Drawing text and shapes (including filled paths).
- Placing a sprite from a file.
- Moving the sprite and calling
present()again to prove background preservation.
Sources: tasks/plan.md:113-132, README.md:37-41
Continuous Integration (CI) Hardening
The testing strategy is supported by a hardened CI environment that ensures reproducibility.
- Toolchain Pinning: The Rust version is pinned to
1.96.0viamise.tomlandCargo.toml. - Action Pinning: GitHub Actions are pinned to specific commit SHAs to prevent supply chain attacks and ensure consistent runs.
- Caching: Build caching is implemented to provide fast feedback loops while maintaining the 90% coverage floor.
Sources: tasks/issue-8-chore-ci-hardening-follow-ups-caching-sha-pinned.md, Cargo.toml:10, mise.toml:2
The combination of strict quality gates, robust unit tests for geometry, mockable protocol backends, and manual visual checks provides a comprehensive framework for developing a reliable terminal graphics library.