# snitch-org/snitch architecture

> Architecture diagram of the GitHub repository snitch-org/snitch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/snitch-org/snitch
- Repository: https://github.com/snitch-org/snitch

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User-Facing API"
        API["Public API (include/snitch)"] 
    end

    subgraph "Core Execution"
        REG["Test Registration & Execution\n(src: snitch_registry.cpp, snitch_main.cpp)"]
        CLI["Command-line Interface\n(snitch_cli.hpp, snitch_cli.cpp)"]
    end

    subgraph "Internal Processing"
        ASR["Assertion & Matcher Engine\n(snitch_matcher, snitch_capture, snitch_error_handling)"]
        REP["Reporting Subsystem\n(Console, TeamCity, Catch2 XML)"]
    end

    subgraph "Build & Support"
        BUILD["Build & CI Integration\n(CMake, Meson, Docker, CI workflows, codecov)"]
        DOC["Documentation & Developer Utilities\n(doc, make_snitch_all.py)"]
    end

    %% Relationships
    API -->|"registersTests"| REG
    CLI -->|"configures"| REG
    REG -->|"evaluatesTests"| ASR
    REG -->|"sendsEvents"| REP
    BUILD -->|"triggersTests"| REG
    DOC ---|"assists"| API

    %% Click Events for Public API
    click API "https://github.com/snitch-org/snitch/tree/main/include/snitch"
    
    %% Click Events for Test Registration and Execution Core
    click REG "https://github.com/snitch-org/snitch/tree/main/src"

    %% Click Events for Reporting Subsystem
    click REP "https://github.com/snitch-org/snitch/blob/main/include/snitch/snitch_reporter_console.hpp"
    click REP "https://github.com/snitch-org/snitch/blob/main/src/snitch_reporter_console.cpp"
    click REP "https://github.com/snitch-org/snitch/blob/main/include/snitch/snitch_reporter_teamcity.hpp"
    click REP "https://github.com/snitch-org/snitch/blob/main/src/snitch_reporter_teamcity.cpp"
    click REP "https://github.com/snitch-org/snitch/blob/main/include/snitch/snitch_reporter_catch2_xml.hpp"
    click REP "https://github.com/snitch-org/snitch/blob/main/src/snitch_reporter_catch2_xml.cpp"

    %% Click Events for Assertion and Matcher Logic
    click ASR "https://github.com/snitch-org/snitch/blob/main/include/snitch/snitch_matcher.hpp"
    click ASR "https://github.com/snitch-org/snitch/blob/main/src/snitch_matcher.cpp"
    click ASR "https://github.com/snitch-org/snitch/blob/main/include/snitch/snitch_capture.hpp"
    click ASR "https://github.com/snitch-org/snitch/blob/main/include/snitch/snitch_error_handling.hpp"
    click ASR "https://github.com/snitch-org/snitch/blob/main/src/snitch_capture.cpp"
    click ASR "https://github.com/snitch-org/snitch/blob/main/src/snitch_error_handling.cpp"

    %% Click Events for CLI/Configuration
    click CLI "https://github.com/snitch-org/snitch/blob/main/include/snitch/snitch_cli.hpp"
    click CLI "https://github.com/snitch-org/snitch/blob/main/src/snitch_cli.cpp"

    %% Click Events for Build and CI Support
    click BUILD "https://github.com/snitch-org/snitch/blob/main/CMakeLists.txt"
    click BUILD "https://github.com/snitch-org/snitch/tree/main/cmake/"
    click BUILD "https://github.com/snitch-org/snitch/blob/main/meson.build"
    click BUILD "https://github.com/snitch-org/snitch/tree/main/docker/"
    click BUILD "https://github.com/snitch-org/snitch/tree/main/.github/workflows"
    click BUILD "https://github.com/snitch-org/snitch/blob/main/codecov.yml"

    %% Click Events for Documentation and Developer Utilities
    click DOC "https://github.com/snitch-org/snitch/tree/main/doc"
    click DOC "https://github.com/snitch-org/snitch/blob/main/make_snitch_all.py"

    %% Styles
    classDef publicAPI fill:#B3E5FC,stroke:#0277BD,stroke-width:2px;
    classDef core fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef internal fill:#FFF9C4,stroke:#F9A825,stroke-width:2px;
    classDef support fill:#FFCCBC,stroke:#D84315,stroke-width:2px;
    
    class API publicAPI;
    class REG,CLI core;
    class ASR,REP internal;
    class BUILD,DOC support;
```
