# typeddevs/bashunit architecture

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

- Interactive diagram: https://gitdiagram.com/typeddevs/bashunit
- Repository: https://github.com/typeddevs/bashunit

## Overview

##### Primary Components
- Command-Line Interface (CLI): The main entry point is in scripts like src/main.sh and bin/pre-commit.
- Core Testing Engine: This includes the test runner (src/runner.sh), which discovers and executes tests, along with modules for parallel testing (src/parallel.sh) and state management (src/state.sh).
- Assertions Library: A collection of assertion scripts (src/assert.sh, src/assertions.sh, src/assert_arrays.sh, etc.) which are the core of the framework’s testing capabilities.
- Reporting & Output: Components handling output and reporting (src/console_results.sh, src/console_header.sh, src/reports.sh) that format the results and possibly generate JUnit/HTML reports.
- Configuration & Environment: The project includes configuration examples (.env.example, Makefile, install.sh) and possibly uses the .github workflows for CI/CD automation.
- Documentation & Community Resources: The docs/ directory maintains the official documentation (powered by VitePress), examples, and blog posts, and the README outlines project information.
- Testing of the Framework: The tests directory is organized into unit, functional, and acceptance tests, which show how the framework’s different parts interact and validate each other.

##### Relationships and Interactions
- The CLI receives user commands which forward to src/main.sh.
- The main script then invokes the test runner (src/runner.sh), which discovers tests (from the tests directory) and sequentially or in parallel orchestrates the test execution.
- During test execution, various assertion scripts (e.g., src/assert.sh) are called to perform validations.
- Utility scripts assist in formatting output and handling some OS/environment checks (e.g., src/check_os.sh, src/env.sh).
- Feedback (results and reports) flows from the testing engine to reporting components, which then output to the terminal or generate HTML/JUnit reports.
- CI/CD and quality controls are managed by GitHub workflows (.github/workflows) and static analysis/linter tools, ensuring that changes follow coding standards.

##### Architectural Patterns and Design Principles
- Modular Design: Each functionality is separated into its own script (e.g., separate assertion scripts, utility scripts, etc.), emphasizing reusability and clarity.
- Layered Command Structure: There is a clear separation between the entry point, the business logic (test running and assertions), and the reporting/utility layers.
- Testing Hierarchy: The project itself is built with a rigorous internal testing structure (unit, functional, acceptance tests) to maintain robustness.
- Extensibility: With hundreds of assertions and functionalities like mocks, spies, and providers, the framework’s design is built for both ease-of-use and extension.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Interface
    subgraph "CLI Interface"
        CLI1["src/main.sh"]:::exe
        CLI2["bin/pre-commit"]:::exe
    end

    %% Core Testing Engine
    subgraph "Core Testing Engine"
        TR1["src/runner.sh"]:::exe
        TR2["src/parallel.sh"]:::exe
        TR3["src/state.sh"]:::exe
    end

    %% Assertions Library
    subgraph "Assertions Library"
        A1["src/assert.sh"]:::assert
        A2["src/assertions.sh"]:::assert
        A3["src/assert_arrays.sh"]:::assert
        A4["src/assert_files.sh"]:::assert
        A5["src/assert_folders.sh"]:::assert
        A6["src/assert_snapshot.sh"]:::assert
    end

    %% Reporting & Output
    subgraph "Reporting & Output"
        R1["src/console_header.sh"]:::report
        R2["src/console_results.sh"]:::report
        R3["src/reports.sh"]:::report
    end

    %% Utilities & Helpers
    subgraph "Utilities & Helpers"
        U1["src/helpers.sh"]:::util
        U2["src/io.sh"]:::util
        U3["src/clock.sh"]:::util
        U4["src/colors.sh"]:::util
        U5["src/check_os.sh"]:::util
        U6["src/env.sh"]:::util
    end

    %% Configuration & Environment
    subgraph "Configuration & Environment"
        C1[".env.example"]:::conf
        C2["Makefile"]:::conf
        C3["install.sh"]:::conf
    end

    %% Documentation & Community Resources
    subgraph "Documentation & Community Resources"
        D1["docs/"]:::doc
        D2["README.md"]:::doc
        D3["adrs/"]:::doc
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        CD1[".github/workflows"]:::ci
    end

    %% Testing of the Framework
    subgraph "Testing of the Framework"
        T1["tests/"]:::test
    end

    %% Relationships
    CLI1 -->|"executes"| TR1
    CLI2 -->|"executes"| TR1

    TR1 -->|"runs"| A1
    TR1 -->|"runs"| A2
    TR1 -->|"runs"| A3
    TR1 -->|"runs"| A4
    TR1 -->|"runs"| A5
    TR1 -->|"runs"| A6

    TR1 -->|"utilizes"| U1
    TR1 -->|"utilizes"| U2
    TR1 -->|"utilizes"| U3
    TR1 -->|"utilizes"| U4
    TR1 -->|"utilizes"| U5
    TR1 -->|"utilizes"| U6

    TR1 -->|"discovers"| T1

    A1 -->|"reportsTo"| R1
    A2 -->|"reportsTo"| R2
    A3 -->|"reportsTo"| R3
    A4 -->|"reportsTo"| R1
    A5 -->|"reportsTo"| R2
    A6 -->|"reportsTo"| R3

    R1 -->|"formatsWith"| U4
    R2 -->|"formatsWith"| U4

    CD1 -->|"triggers"| CLI1
    CD1 -->|"triggersTests"| T1

    D1 ---|"guides"| CLI1
    D2 ---|"guides"| TR1
    D3 ---|"documents"| CD1

    C1 ---|"configures"| TR1
    C2 ---|"builds"| TR1
    C3 ---|"installs"| TR1

    %% Additional minor vertical connections for clarity
    TR1 --- A1
    A1 --- R1

    %% Styles
    classDef exe fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef assert fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef report fill:#FADBD8,stroke:#C0392B,stroke-width:2px;
    classDef util fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef conf fill:#FCF3CF,stroke:#B7950B,stroke-width:2px;
    classDef doc fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef ci fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
    classDef test fill:#D6EAF8,stroke:#2980B9,stroke-width:2px;

    %% Click Events
    click CLI1 "https://github.com/typeddevs/bashunit/blob/main/src/main.sh"
    click CLI2 "https://github.com/typeddevs/bashunit/tree/main/bin/pre-commit"
    click TR1 "https://github.com/typeddevs/bashunit/blob/main/src/runner.sh"
    click TR2 "https://github.com/typeddevs/bashunit/blob/main/src/parallel.sh"
    click TR3 "https://github.com/typeddevs/bashunit/blob/main/src/state.sh"
    click A1 "https://github.com/typeddevs/bashunit/blob/main/src/assert.sh"
    click A2 "https://github.com/typeddevs/bashunit/blob/main/src/assertions.sh"
    click A3 "https://github.com/typeddevs/bashunit/blob/main/src/assert_arrays.sh"
    click A4 "https://github.com/typeddevs/bashunit/blob/main/src/assert_files.sh"
    click A5 "https://github.com/typeddevs/bashunit/blob/main/src/assert_folders.sh"
    click A6 "https://github.com/typeddevs/bashunit/blob/main/src/assert_snapshot.sh"
    click R1 "https://github.com/typeddevs/bashunit/blob/main/src/console_header.sh"
    click R2 "https://github.com/typeddevs/bashunit/blob/main/src/console_results.sh"
    click R3 "https://github.com/typeddevs/bashunit/blob/main/src/reports.sh"
    click U1 "https://github.com/typeddevs/bashunit/blob/main/src/helpers.sh"
    click U2 "https://github.com/typeddevs/bashunit/blob/main/src/io.sh"
    click U3 "https://github.com/typeddevs/bashunit/blob/main/src/clock.sh"
    click U4 "https://github.com/typeddevs/bashunit/blob/main/src/colors.sh"
    click U5 "https://github.com/typeddevs/bashunit/blob/main/src/check_os.sh"
    click U6 "https://github.com/typeddevs/bashunit/blob/main/src/env.sh"
    click C1 "https://github.com/typeddevs/bashunit/blob/main/.env.example"
    click C2 "https://github.com/typeddevs/bashunit/tree/main/Makefile"
    click C3 "https://github.com/typeddevs/bashunit/blob/main/install.sh"
    click D1 "https://github.com/typeddevs/bashunit/tree/main/docs/"
    click D2 "https://github.com/typeddevs/bashunit/blob/main/README.md"
    click D3 "https://github.com/typeddevs/bashunit/tree/main/adrs/"
    click CD1 "https://github.com/typeddevs/bashunit/tree/main/.github/workflows"
    click T1 "https://github.com/typeddevs/bashunit/tree/main/tests/"
```
