How snitch-org/snitch works
Project Type and Purpose
• snitch is a C++20 testing framework used for writing and running tests in C++ projects.
• Its design philosophy is to remain simple and “non-invasive” with minimal API overhead and no dynamic (heap) allocations during tests.
• Key use cases include registering tests, running them with comprehensive reporting (console, teamcity, XML), and handling both run-time and compile-time assertions.
File Structure
• Top-level build/configuration files (CMakeLists.txt, meson.build, docker files, and CI workflows in .github) indicate a well-supported cross-platform build system.
• The include/snitch directory holds most of the public API header files (macros and utility functions, e.g., snitch.hpp, snitch_cli.hpp, snitch_registry.hpp, etc.), which serve as the framework’s interface.
• The src directory contains the implementation (e.g., snitch.cpp, snitch_registry.cpp, snitch_section.cpp) that supports the testing logic.
• A separate tests directory provides various test suites (runtime, install, approval tests) to validate the framework’s behavior.
• The doc folder shows additional documentation—including coding guidelines, comparison with Catch2, and examples—supporting both developers and end-users.
README for Architectural Insights
• It describes how the snitch API is meant to be a drop-in or alternative testing framework with a lean API and minimal overhead.
Main Components
a. Public API / Interface Module
• Include/snitch headers where users will write tests (TEST_CASE, TEMPLATE_TEST_CASE, SECTION, etc.).
• Macros and functions for registering tests and assertions.
b. Test Registration and Execution Core
• The “Registry” and “Test Runner”: Components in src (snitch_registry.cpp, snitch_main.cpp) that aggregate test cases, manage execution flow, and handle filtering based on CLI or tag criteria.
c. Reporting Subsystem
d. Assertion and Matcher Logic
• Since test assertions and matchers are a core feature, mark the components (snitch_capture, snitch_matcher, snitch_expression, snitch_error_handling) that parse and evaluate test expressions.
e. Command-line Interface (CLI) / Configuration
f. Build and Continuous Integration (CI) Support
• A block for build configuration (CMake, Meson, Docker, CI workflows in .github), showing how the build system integrates with the project and possibly triggers automated testing, code coverage (via codecov.yml), and release workflows.
g. Documentation and Developer Utilities
• A node for the documentation (doc folder) and utilities (e.g., make_snitch_all.py to create a single header version) that help both users and contributors.
Relationships and Interactions
• Users write tests using the Public API (node: “Test Cases – API”, originating from include/snitch).
• These macros register tests with the Test Registry. The registry holds pointers to test cases and orchestrates execution.
• When tests run, the Test Runner invokes tests according to command-line filters (CLI module) and passes events to the Reporting module.
• The Reporter module translates test events (pass, fail, assertion messages, captures) into formatted console output or XML files.
• The Assertion/Matcher subsystem is used internally by test macros to evaluate check conditions and produce detailed failure messages.
• Build system tools (CMake/Meson) and CI workflows will invoke the test executable as part of automated builds.
Architectural Patterns & Design Principles
• Modular Design: Clear separation between user-facing API, test registration/execution core, reporting, and supporting utilities.
• Plug-in Architecture for Reporters: The reporting mechanism uses function pointers/callbacks or strategy pattern so that different reporter implementations can be swapped.
• Header-only vs. Compiled Library Flexibility: The design accommodates being built as a header-only single file (snitch_all.hpp) or as a traditional compiled library.
• Minimal Runtime Overhead: Emphasize that no dynamic memory allocation occurs in assertions.